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 on a random free port, 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:<port>/api \
  -H "X-Agent-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "id": "chk_1", "command": "check_connection", "instance": "dev12345" }'

Discovering the endpoint

The extension publishes the live endpoint to .vscode/sn-agent-port.json in your workspace:

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

Treat this file as a hint and validate it before trusting it — it can be stale after a crash, a machine move, or cloud-sync (iCloud/OneDrive/git). Do this every session and never cache the port/token:

1. Read port, token, and pid from .vscode/sn-agent-port.json.
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:<port>/api/health
# → { "status": "success", "apiVersion": 2, "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)

The original transport is an event-driven folder queue — no HTTP, just JSON files:

• Write a request to {instance}/agent/requests/req_<id>.json
• The matching response appears in {instance}/agent/responses/res_<id>.json
• Processing is instant and event-driven (no polling), and parallel requests are supported
• Delete both files once you've read the response

// {instance}/agent/requests/req_chk_1.json
{ "id": "chk_1", "command": "check_connection" }

This transport stays available as a fallback (controlled by the sn-scriptsync.agentApi.fileFallback setting, enabled by default) so existing automations keep working. New integrations should prefer the HTTP API.

Upgrading from the file-based API

If you built automations against the file queue, here's how to move to the HTTP API:

1. Discover the endpoint — read .vscode/sn-agent-port.json and health-check it, instead of writing files into agent/requests/.
2. Switch the call — POST the same JSON payload ({ "id": ..., "command": ... }) to http://127.0.0.1:<port>/api with an X-Agent-Token: <token> header, and read the response from the HTTP body instead of polling agent/responses/.
3. Keep the helper tab open — unchanged; the browser tab still performs the ServiceNow work.
4. No rush — the file-based transport stays enabled by default, so nothing breaks if you migrate gradually. You can disable it later via sn-scriptsync.agentApi.fileFallback once everything is on HTTP.

The complete, always-current command reference also ships inside the extension as agentinstructions.md (the same file your AI agent reads). The sn-scriptsync GitHub repository holds the source and issue tracker.

Security

Comprehensive security measures protect your workspace and ServiceNow instance:

• Local-only HTTP server — bound to 127.0.0.1 (never exposed on the network) on a random free port
• Per-session token — every POST /api request must carry the X-Agent-Token: <token> header from .vscode/sn-agent-port.json; the port and token are regenerated each session
• Request ID validation — Alphanumeric with underscores/hyphens only
• Workspace boundary enforcement — All file operations restricted to the VS Code workspace
• Path traversal protection — File paths normalized and validated to prevent directory escapes
• Upload security — File path validation for attachment uploads
• Agent folder isolation — agent/ folders and .vscode/sn-agent-port.json are excluded from ServiceNow sync and git tracking