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 automatically copied to your workspace root. Rename it based on your AI tool:

• Cursor → .cursorrules
• Claude → CLAUDE.md
• GitHub Copilot → .github/copilot-instructions.md
• Windsurf → .windsurfrules

This file contains guidelines for AI agents to work effectively with sn-scriptsync, including file structure patterns, Agent API documentation, and ServiceNow best practices. You can expand it with your own project-specific instructions.

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.

File-based Agent API

For advanced integrations, sn-scriptsync exposes a file-based API. AI agents can interact programmatically via an event-driven folder queue — no npm packages, no HTTP servers, just JSON files.

How It Works

• Requests go to agent/requests/ as req_<id>.json
• Responses appear in agent/responses/ as res_<id>.json
• Processing is instant and event-driven (no polling)
• Parallel requests are supported

Available Commands

Example Request

{
  "id": "check_1",
  "command": "check_connection"
}

See the sn-scriptsync GitHub repository for full Agent API documentation.

Security

Comprehensive security measures protect your workspace and ServiceNow instance:

• 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 are excluded from ServiceNow sync and git tracking