--- title: Sync config to other AI CLIs (in development) --- # Sync config to other AI CLIs (in development) ## What it is A first-party Omniscio feature that takes the setup you already manage inside Omniscio — your **custom MCP servers**, your **agent instructions**, and your actual **skills** — and installs it into the _other_ AI coding CLIs on your machine: **Codex, Gemini, OpenCode, and Cursor**. Configure a tool once in Omniscio and your configuration follows you into every tool, even when you use those tools outside Omniscio. It is **experimental / in-development and hidden by default**, and it stays that way because it is gated through the unreleased-feature registry (`provider-config-sync`), **not** a plain feature flag — a developer has to flip its status to `shipped` before it becomes generally visible (see Omniscio’s unreleased-feature (“Lab”) gate). You turn it on in **Settings → Lab → "Sync config to other AI CLIs"**, or with `AMC_SHOW_PROVIDER_CONFIG_SYNC=1` in dev. For skills this means **real portability**: Omniscio copies each skill's whole `SKILL.md` folder (its scripts and reference files too) into the other tool's skills directory, so the skill is actually _runnable_ there — not just a read-only list of skill names. (The earlier name+description index is retired.) The skill copies stay **live** (when skills sync is on, editing a skill in `~/.claude/skills` gets re-synced to the other tools by a lightweight background pass the next time you start a session — throttled, never a constant file-watcher — and they're real copies, not fragile symlinks) and are **edit-protected** (if you hand-edit a synced copy _inside another tool_, Omniscio leaves it alone and flags it rather than overwriting your change — the same safety the `CLAUDE.md → AGENTS.md` mirror has). Both run on one shared "mirror engine" that powers the instructions sync too. This is the **opposite direction** from Omniscio's normal MCP behavior. Normally Omniscio delivers MCP servers **per-session**, writing a private per-session `.mcp.json` (under Omniscio's data dir, never your project folder) only for the Claude sessions Omniscio itself spawns — it deliberately never touches a tool's _global_ config (see [mcp-servers.md](mcp-servers.md)). This feature is a separate, opt-in **machine-sync** path that pushes a _flagged_ subset of that same registry out to each installed tool's own global config. The per-session path is left completely untouched. ## Where to find it Everything is reached from **Settings**. The master switch is the **Lab** section's **"Sync config to other AI CLIs"** toggle. The feature's own panel has **no permanent sidebar row while it is experimental**, so you open it with the **Settings search box** at the top of Settings — type _"sync config"_ or _"mcp sync"_ and open the **"Sync Config to Other AI CLIs"** panel from the results. That panel is where the target tools, the per-server sync toggles, the instructions and skills switches, the Cursor project-folder picker, the background auto-sync switch and the **Sync now** button all live. ## How it behaves ### How to use it 1. **Enable it:** Settings → Lab → toggle **"Sync config to other AI CLIs"** on. 2. **Open the panel:** use the Settings search box (top of Settings) and type _"sync config"_ or _"mcp sync"_ — open the **"Sync Config to Other AI CLIs"** panel. (The panel has no permanent sidebar row while the feature is experimental; search is how you reach it.) 3. **Pick target tools:** check the tools you want to sync into. Only tools that are actually installed on your machine are selectable; the rest show _"not installed"_ and are disabled. 4. **Choose which MCP servers to sync:** each of your custom MCP servers gets a per-server **"sync to machine"** toggle. A server that contains a **secret** (an environment variable value or an auth header) **cannot** be synced — it's shown disabled with a lock and a "Contains a secret — not synced" note. This is deliberate: Omniscio never writes one of your secrets into another tool's plain-text config file (some of those, like Gemini's, can even sync up to a cloud account). 5. **Optionally** turn on **Sync instructions** (mirror your agent instructions into each tool's global instructions file — written into a clearly-marked managed block so your own edits around it are preserved) and **Sync skills** (really install your skills as runnable folders — see _What gets written where_ below). 6. **If you target Cursor:** because Cursor has no machine-wide skills folder (unlike the others), a **Cursor project-folder picker** appears — add the project folders you want your skills installed into (each gets a `.cursor/skills/` folder). The picker only shows when Cursor is a target. 7. **Optionally** turn on **Auto-sync in the background** to re-sync automatically about every 6 hours instead of only on demand. 8. Click **"Sync now"** to run a full sync immediately. You'll see a per-tool result: how many servers were **added**, **already present**, **skipped (secret)**, or **failed**, plus the instructions status and a skills tally (**copied** / **unchanged** / an amber **edited** count for any copy you changed in the other tool / **removed** for copies pruned because their skill is gone / **skipped** / **failed**, or _already available_ for OpenCode). Everything is **off by default**. With the feature disabled, Omniscio behaves exactly as before — nothing is written to any other tool. ### What gets written where - **MCP servers** — installed into each tool's **global** MCP config: - **Claude, Codex, Gemini** — via that tool's own `mcp add` command (user/global scope). - **Cursor** — merged into `~/.cursor/mcp.json`. - **OpenCode** — merged into `~/.config/opencode/opencode.jsonc`. - **Grok** — nothing is written. Grok reads `~/.claude.json` itself through its Claude Code compatibility layer, so it already has every server Claude has; pushing them again would list each one twice. - **Instructions** — a managed block written into each tool's global agent- instructions file: Codex (`~/.codex/AGENTS.md`), Gemini (`~/.gemini/GEMINI.md`), OpenCode (`~/.config/opencode/AGENTS.md`), Grok (`~/.grok/AGENTS.md`). Claude is the _source_ of the instructions, and Cursor has no global instructions file, so neither gets one. Omniscio writes exactly ONE block and strips any older duplicate it left behind before (an internal marker-format change once orphaned a stale second block). - **Skills** — your actual skill folders (the `SKILL.md` plus any `scripts/` and `references/`), copied into each tool's skills directory: - **Codex** → `~/.agents/skills/` (Codex's documented user-scope skills dir). Codex ALSO scans `~/.codex/skills/`, so Omniscio removes its OWN earlier copies from there as well — otherwise Codex would list every synced skill twice. Only Omniscio-made copies (those carrying the `.amc-synced.json` marker) are removed; Codex's built-in skills and anything you installed yourself are left untouched. - **Gemini** → `~/.gemini/skills/` - **Cursor** → a `.cursor/skills/` folder inside each project folder you picked - **OpenCode** already reads your `~/.claude/skills` natively, so nothing is copied — its row shows _already available_. - **Grok** also reads your `~/.claude/skills` natively (its Claude Code compatibility layer treats that folder as one of its own skill roots), so nothing is copied and its row shows _already available_ too. This holds even though Omniscio gives each managed Grok account its own isolated `GROK_HOME` — that isolation moves `~/.grok`, not your home folder, so your skills still reach it. Grok's own built-in skills in `~/.grok/skills` (`check-work`, `code-review`, `create-skill`, `docx`, `help`, `imagine`, `pptx`, `xlsx`) are never touched, and are deliberately never pulled into your library — they belong to Grok alone. - **Claude** is the _source_, so it is never a copy target. Every copied folder carries a small `.amc-synced.json` marker so Omniscio only ever manages copies it made — a skill you (or another tool) created with the same name is left untouched and reported as _skipped_. All your installed skills are included (your own plus any from plugins). The sync is **safe by construction**: - **Additive + idempotent** — it only _adds_ servers a tool is missing and only copies new or changed skills, so it never touches anything you configured yourself, and running it twice changes nothing. The one exception is removal propagation (below): a skill you delete from the canonical store has its synced copies pruned too. - **Never clobbers your own skills** — a same-named skill folder Omniscio didn't create is left untouched (reported _skipped_); each skill is copied atomically (staged, then swapped in — never half-written). The only folders Omniscio ever deletes are its **own** marker-verified copies: its old duplicates from Codex's secondary skills root (so a skill isn't delivered twice) and, via removal propagation, the copies of a skill you've removed from the canonical store — never a folder you own. - **Removal propagates** — when a skill leaves the canonical store (you uninstall a plugin or delete the skill), its synced copies in every target tool are pruned on the next sync run and reported as **removed** on that tool's row, so no stale copies are left behind. Only Omniscio's own copies (carrying the `.amc-synced.json` marker) are ever pruned; a foreign folder with the same name is left untouched. - **Edit-protected** — if you hand-edit a skill copy Omniscio made (inside Codex, Gemini, or a Cursor project), Omniscio detects it diverged and reports it as **edited** instead of overwriting your change. The copies it made and you left alone still refresh normally when you change the original. - **Live** — with skills sync on, an edit to a skill in `~/.claude/skills` is picked up by a lightweight background re-sync the next time you start a session (throttled to at most once every ~10 minutes, and collapsed to a single run even for a burst of edits), so you rarely need to click _Sync now_ or wait for the 6-hour pass. - **Secret-clamped** — a secret-bearing server is never written out (see step 4). - **Fail-soft** — if one tool (or one skill) errors, the rest still sync; the failure is shown on that tool's row. - **Times out safely** — if a tool is slow to list its current servers, Omniscio skips that tool for the run rather than risk re-adding duplicates. ### Project context via the Omniscio broker (pilot) Alongside the config sync above, Omniscio can register its own small **`amc-broker`** MCP server into a tool so that tool can pull **read-only project context** Omniscio is the authority for — which Omniscio project a repo belongs to, its `CLAUDE.md` instructions, its `MEMORY.md` index, and a list of its `docs/`. This is an early **pilot**, deliberately narrow: - **Two tools only for now** — the broker is installed into **Codex** (via its `mcp add`) and **Cursor** (merged into `~/.cursor/mcp.json`). Gemini and OpenCode are not part of the pilot yet. - **Read-only** — the broker never writes anything. It identifies the project by the **real folder path** you're working in (not a value the tool supplies) and returns a clean "not managed by Omniscio" answer outside an Omniscio project. - **Project context first** — the pilot ships read-only context tools (`amc.ping`, resolve-project, read-instructions, read-memory, list-docs). Secret-bearing proxying is **deferred** to later phases. (Skills portability is already done, but via the direct folder copy above — not through the broker.) - When **Sync instructions** is on, the synced instructions also carry a short note that the `amc-broker` may be available — Omniscio stays the authoritative source. You don't configure the broker separately: it's installed as part of a normal **Sync now** run for Codex/Cursor, and the per-tool result row shows a **Broker** status (written / unchanged / skipped / error) next to Instructions and Skills. ## For agents - **Storage:** reuses the existing custom-MCP-server registry (the `mcp_servers` table) plus one new per-server column, `sync_to_machine`. The per-session MCP orchestrator never reads that column — machine-sync is a fully separate path. Read via `listMachineSyncCandidates()`; flagged via `setMcpServerSyncToMachine()`. - **Engine:** `src/main/services/provider-config-sync/` — a pure `reconcile.ts` (slug/argv/diff/managed-block helpers), a dependency-injected `sync-engine.ts` (the secret-clamp / list-timeout-skip / additive / fail-soft logic), a `provider-registry.ts` data table (per tool: CLI-mode vs file-merge-mode + config paths), `run-cli.ts` (wraps Omniscio's safe `spawnCliChild`), `file-mcp.ts` (Cursor/OpenCode config-file merge), and `service.ts` (the single-flight orchestrator). The per-provider work it orchestrates lives in three focused helpers: `sync-mcp.ts` (the per-tool MCP reconcile — CLI and file-merge modes), `sync-managed-blocks.ts` (writes the instructions managed block and removes any legacy skills-index block), and `sync-skills.ts` (the skills adapter — it dedupes by folder name then reconciles each skill through the **shared mirror-sync engine** at `src/main/services/mirror-sync/`, the same classify-write machinery the instructions sync uses; the engine's folder strategy does the recursive atomic copy + `.amc-synced.json` own-marker non-clobber + marker-excluded change detection, and now also flags a copy you edited in the other tool as `drift`). Liveness is `skills-activity-refresh.ts` — a throttled (~10 min), fire-and-forget re-sync kicked from the session-spawn hand-off. A CLI reads skills only at spawn, so there is no filesystem watcher: the old always-on `MirrorWatcher` over the skill roots was **removed 2026-07-08** after it fanned out to ~3,700 native `fs.watch` handles and pinned ~2 CPU cores in kernel-mode (see mirror-sync-engine-contract). It is gated on the feature + skills-sync toggles, reconcile = a single-flight `runProviderConfigSync`. `auto-service.ts` is the 6-hour background tick; "Sync now" is the manual path. Registered in `startup/registry.ts` and self-gated on settings. - **Broker:** `src/main/services/amc-broker-mcp-server/` — a standalone stdio MCP server (bundled to `out/mcp/amc-broker-server.js`) that reads Omniscio's database read-only to map a repo path → project, then serves read-only context. It's registered by the same `service.ts` run for the pilot tools (Codex/Cursor); its DB path is passed on the command line, never as a secret. - **Settings:** flat `AppSettings` fields — `providerConfigSyncEnabled` (the gate), `providerConfigSyncTargets[]`, `providerConfigSyncInstructions`, `providerConfigSyncSkills`, `providerConfigSyncAuto`, and `providerConfigSyncCursorProjectDirs[]` (the Cursor project folders skills are copied into). - **IPC:** `provider-config-sync:run`, `:get-status`, `:detect-targets`, `:set-server-flag`. - **UI:** `ProviderConfigSyncSettings.tsx` + `provider-config-sync-store.ts`. The Settings section is registered `DEEP_LINK_ONLY` (search/deep-link reachable, no nav row) and gated via `isUnreleasedFeatureVisibleInRenderer('provider-config-sync', …)`. A Cursor project-folder picker (reusing the `dialog:open-folder` IPC) shows only when Cursor is a target; each result row shows a skills-copy tally. ## Related The servers this feature syncs _from_ — and the per-session delivery it is the exact opposite of — are described in [mcp-servers.md](mcp-servers.md), which is the page to read first if you are unsure which of the two paths you want. The sibling mirror that pushes project instructions from CLAUDE.md out to AGENTS.md is [agent-instructions-sync.md](agent-instructions-sync.md), and it shares the same mirror engine. The skills being copied are the ones covered by [use-skills.md](use-skills.md), so learn how skills work there before deciding to spread them across tools. Nothing else in the product keeps an unreleased feature hidden the way this one is hidden, so if you are wondering why you cannot find a sidebar row for it, the answer is the unreleased-feature gate this page describes. For the invariants and the tests that lock them, read [.claude/memory/contracts/provider-registry-contract.md](../../.claude/memory/contracts/provider-registry-contract.md).