Ai Config Sync Manager

AI Config Sync Manager

Continuous bidirectional sync between Claude Code and Codex — round-trip lossless, not a one-shot migrator.

Highlights

• Continuous bidirectional sync — claude → codex and codex → claude, run as often as the two hosts drift; not a one-shot migration.
• Strict YAML round-trip — Claude lenient YAML and Codex YAML 1.2 strict frontmatter both preserved across repeated syncs without loss or oscillation.
• Diff-first workflow — status to compare → sync --dry-run to preview → --apply to write.
• Risk-tagged operations — permissions, hooks, custom commands labeled safe / partial / manual.
• Backup-on-write — every overwrite snapshotted under .backups/, FIFO retention (30).
• Apply ledger — every --apply writes a per-item sha256 attestation (before/after hash, backup path) to ~/.ai-config-sync-manager/ledgers/.
• Selector syntax — --include skills:code-writer,instructions --exclude mcp style filtering.
• Native semantic mapping — Claude Write → Codex sandbox_mode = "workspace-write", etc.
• Prose-level token rewriting — Claude-only tokens (Read, Bash, TaskCreate, headless claude -p) and Codex-only tokens (spawn_agent, codex exec) auto-translate across hosts and round-trip back.
• Zero runtime dependencies — single ESM file, Node built-ins only.
• Thin host plugins — /config-manager:* for Claude, config-manager-* for Codex.

Why this exists

Claude Code and Codex use the same concepts (instructions / skills / mcp / permissions / hooks) but in different files, formats, and names:

| Concept | Claude | Codex | |---|---|---| | Instructions | ~/.claude/CLAUDE.md | ~/.codex/AGENTS.md | | Skills | ~/.claude/skills/ | ~/.codex/skills/ | | Settings | ~/.claude/settings.json | ~/.codex/config.toml | | MCP | ~/.claude/.mcp.json | [mcp_servers.*] in config.toml |

Hand-rolling the sync invites drift, semantic loss, and accidental secret leaks. This CLI keeps the two hosts aligned while preserving host-native meaning.

This tool is built for two hosts in continuous use — where drift accumulates daily and round-trip integrity matters across repeated syncs — not for a one-shot, one-way migration.

One-shot migrators typically copy Claude-only vocabulary (tool names like Read / Bash, prose like Use the Bash tool, in-line Agent({...}) calls) into the generated file as prompt guidance and flag it for manual review. This CLI instead auto-rewrites those tokens to their host equivalents (Read → workspace-write, TaskCreate → spawn_agent, claude -p → codex exec, …) and round-trips them back when syncing the other direction — so the same content stays correct for both hosts with no manual fix-ups.

Quick Start

npm install -g ai-config-sync-manager
ai-config-sync connect           # register the plugin for any detected host (Claude / Codex)
ai-config-sync status            # show drift across global + project scopes
ai-config-sync sync              # preview changes (--dry-run by default)
ai-config-sync sync --apply      # apply with automatic backups

connect only registers plugins for hosts it actually finds (~/.claude for Claude, ~/.codex or ~/.agents for Codex). Hosts that are missing are reported as skipped and no directories are created — install the host first, then rerun connect.

Requirements

• Node.js ≥ 20
• Claude Code and/or Codex CLI installed (host plugins are auto-registered by connect when the matching host directory exists)

Table of Contents

| Category | Sections | | --- | --- | | Commands | [Bundled CLI](#bundled-cli) · [Host plugin commands](#host-plugin-commands) · [Flags](#flags) | | Workflow | [Selector syntax](#selector-syntax) · [Ignore rules](#ignore-rules) · [Sync direction](#sync-direction) · [Scopes](#scopes) | | Safety | [Safety defaults](#safety-defaults) · [Risk levels](#risk-levels) · [Retention](#retention) | | Mapping | [Native mapping](#native-mapping-claude--codex) · [Areas](#areas) · [Paraphrase](#paraphrase) · [Hidden markers](#hidden-markers) · [Unsupported](#unsupported) | | Reference | [Install resolution](#install-resolution) · [Local dev](#local-dev-from-this-repo) · [Gotchas](#gotchas) · [API surface](#api-surface) · [What's next](#whats-next) |

Commands

Bundled CLI

After npm install -g, the same binary is on PATH as ai-config-sync — equivalent to ./bin/ai-config-sync.mjs from a source clone.

ai-config-sync connect
ai-config-sync status
ai-config-sync status --json
ai-config-sync status --scope global
ai-config-sync status --scope project
ai-config-sync status --include skills:code-writer,instructions --exclude mcp
ai-config-sync sync --dry-run
ai-config-sync sync --scope project --dry-run
ai-config-sync sync --scope global --apply
ai-config-sync sync --include instructions,skills:code-writer --exclude mcp --dry-run
ai-config-sync sync --from claude --to codex
ai-config-sync sync --from codex --to claude
ai-config-sync reference
ai-config-sync paraphrase

| Command | Purpose | | --- | --- | | connect | Detect installed hosts and register the matching plugin | | status | Compare global + project config across both hosts | | status --json | Machine-readable diff | | sync --dry-run | Preview the merge plan without writing | | sync --apply | Apply the plan, snapshot to .backups/ | | reference | Emit / persist a self-generated markdown reference | | paraphrase | Line-level override archive for instruction wording |

Host plugin commands

| Host | Connect | Status | Sync | Paraphrase | | --- | --- | --- | --- | --- | | Claude | /config-manager:connect | /config-manager:status | /config-manager:sync | /config-manager:paraphrase | | Codex | config-manager-connect | config-manager-status | config-manager-sync | config-manager-paraphrase |

Flags

Per-subcommand flag reference, mirroring --help output. Shared flags (--include / --exclude / --scope / --map) get a one-line summary; full syntax lives in the linked section.

connect

| Flag | Description | | --- | --- | | -h, --help | Show connect help |

ai-config-sync connect

status

| Flag | Description | | --- | --- | | --json | Print the full status report as JSON | | --compact | One compact line per diff entry | | --tree | Scope/area/item tree output | | --scope global\|project\|all | Limit scope (default: all = global + project) | | --include area[:item][,...] | Include selector — see [Selector syntax](#selector-syntax) | | --exclude area[:item][,...] | Exclude selector — see [Selector syntax](#selector-syntax) | | -h, --help | Show status help |

ai-config-sync status --scope project --tree --include skills:code-writer

sync

| Flag | Description | | --- | --- | | --dry-run | Preview without writing (default; mutually exclusive with --apply) | | --apply | Apply with backups | | --plan-json | Print the sync plan as JSON | | --ledger-json | Print the apply ledger as JSON to stdout (--apply only) | | --ledger | Write the apply ledger JSON to ` (--apply only) | | --from claude\|codex | Source host (overrides AICONFIGSYNCHOST) | | --to claude\|codex | Target host (overrides AICONFIGSYNCHOST) | | --scope global\|project\|all | Limit scope (default: all = global + project) | | --include area[:item][,...] | Include selector — see [Selector syntax](#selector-syntax) | | --exclude area[:item][,...] | Exclude selector — see [Selector syntax](#selector-syntax) | | -h, --help` | Show sync help |

When --from / --to are omitted, direction follows [Sync direction](#sync-direction).

ai-config-sync sync --scope project --include mcp:notion --apply

reference

| Flag | Description | | --- | --- | | --output | Write the reference markdown to ` (parent directories created) | | -h, --help` | Show reference help |

ai-config-sync reference --output ~/.ai-config-sync-manager/reference.md

paraphrase

| Flag | Description | | --- | --- | | --apply | Rewrite files + register overrides + persist new map entries (default: dry-run) | | --register | Skip rewriting; only register overrides where the effective map already equates both sides — see [Paraphrase](#paraphrase) | | --map token=paraphrase[,...] | Inline token-to-paraphrase pairs (free-form prose accepted) — see [--map syntax](#--map-syntax) | | --non-interactive | Skip TTY prompts for tokens missing from paraphrase-map.json | | --json | Print the result as JSON | | --scope global\|project\|all | Limit scope (default: all = global + project) | | --include area[:item][,...] | Include selector — see [Selector syntax](#selector-syntax) | | --exclude area[:item][,...] | Exclude selector — see [Selector syntax](#selector-syntax) | | -h, --help | Show paraphrase help |

ai-config-sync paraphrase --map "Read=read the file,Write=write to the file" --apply

Selector syntax

--include narrows the plan first, then --exclude removes matches. Both accept area or area:item syntax; itemized areas (skills, permissions, hooks, agents, mcp, commands) accept glob items.

ai-config-sync sync --include skills:code-writer,instructions --exclude mcp --dry-run
ai-config-sync sync --include "permissions:Write*" --exclude "permissions:Bash(rm:*)" --dry-run

Areas

| Area | Itemized? | Apply granularity | | --- | --- | --- | | instructions | — | file merge | | skills | yes | per skill | | agents | yes | per agent | | mcp | yes | per server | | permissions | yes | item-by-item patch | | hooks | yes | item-by-item patch | | commands | yes | per command | | plugins | yes | status only (read-only diff; sync skips this area) |

Ignore rules

Persistent ignore lives at one of:

• /.ai-config-sync-manager/status-ignore.json (project scope, checked first)
• ~/.ai-config-sync-manager/rules/status-ignore.json (global)

Each exclude entry is a string selector (area:item or path glob) or an object whose fields combine with AND. term is a line-level mask — lines containing the substring are removed from both sides before the diff, so the conflict can disappear without hiding unrelated changes.

{
  "version": 1,
  "exclude": [
    "skills:legacy-skill",
    "permissions:Bash",
    "~/.codex/agents/archive-*.toml",
    { "scope": "global", "area": "agents", "item": "refactor-*" },
    { "area": "skills", "host": "claude", "path": "~/.claude/skills/coderabbit-review" },
    { "area": "skills", "term": ".claude/docs/repo-analysis/" },
    { "area": "agents", "host": "claude", "path": "~/.claude/agents/*.md", "term": "TODO: do not sync" }
  ]
}

The active path and rule count are echoed in status output as Status ignore: rules: [...] (N hidden).

Sync direction

| Trigger | Default direction | | --- | --- | | AI_CONFIG_SYNC_HOST=codex (Codex plugin invocation) | codex → claude | | Otherwise (Claude plugin / direct CLI) | claude → codex | | --from --to | Explicit override |

Scopes

| Scope | Path coverage | | --- | --- | | global | ~/.claude/**, ~/.codex/** | | project | /.claude/**, /.codex/**, /AGENTS.md, /CLAUDE.md | | default / all | global + project |

Safety defaults

• Dry-run first — sync defaults to dry-run; --apply is required for any write.
• Backups on every write — atomic snapshot to .backups////... before overwrite.
• Apply ledger — every --apply records a per-item sha256 attestation (before_hash/after_hash, backup_path, plan_hash) to ~/.ai-config-sync-manager/ledgers/.json; --ledger copies it elsewhere and --ledger-json prints it to stdout.
• Risk labels — high-impact entries (permissions, hooks, custom commands) marked with their risk level in the diff.
• Strict-vocab guard — host-only tokens (e.g. Codex update_plan) flagged on cross-host copy.
• Secret pass-through — MCP env values are copied by default; set AI_CONFIG_SYNC_STRIP_SECRETS=1 to redact.
• Schema version — baseline state requires schemaVersion: 1; unknown versions abort.

Risk levels

| Level | Meaning | Behavior | | --- | --- | --- | | safe | Lossless, deterministic mapping | Auto-applied | | partial | Maps to a near-equivalent on the other host | Auto-applied with annotation | | manual | No safe automatic equivalent | Listed in the plan but always review before --apply |

Retention

| Directory | Keep | Strategy | | --- | --- | --- | | .backups/// | 30 | FIFO (oldest pruned on next write) | | ~/.config/ai-config-sync/status-details/ | 100 | FIFO | | ~/.ai-config-sync-manager/ledgers/ | 300 | FIFO (oldest pruned on next --apply) |

Native mapping (Claude ↔ Codex)

| Claude | Codex | | --- | --- | | permissions.allow: ["Write"] | sandbox_mode = "workspace-write" | | command-like permissions.allow (e.g. Bash(npm:*)) | approval_policy = "on-request" | | .mcp.json server entries | [mcp_servers.] TOML tables | | hooks.PreToolUse / PostToolUse | mapped where a Codex equivalent exists, else manual | | ~/.claude/skills//SKILL.md | ~/.codex/skills//SKILL.md |

Full mapping reference: [rules/](./rules/).

Paraphrase

Some tokens are mutually exclusive between hosts — Read, Write, Edit, Glob, mcp__* only exist on Claude; update_plan, spawn_agent, apply_patch only exist on Codex (full list: [rules/host-strict-vocab.json](./rules/host-strict-vocab.json)). When such a token leaks into the wrong host's file, the terminology map cannot translate it, so status keeps reporting the line as a manual-review mismatch forever.

This is what keeps strict YAML round-trip stable across repeated syncs: without it, host-specific vocabulary would oscillate or accumulate as drift on every cycle.

paraphrase resolves these by rewriting both sides to a shared word and registering a per-line override so future status runs treat the pair as in sync.

ai-config-sync paraphrase                                            # dry-run preview
ai-config-sync paraphrase --apply                                    # rewrite + register
ai-config-sync paraphrase --map "Read=Inspect,Write=Author" --apply  # inline mapping
ai-config-sync paraphrase --register --include skills:foo --apply    # register only (no rewrite)

| Flag | Purpose | | --- | --- | | --apply | Rewrite files, append to paraphrase-overrides.json, persist new entries to paraphrase-map.json (default: dry-run) | | --map token=paraphrase[,...] | Inline token-to-paraphrase pairs; layered on top of the file map | | --register | Skip rewriting; only register an override when the effective map already makes both sides byte-equal | | --non-interactive | Skip TTY prompts for tokens missing from the map | | --scope global\|project\|all | Limit paraphrase scope (default: both) | | --include / --exclude | Same selector syntax as status / sync | | --json | Machine-readable result |

--map syntax

• Token=Paraphrase for unambiguous tokens listed in host-strict-vocab.json.
• Prefix with claude_only: or codex_only: to disambiguate (e.g. claude_only:Read=Inspect).
• Comma-separated to chain entries: --map "Read=Inspect,codex_only:update_plan=Plan refresh".
• Tokens not present in host-strict-vocab.json are rejected unless prefixed.
• Paraphrase can be free-form prose, not just a single word. Pick wording that reads naturally on the opposite host so the rewritten line still makes sense in context — e.g. when masking a Claude-only token, choose phrasing a Codex prompt would actually use (Read=read the file, Write=write to the file, Glob=glob for files). Quote the value

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: slash9494
• Source: slash9494/ai-config-sync-manager
• License: MIT

Install and usage instructions live in the source repository linked above.