AI Agent Support

Version 4.0 of sn-scriptsync brings native AI coding assistant support. Changes made by AI tools are automatically detected and synced to your ServiceNow instance.

Supported AI Tools

sn-scriptsync works with any tool that modifies files on disk:

• Cursor (with Claude, GPT-4, etc.)
• GitHub Copilot
• Windsurf
• Cline / Claude Dev
• Aider
• Any other AI coding assistant or external editor

How It Works

1. Automatic detection — File changes are detected via file system watcher
2. Smart batching — Changes are intelligently grouped and deduplicated for efficiency
3. Multi-field batching — Multiple field changes on the same record are combined into a single API call
4. Configurable delay — The syncDelay setting controls sync frequency (default: 30 seconds, set to 0 to disable)

Manual saves (Ctrl+S / Cmd+S) always sync immediately, bypassing the queue.

Pending Saves Queue

A tree view panel shows files waiting to sync:

• Pause/Resume queue functionality
• Sync Now button for immediate sync
• Remove individual files from the queue

AI Agent Instructions

When you start sn-scriptsync, an agentinstructions.md file is written to your workspace root. It contains guidelines for AI agents to work effectively with sn-scriptsync — file-structure patterns, Agent API documentation, and ServiceNow best practices.

Recommended: import or reference it instead of renaming. Keeping agentinstructions.md as the single source of truth lets the extension keep it up to date automatically when you upgrade. Point your tool's own rules file at it:

• Cursor → in .cursorrules (or a file under .cursor/rules/) add: Follow the rules in @agentinstructions.md
• Claude → in CLAUDE.md add: @agentinstructions.md
• GitHub Copilot → copy into .github/copilot-instructions.md (Copilot has no import; see auto-refresh below)
• Windsurf → copy into .windsurfrules (no import; see auto-refresh below)

Keeping the docs and skills up to date

agentinstructions.md and the on-demand skills under agentrules/skills/ are regenerated by the extension on every start and re-synced whenever their version is newer than the copy in your workspace. To pull the latest, update the sn-scriptsync extension and reload VS Code (or run ServiceNow ScriptSync: Enable). Renamed or removed skills are cleaned up automatically, and any file you authored yourself is never touched.

Prefer your own agent instructions?

If you maintain your own CLAUDE.md / AGENTS.md / .cursorrules and don't want the managed reference block added to them, set sn-scriptsync.agentInstructions.autoUpdate to false. The extension then stops injecting and refreshing that block inside your files — but still keeps agentinstructions.md and agentrules/skills/ current, so you can reference them on demand yourself (for example @agentinstructions.md, or point your agent at a specific agentrules/skills/<name>/SKILL.md).

Creating New Artifacts with AI

AI agents can create new ServiceNow artifacts by creating files in the correct folder structure:

{instance}/{scope}/{table}/{name}.{field}.{extension}

For example, to create a new Script Include:

myinstance/global/sys_script_include/MyNewUtils.script.js

The extension will automatically detect the new file, create the record in ServiceNow, and update _map.json with the new sys_id.

Agent API

For advanced integrations, sn-scriptsync exposes a programmatic Agent API so AI tools can drive ServiceNow directly. There are two transports for the same set of commands:

1. HTTP API (recommended) — a local HTTP server, the preferred, event-driven transport.
2. File-based API (legacy) — a folder queue of JSON files, kept for backward compatibility.

HTTP API (recommended)

When the extension starts it launches a local HTTP server bound to 127.0.0.1, preferring the fixed port 1977 (it falls back to a random free port only when 1977 is taken), secured with a per-session token. Send commands with a single POST /api call, passing the token in the X-Agent-Token header:

curl -s -X POST http://127.0.0.1:1977/api \
  -H "X-Agent-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "id": "chk_1", "command": "check_connection", "instance": "dev12345" }'

Connect any agent in two lines (Pro)

Everything above — file-watcher sync, agentinstructions.md, and the Agent API via the workspace port file — works free: agents inside your editor (Cursor, Copilot, or a CLI agent started in the sync workspace) need no license. Pro adds connect-from-anywhere for external terminal agents (Claude Code, Codex): a well-known per-user port file plus a paste-anywhere instruction snippet, so agents find ScriptSync without knowing the workspace.

Run sn-scriptsync: Copy agent connect instructions from the VS Code command palette (or click Connect an agent in the SN Utils helper tab; the block also appears in the helper tab's sync log when ScriptSync connects) and paste the snippet into any AI agent's instructions — a global CLAUDE.md, AGENTS.md, a Devin playbook, any system prompt. Requires an active SN Utils Pro, Trial, or Enterprise license in the connected browser (the global port file is only written then). The agent then needs no workspace files at all:

1. GET http://127.0.0.1:1977/api/instructions — full usage docs, served by the running extension itself (no auth), so they always match the installed version. GET /api/skills and /api/skills/<name> serve the on-demand skills the same way.
2. Token (and the actual port, if 1977 was taken): ~/.sn-scriptsync/agent-port.json.

Discovering the endpoint

The extension publishes the live endpoint to two places: ~/.sn-scriptsync/agent-port.json (well-known per-user location, readable from any directory, written with user-only permissions — Pro: only written while a Pro/Trial/Enterprise license is connected) and .vscode/sn-agent-port.json in your workspace (always written, free):

{
  "port": 1977,
  "token": "4f9a…hex…",
  "pid": 68861,
  "apiVersion": 7,
  "startedAt": 1730000000000
}

Treat these files as a hint and validate before trusting them — a copy can be stale after a crash or (the workspace copy) a machine move or cloud-sync. Do this every session and never cache the port/token:

1. Read port, token, and pid from ~/.sn-scriptsync/agent-port.json (fall back to .vscode/sn-agent-port.json on older versions).
2. Call GET http://127.0.0.1:<port>/api/health (no auth required).
3. Trust the endpoint only if the request succeeds (HTTP 200), health.pid matches the file's pid, and health.apiVersion is one you support.
4. If any check fails (no file, connection refused, pid/version mismatch), fall back to the file-based API.
5. Read the available commands from health.commands[] rather than hard-coding them.

curl -s http://127.0.0.1:1977/api/health
# → { "status": "success", "apiVersion": 7, "commands": [ … ], "pid": 68861 }

Request and response shape

Every authenticated request is a POST /api with a JSON body containing a command, an optional id (auto-generated if omitted), an optional instance, and command-specific params:

{ "id": "upd_1", "command": "update_record", "instance": "dev12345",
  "params": { "table": "sys_script_include", "sys_id": "…", "field": "script", "content": "gs.info('hi');" } }

Successful responses echo the id/command and carry a result:

{ "id": "upd_1", "command": "update_record", "status": "success",
  "result": { "success": true, "table": "sys_script_include", "sys_id": "…", "field": "script" },
  "timestamp": 1730000001235 }

Errors return status: "error" with a structured code:

{ "status": "error", "code": "E_BROWSER_DISCONNECTED", "error": "No browser helper tab is connected." }

Available Commands

The same commands work over both transports. The authoritative list for your installed version is always health.commands[].

Connection & sync

Records

Query

Local files

Browser

Browser debugger (CDP) — needs the Debug edition build + a Pro subscription, off by default

These commands drive the connected ServiceNow tab through the Chrome DevTools Protocol (chrome.debugger) for things the normal content-script bridge can't do — network bodies, console errors, beyond-viewport screenshots, and captured dialog text. They are an escalation: reach for the g_form / REST commands first.

A typical "why did that request fail?" loop:

start_network_capture  (urlFilter: "/api/now")
start_console_capture
→ run_ui_action / click_element / navigate   (reproduce the action)
stop_network_capture   (inspect status + response body)
stop_console_capture   (inspect client-side errors)

All browser-debugger commands share these error codes: E_PRO_REQUIRED, E_DISABLED, E_CDP_UNAVAILABLE, E_DEBUGGER_BUSY, E_NO_TAB, E_BROWSER_DISCONNECTED, E_TIMEOUT (plus E_NO_ELEMENT for capture_full_page with a selector).

File-based API (legacy)

Human Review Queue & Security Gates

Starting with ScriptSync 4.8.0 and SN Utils 10.1.7.5, high-risk agent operations and instance authorizations are governed interactively in the SN Utils ScriptSync Helper tab:

1. Two-Phase Human Review Queue

When an AI agent requests a high-impact operation (such as run_background_script or delete_record), the command is held in a Review Queue:

• An interactive review card appears in the helper tab with the code payload or delete target.
• A 5-minute expiry countdown timer starts, the page title alerts you, and the favicon flashes.
• You can inspect the operation, enter optional feedback, and click Approve once or Reject.
• If rejected or timed out, the agent receives an immediate, structured E_USER_REJECTED or E_REVIEW_EXPIRED response.

2. Per-Instance Security Permissions

In the helper tab's Instances & Permissions tab, you can toggle individual capabilities per instance:

• Scripts: Allow or disallow background script execution.
• Deletes: Allow or disallow deleting records via the API.
• Create: Allow creating new artifacts.
• REST Write: Allow direct REST record updates.

Toggles persist across sessions and synchronize live with connected agents and editor instances.

Standalone CLI & MCP Server (@snutils/snu)

AI agents outside VS Code (Claude Code, terminal agents, standalone scripts) can use the official @snutils/snu CLI and MCP server:

# Run standalone SN Utils agent commands
npx -y @snutils/snu@latest context
npx -y @snutils/snu@latest pull sys_script "nameSTARTSWITHincident" --limit 10
npx -y @snutils/snu@latest query incident "active=true" --limit 5
npx -y @snutils/snu@latest search "GlideRecord"

To use it as an MCP server in Claude Code, Cursor, Claude Desktop, or Windsurf, one command detects your installed AI tools and writes the configuration for you:

npx -y @snutils/snu@latest setup

Prefer to configure manually? snu setup --print shows the copy-paste blocks for every client, or add this entry yourself:

{
  "mcpServers": {
    "sn-utils": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "@snutils/snu@latest", "--mcp"]
    }
  }
}

The configuration is static and secret-free: the bridge port and auth token are discovered at call time from the local port file, so the same entry works for every user and machine, and a project-scoped config file is safe to commit and share with your team.

Security

Comprehensive security measures protect your workspace and ServiceNow instance:

• Interactive Human Review — High-impact actions require explicit developer approval in the browser helper tab before execution
• Per-Instance Access Control — Granular permission switches per connected ServiceNow instance
• Local-only HTTP server — bound to 127.0.0.1 (never exposed on the network), preferring fixed port 1977 with an ephemeral fallback
• Per-session token — every POST /api request must carry the X-Agent-Token: <token> header; the token is regenerated each session
• Pause switch — one click in the SN Utils helper tab blocks all incoming agent commands (E_PAUSED) while manual editor saves keep working
• Workspace boundary enforcement — All file operations are restricted to the local workspace with strict path containment checks