Treat ServiceNow code like real source code.

What is this, exactly?

SyncroNow AI is the next-generation successor to Sincronia — a CLI (and an MCP server) for managing ServiceNow scoped-application source code outside the platform. It takes a two-pronged approach: architecture, records, dictionary and other metadata stay managed in ServiceNow the normal way; your source code itself lives in a local project folder, under Git, built with the tools you already use.

Why teams pick SyncroNow AI

For teams deciding how to manage ServiceNow scoped-app code. SyncroNow AI is pre-1.0 and early — these are the honest trade-offs.

Honest gaps today: versus first-party tooling it still lacks OAuth/SSO in the MCP server, a support SLA, and a packaged distribution (Homebrew / Windows installer). These are the active priorities — see the roadmap.

Capabilities

A modern engineering workflow on top of ServiceNow — not just a file uploader.

Quick start

You need Node.js 22+ and a ServiceNow instance you can reach (a free Personal Developer Instance works great). On Windows, run everything inside WSL.

npm i -g @syncro-now-ai/core
syncrona login

npx syncrona init

npx syncrona dev

Prefer a per-project dev dependency? Use npm i -D @syncro-now-ai/core and call it with npx syncrona …. Optionally install the companion server scoped app for a few enhanced endpoints — the CLI works with or without it against plain REST APIs.

Commands

The full syncrona command surface. Run any of them with npx syncrona <command> (or just syncrona if installed globally).

Diff, dry-run and profiles

• --diff <branch> uses git diff against a branch. On push it pushes only changed files; on build it builds everything but records which files changed for a later targeted deploy.
• --dry-run previews effects without writing, on push, deploy, download and build.
• --instance-profile <name> selects profile env vars (SN_INSTANCE_<PROFILE>, SN_USER_<PROFILE>, SN_PASSWORD_<PROFILE>), falling back to base vars.
• --refresh-interval <seconds> tunes how often dev re-reads the manifest (default 30s; 0 disables polling).

Configuration

All configuration lives in sync.config.js in your project root. It controls where source lives, which files are tracked, and which build plugins run on them.

module.exports = {
  // Where your source files live and are watched in dev mode.
  sourceDirectory: "src",
  // Where local builds are written.
  buildDirectory: "build",
  // Plugin rules — MOST SPECIFIC match first; the first match wins.
  rules: [],
  // Tables/fields to exclude (on top of the built-in defaults).
  excludes: {},
  // Tables/fields to explicitly include (can override excludes).
  includes: {},
  // How often (seconds) dev mode refreshes the manifest.
  refreshInterval: 30,
};

Includes & excludes

Too many files, or some missing? includes and excludes are layered on top of sane built-in defaults. List those defaults with syncrona config show-defaults, then add overrides — and run syncrona refresh to apply.

module.exports = {
  excludes: {
    sys_scope_privilege: false, // turn the default exclusion back on
    my_cool_table: true,        // exclude this table entirely
    new_cool_table: { cool_script: true }, // exclude one field
  },
  includes: {
    sys_report: true, // force-include (overrides excludes)
    // treat a text field as a .js code file:
    special_code_table: { neat_script_field: { type: "js" } },
  },
};

Plugin rules

The rules array maps a filename regular expression to an ordered plugin chain. The result of each plugin is passed to the next, and only the first matching rule runs — so order your most specific patterns first.

rules: [
  { match: /\.secret\.ts$/, plugins: [] },     // matched → no plugins run
  {
    match: /\.ts$/,
    plugins: [
      {
        name: "@syncro-now-ai/typescript-plugin",
        options: { transpile: false }, // type-check only
      },
    ],
  },
],

Table options

tableOptions customises how records on a table map to folders: displayField names the record folder, differentiatorField disambiguates duplicate display values, and query is an encoded query that limits which records are tracked.

tableOptions: {
  some_table: {
    displayField: "some_field",
    differentiatorField: ["version", "sys_id"], // first non-empty wins
    query: "active=true",
  },
},

Build plugins

Plugins are where the power comes from. Each is a separate @syncro-now-ai/* package you install as a dev dependency and wire into a rule. Chains run in order, threading each plugin's output into the next.

Supporting presets — @syncro-now-ai/babel-preset-servicenow and @syncro-now-ai/babel-plugin-remove-modules — adapt modern output for the ServiceNow runtime.

Credentials & authentication

Authenticate with a dedicated least-privilege integration user over HTTPS. HTTP Basic is the default; OAuth 2.0 is supported in the CLI.

Where credentials live

The global credential store writes each instance to ~/.syncrona/credentials/<instance>.enc, encrypted with AES-256-GCM. The encryption key is resolved with this precedence:

OAuth 2.0

Set SN_OAUTH_CLIENT_ID and SN_OAUTH_CLIENT_SECRET (alongside SN_USER / SN_PASSWORD, optionally with per-profile _<PROFILE> suffixes) and the CLI exchanges them for a Bearer token at oauth_token.do, refreshing on expiry or 401. Without those vars it stays on Basic.

MCP server

The bundled Model Context Protocol server (@syncro-now-ai/mcp-server) lets an MCP-capable AI client — Claude Desktop, Claude Code, VS Code Chat — analyse and operate your scope: session & scope control, metadata inventory, dependency and impact graphs, static script analysis, drift detection and scoped documentation, behind guardrails and dry-run.

Register it with your client

Run npx syncrona mcp to start the server and optionally write local client config (.vscode/mcp.json, .syncrona-mcp/secrets.json), or register it directly:

{
  "mcpServers": {
    "syncrona": {
      "command": "npx",
      "args": ["-y", "@syncro-now-ai/mcp-server"]
    }
  }
}

Tool families

59 tools, grouped by what they do. Expand a family to see the tools inside.

Workflow

SyncroNow AI manages your scope asymmetrically: source code is owned locally; everything else (tables, dictionary, config records, metadata) stays managed in ServiceNow and moves with your usual update-set / deploy process.

File structure

Downloaded code is laid out one folder per record:

project_folder/
  src/
    table_name/
      record_name/
        field_name.extension

Records are folders because one record can hold multiple code files. Because the folder is named by the record's display value, never have two records with the same display value in the same table — or use differentiatorField to keep them apart.

Day-to-day

• Add a record: create it in ServiceNow, run syncrona refresh — files appear automatically.
• Edit code: run syncrona dev and just save; builds push on save.
• Delete: stop dev mode, delete the record in ServiceNow, syncrona refresh, then remove the files (deliberately — deletion is never automatic).
• Ship: syncrona push (or build + deploy) for the whole scope, or push --diff main for just your feature's edits.

Security & safety

• Least-privilege by default. Use a dedicated integration user with only the roles your scope needs; never your admin account.
• Encrypted credential store. AES-256-GCM at rest; key from an explicit secret, the OS keychain, or a machine-derived fallback. Configure a real key for at-rest protection — see Credentials.
• Dry-run everything risky. --dry-run previews push, deploy, download and build; the MCP server gates writes behind confirmation and dry-run.
• Destructive ops confirm first. download overwrites local files but asks before doing so (--ci skips the prompt) — keep source in Git so a bad download is a git checkout away.
• Secrets stay out of Git. Ignore .env and node_modules; for CI, source SYNCRONA_STORE_KEY from a secrets manager or use plain env vars instead of the on-disk store.

Architecture

A Node 22 monorepo of 13 @syncro-now-ai/* packages. Two ServiceNow clients — the core CLI and the MCP server — share one transport policy (sn-transport) and one encrypted credential store, so authentication, scoped-API resolution and retry behaviour are identical across both.

CLI commands are declared one entry at a time in a registry, and MCP tool families likewise — the orchestrators are generic interpreters, so adding a command or a tool family is a contained, contract-checked change. Quality gates (type-check, lint, dependency-cruiser module boundaries, tests) run via npm run check.

Full detail: docs/ARCHITECTURE.md.

FAQ

Is SyncroNow AI affiliated with ServiceNow?

No. It is an independent, third-party tool, not affiliated with, endorsed by or sponsored by ServiceNow, Inc. "ServiceNow" is a trademark of ServiceNow, Inc., used here only to indicate compatibility.

Why the package name @syncro-now-ai/*?

The project ships under the @syncro-now-ai npm scope (the CLI is @syncro-now-ai/core, exposing the syncrona command); the GitHub repository is IvanBBaev/syncrona. It is the modern successor to Sincronia / sinc.

Does it work without installing anything on the instance?

Yes. The CLI talks to standard ServiceNow REST / Table APIs and works with or without the optional companion scoped app — which only enables a few enhanced endpoints. It is broadly release-agnostic; if you hit a release-specific issue, open an issue with your instance version.

How is this different from ServiceNow's native Git?

Native Git moves your code into Git. SyncroNow AI moves your workflow into modern engineering: a local build pipeline, a multi-scope CLI you run from your own editor, and an AI / MCP layer that understands your scope's metadata and dependencies. See How it compares.

Does it run on Windows?

On Windows, WSL is currently required (Ubuntu, build 1903+) — run every syncrona command inside the WSL shell. Native Windows support (PowerShell install, Windows Credential Manager) is on the roadmap; macOS and Linux are first-class.

Can I work with multiple instances or scopes?

Yes. Use the encrypted global store (syncrona login / use / instances) or instance-profile env vars with --instance-profile to route a single command at dev, test or prod. For several scoped apps in one repo, treat each scope as its own project under packages/ and run commands from the scope directory.

Is it production-ready?

It is pre-1.0 and early. The engineering is solid — type-checked lint, enforced module boundaries, tests and a security model — but review the security model for your own deployment, and keep your source in Git. Track progress in the roadmap.