agent-sync

One memory, every agent. Synchronize your AI coding agents' memory, so
you can stop in one agent and pick up in another.

Every coding agent accumulates knowledge about you and your projects: Claude
Code writes memory files, Codex keeps a memory store, Goose keeps memories,
Cursor and Continue collect rules. Each lives in its own silo, so switching
agents means starting over. agent sync breaks the silos with a three-stage
round trip:

1. Gather: read every agent's own memory stores.
2. Synthesize: fold them into one synthesized memory file. Claude does
   the semantic merge when available, then Codex; if neither is usable, the
   deterministic marker-delimited merge remains.
3. Redistribute: write the result to every installed agent's global
   instructions slot.

After a sync, every agent knows what every agent has learned. Unlike
one-way rules generators, the loop is bidirectional: what your agents learn
flows back into the canon.

Target filtering: --only claude,codex / --skip qwen flags on sync and
apply; the AGENT_SYNC_ONLY / AGENT_SYNC_SKIP environment variables
additionally apply to status, diff, skills sync and mcp sync.

The edit loop: agent gather, edit the staged files in one place, agent apply. Your edits land back in each agent's own store, get folded into the
synthesized file, and are redistributed to every agent.

Every command with real output, end to end:
docs/walkthrough.md.

Safety: the first time sync would overwrite a pre-existing file it did
not write, the original is preserved beside it as <file>.orig, and agent revert restores everything. apply validates every manifest entry against
the supported memory-store paths and rejects path traversal and symlinks.
Pack subdirectories must resolve inside the downloaded repository. MCP files
are written through private atomic temporary files, and CLI-managed MCP
updates validate before replacement and restore the recorded configuration if
replacement fails. Skill directories are replaced only after agent-sync has
recorded ownership; an unmanaged same-name skill is reported and left alone.

Install

With the installer (pinned release, checksum-verified):

curl -fsSL https://raw.githubusercontent.com/hibeekaey/agent-sync/main/install.sh | sh
# or, per-user without sudo:
curl -fsSL https://raw.githubusercontent.com/hibeekaey/agent-sync/main/install.sh | PREFIX=$HOME/.local sh

With Homebrew:

brew install hibeekaey/tap/agent-sync

# Upgrading: brew only refreshes taps once per HOMEBREW_AUTO_UPDATE_SECS
# (24 hours by default), so a fresh release can look like "not outdated"
# until the tap is fetched.
brew update && brew upgrade agent-sync

From a clone (installs the man page and completions too):

make install                 # /usr/local (may need sudo)
make install PREFIX=~/.local # per-user, no sudo

POSIX sh only, using standard Unix utilities available on macOS and Linux.
Memory packs require curl and tar; semantic synthesis requires a configured
Claude Code or Codex CLI unless deterministic mode is selected.

Supported agents

Global scope (agent sync writes the synthesized file here):

Every path above was verified against the tool's official documentation.
Tools are detected by their config directory; absent tools are skipped, so
the same binary serves every machine. Files agent-sync generates are never
gathered, so the tool cannot feed on its own output. Aider is deliberately
absent: it has no global instructions mechanism; point read: in
~/.aider.conf.yml at the synthesized file yourself.

Project scope (agent link): one repo-root AGENTS.md — the
AGENTS.md standard is read natively by Codex, Cursor,
Copilot, Zed, Amp, OpenCode, Junie, Goose, Jules and others. link seeds
it (from an existing CLAUDE.md when present), bridges Claude Code with the
officially documented @AGENTS.md import stub, and configures Gemini CLI's
context.fileName (which does not read AGENTS.md by default).

Semantic synthesis

agent sync automatically selects a semantic synthesizer. The same
selection is used by the full sync at the end of agent apply.

Automatic mode sends the synthesized memory document to the locally
configured Claude Code account, then Codex if Claude is unavailable or fails.
Use --synthesizer deterministic when the document must stay entirely local.

agent sync
agent sync --synthesizer deterministic
AGENT_SYNC_SYNTHESIZER='claude -p' agent sync

CLI selection overrides the environment. Model calls are non-interactive
(Claude runs without session persistence; Codex runs ephemerally in a
read-only sandbox), output is validated, the previous file is kept at
<file>.bak, and every failure falls through toward the deterministic
merge. A recursion guard stops a synthesizer-spawned agent from re-entering
agent-sync.

Automating

Cron staleness gate:

0 9 * * * agent status || osascript -e 'display notification "agent memory is stale" with title "agent-sync"'

CI drift gate (fails the build when instructions drifted):

agent diff

Claude Code hook that re-syncs whenever the canon is edited:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "f=$(jq -r \".tool_input.file_path // empty\"); if [ \"$f\" = \"$HOME/.claude/CLAUDE.md\" ]; then agent sync --synthesizer deterministic; fi"
      }]
    }]
  }
}

Coordinating agents on one task

Shared memory makes cross-agent handoffs coherent; the file-mediated
protocol for splitting work between two agents (headless invocation, task
directories, mkdir locks, git worktrees) is documented in
docs/coordination.md, including a verified
Claude Code to Codex round trip.

The same protocol ships as an installable coordinator skill at
skills/coordinate-agents. Install it
with gh skill into whichever agent
should play coordinator:

gh skill install hibeekaey/agent-sync coordinate-agents \
  --agent claude-code \
  --scope user

To pin a specific version, add --pin vX.Y.Z using any agent-sync release
tag; the skill ships with the CLI and shares its version line. Without gh,
copying skills/coordinate-agents/ into your agent's skills directory works
too.

MCP, skills, packs and hooks

Beyond memory, agent syncs the rest of your agent setup:

• MCP servers (agent mcp): register a server once, push it everywhere.
  Tools with an MCP CLI get it through their own CLI (claude mcp add-json,
  codex mcp add, gemini/qwen mcp add, amp mcp add); tools with a
  dedicated MCP file get an agent-sync-owned file (Cursor ~/.cursor/mcp.json,
  Windsurf mcp_config.json, Kiro settings/mcp.json), never touched if you
  created it yourself. Tools that keep MCP inside shared settings (Zed,
  OpenCode, Goose, Continue) get a printable snippet instead of risky edits.
  CLI entries successfully applied by agent-sync are tracked so later updates
  can validate and roll back, and removal from the registry is propagated on
  the next sync. Entries first installed before v1.5.2 may require one manual
  removal. MCP environment values and headers can be secrets: registry files
  are private, and agent mcp snippet deliberately prints them for pasting.
  Every command grammar and file shape was verified against official docs.
• Skills (agent skills sync): additively synchronize ~/.claude/skills
  (or AGENT_SYNC_SKILLS_SOURCE) into every agent's user-scope skills
  directory, following the gh skill agent registry mapping. Target-only
  skills remain. Identical copies are adopted, agent-sync-owned copies update
  atomically, and conflicting unmanaged copies are left untouched with a
  nonzero exit.
• Memory packs (agent pack): install shareable markdown packs from any
  GitHub repo, pinned to a commit in a lockfile, folded into the synthesized
  file on every sync and cleanly removable.
• Hooks (agent hooks): verified snippets that keep memory fresh
  automatically (Claude Code SessionEnd, Codex Stop, Gemini AfterAgent,
  an OpenCode plugin under ~/.config/opencode/plugin), printed for you to
  paste, never installed behind your back.

Roadmap

• Hook-based automatic session capture into the canon (beyond re-sync)
• Per-agent content overrides (vary sections per tool)
• Native Windows (PowerShell) port; WSL is supported today
  (docs/windows.md)

Notes

Contributing

Contributions are welcome, especially support for new agents (see the
feature request template for
what a new target needs). Start with CONTRIBUTING.md;
this project follows a Code of Conduct and takes
security reports privately per SECURITY.md.

Support the project

If agent-sync saves you from re-teaching your agents who you are:

• Star the repo. It genuinely helps others find it.
• Share it with someone juggling more than one coding agent.
• Sponsor if it earns a place
  in your daily loop.

License

MIT