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