Generate output (sync)

sync

Emit per-target configs.

agnostic-ai sync --only claude,cursor

sync --global details:

• Loads overrides from local/ in the source root. Reads targets from an optional agnostic-ai.yaml there. See global configuration and global output.
• Works outside a project; never loads project config or packs.
• Accepts --target, --only, --except, --dry-run, --check, --check --diff, --backup, --plan, and --json. --plan lists each file a sync would create, update, or delete, with key-level settings and MCP edits. --json adds a keys list per settings or MCP file.
• MCP specs install servers in the user MCP files of Augment, Claude, Codex, Cursor, Copilot, Gemini, OpenHands, and Qoder. Settings specs set model and effort for Claude, Codex, Copilot, Qoder, and Gemini. See default model and effort.
• Rejects --watch, --gitignore, --jobs, and --plan with --check or --dry-run.

Paths listed under sync.unmanaged are skipped and reported as ~ skip (unmanaged) <path>.

Summary. sync ends with what it changed. With nothing to do it prints ✓ 25 targets up to date · 49ms. After an edit it names the changed specs, then the files created (+), updated (~), and removed (-):

  ~ rule testing → 9 files in 9 targets
  + .cursor/rules/testing.mdc  .kiro/steering/testing.md  (+1 more)
  ~ AGENTS.md  CLAUDE.md  GEMINI.md  (+2 more)
  ! 1 file to commit: .openhands/setup.sh
✓ synced 25 targets · 3 created · 6 updated · 49ms

Each list shows three paths; -v lists all. config in the spec line means agnostic-ai.yaml changed. The ! line lists changed files git tracks or does not ignore, and is absent outside a git repository.

Tracked despite ignored. A generated path git already tracks, typically committed before it moved into the managed .gitignore block, prints ! 1 file tracked despite being ignored: git rm --cached .claude/rules/tone.md. sync --untrack runs that command for every such path and reports ~ untracked <path>. doctor shows the same finding and never fails on it alone.

Orphan sweep. sync records every file it writes in .agnostic-ai/.sync-state. A full run deletes files it no longer emits and prunes empty directories, but only what it can prove it wrote (provenance header or recorded hash). A file edited since is kept as ~ kept orphan <path> and counts as drift until you delete it or list it under sync.unmanaged.

Without .sync-state (a fresh checkout of a repo that commits generated files), sync --check and doctor scan git-tracked files instead. A tracked file is a leftover when it sits where a configured target writes and its first line carries the provenance header. A plain full sync removes none of them; it records them under target unledgered and lists each as ~ kept leftover <path>. --only and --except record them without naming them. An empty .sync-state still counts as a ledger and turns this scan off. doctor --fix removes a leftover in a tool directory or root dotfile. Delete a scope document such as services/api/AGENTS.md by hand or add it to sync.unmanaged.

First-sync target picker

On the first sync (no .agnostic-ai/.sync-state yet), if the config still lists every supported target, sync asks which to keep. The choice is saved to agnostic-ai.yaml.

echo "claude,codex" | agnostic-ai sync keeps two targets.

Reading a failing --check

A drifting --check exits non-zero in every format. A file still holding what the last sync wrote is reported as out of date (the specs changed). A file whose bytes changed since is reported as edited locally (the next sync overwrites it). Without a record of the last sync, as in a fresh CI checkout, a changed file reads as out of date. Stderr names the fix, agnostic-ai sync, and points at agnostic-ai doctor.

• --diff prints changed lines. A missing file gets a one-line create summary; a large diff truncates with a count.
• --format=github emits ::error file=...,line=...:: annotations on the pull request.

Neither has a config-file key.

Watch mode

sync --watch watches agnostic-ai.yaml, agnostic-ai.local.yaml, .agnostic-ai/AGNOSTIC_AI.md, every sources.* directory, .agnostic-ai/local/, and .agnostic-ai/overlays/, including ones that appear later. It uses fsnotify with a 50 ms debounce, polls every 200 ms where fsnotify fails, and exits on Ctrl+C. A spec change re-syncs only targets that emit that kind. Config and overlay edits, deletes, and renames re-sync everything.

Parallel emission

sync emits each target on its own worker; --jobs <n> bounds how many run at once. There is no config-file key. Output never depends on the value. Use --jobs 1 only to debug or pin ordering.

Profiling a slow sync

--profile <file> or AGNOSTIC_AI_PROFILE=<file> writes a CPU profile. --verbose adds wall time per target, as in → claude: 12 created, 3 updated, 0 unchanged in 42ms. Under --jobs > 1 these times overlap: read them as per-adapter cost, not a serial breakdown.

JSON output

sync --json, sync --plan --json, sync --dry-run --json, and sync --check --json share one schema:

writes and skipped entries have target, path, action (strings), and bytes (number), for example {"target": "claude", "path": "CLAUDE.md", "action": "create", "bytes": 1284}.

--plan --json and --dry-run --json write nothing and exit 0. Each leftover they would remove is "delete" in writes; kept files are "orphan" or "leftover" in skipped. --dry-run --json also lists every unchanged output as "skip". Count writes by target for the per-target numbers --plan prints.