agent-sync

One canonical .agents/ folder, fanned out to all your AI coding agents.

Website and docs: https://agent-sync.sh/

The Commons — the canonical ~/.agents/ directory — holds the single real copy of every config you share: skills, instructions, MCP servers, slash commands, agents and hooks. agent-sync sync fans it out to every agent you actually have installed.

Configs that can be byte-identical everywhere are symlinked, so there is one file seen from ten places and drift is impossible by construction. Configs that cannot be — MCP servers and hooks, which live inside files the agent also owns, in formats no two agents share — are rendered and key-merged, with your other keys preserved.

There is no state file. There never will be. The filesystem is the state.

~/.agents/
├── skills/<name>/       fanned out as symlinks
├── commands/<name>.md
├── agents/<name>.md
├── AGENTS.md            symlink, import-line, include-entry, or rules-dir link per agent
├── mcp.json             rendered into each agent's native dialect
└── hooks/<Event>.toml   merged by command string

Install

npm install -g agent-sync-sh   # prebuilt binary, macOS, Linux and Windows, no toolchain
pip install agent-sync-sh      # the same binary, shipped as a wheel
cargo install agent-sync-sh    # from source, needs Rust 1.97+

npx agent-sync-sh doctor       # or try it first, without installing anything
uvx agent-sync-sh doctor       # the same, if you reach for uv rather than npm

On macOS and Linux there is also a Homebrew tap. It lives in this repository rather than a separate homebrew-agent-sync one, so it is tapped by URL:

brew tap agent-sync-sh/tap https://github.com/agent-sync-sh/agent-sync
brew trust agent-sync-sh/tap   # Homebrew 6 refuses to load untrusted third-party taps
brew install agent-sync

Use

agent-sync init            # create the Commons and report what this machine already has
agent-sync adopt <path>    # take a path under management; --dry-run names the mechanic
agent-sync sync            # fan out; --dry-run prints the full plan
agent-sync status          # what is linked, what is not, and what is not ours
agent-sync doctor          # installed agents, Commons hygiene, Sourced entries
agent-sync revert <agent>  # offboard one agent (refuses until you disable it)
agent-sync mcp list | adopt | remove | enable | disable

adopt picks its mechanic from where the path lives: a real config inside an agent's directory is moved into the Commons with a link left behind; a path inside a git repo becomes a Sourced entry — the Commons links out to it and the repo keeps the truth; anything else is copied in. To gate CI on drift use status (exit 0 clean, 2 actionable, 1 error) — sync --dry-run previews, it does not gate.

Agents

Claude Code, Codex, opencode, pi, oh-my-pi, OpenClaw, Hermes, Gemini CLI, Cursor, Windsurf, Roo and Cline. Detection is simply whether the agent's config directory exists — agent-sync never creates one. Agents that read ~/.agents/skills natively (Codex, opencode, oh-my-pi, Gemini CLI, Cursor) get no skill links written, because nothing needs to be — and where an agent still reads its old fan-out directory beside the Commons (Codex, Cursor), sync prunes agent-sync's now-duplicate links from it.

Interop

The Commons speaks the conventions that won: skills/<name>/SKILL.md — the layout opencode and friends read natively — one AGENTS.md, and an mcp.json in the standard mcpServers shape. .agents Protocol surfaces (tasks/, memories/, models.json, system-prompt.md) are recognized by doctor and never touched.

What it will not touch

Anything it does not own. A symlink pointing outside the Commons, a hand-written file, an MCP server whose name isn't in the Commons — all Foreign, all reported by status, none ever modified. A real directory shadowing a Commons entry is a Variant: deliberate, preserved, and counted as actionable only when its contents are identical to the Commons copy, so you can dedupe on purpose.

The Commons is exactly that — a commons, not agent-sync's alone. opencode, oh-my-pi and Hermes read ~/.agents/ themselves, and other tools keep their own files there. doctor names entries that aren't agent-sync's and leaves them be; status stays target-only, since a neighbour's file has no fan-out to report.

Configuration

Optional agent-sync.toml in $XDG_CONFIG_HOME/agent-sync/ (default ~/.config/agent-sync/): disable targets, define custom ones, choose each agent's instructions route, scope MCP servers per agent, per-agent Tweaks.

[instructions]
claude = "symlink"   # "symlink" or "import"; omitted, the agent's default

Claude, opencode and Gemini CLI offer both routes and default to import. Claude Cowork on the desktop skips a ~/.claude/CLAUDE.md that is a symlink (Claude Code memory docs), and it also skips an import that points outside the session's folder, so there it reads only CLAUDE.md's own text. For opencode and Gemini, symlink lets claude-mem, and Gemini's own memory tool, write through the link into the Commons. Every other agent takes the one route it has, and naming a route it lacks is a configuration error (ADR-0009).

The lock — agent-sync's only machine state — lives in $XDG_STATE_HOME/agent-sync/ (default ~/.local/state/agent-sync/). Environment: AGENT_SYNC_HOME relocates the Commons (doctor warns — native readers won't follow), AGENT_SYNC_TARGET_ROOT resolves everything against another root, AGENT_SYNC_LOCK_TIMEOUT_MS bounds the lock wait.

What it does not do

No cross-machine sync — version the Commons with git or chezmoi. No undo — refusals come before writes, sync plans everything before writing anything, sync and adopt preview with --dry-run, re-runs are idempotent, and a git-versioned Commons is better history than any journal. No memory sync: agent memory is not a defined artifact and agent-sync will not pretend otherwise. No GUI, daemon or file watcher. It does not install skills; it fans out whatever is in the Commons, whoever put it there.

On Windows, creating symlinks requires Developer Mode (Settings → System → For developers) or an elevated shell; sync says exactly that when it cannot link.

Name and inspiration

The name is a nod to GNU Stow, the classic symlink-farm manager — agent-sync does for agent configs what Stow does for dotfiles. The project is also inspired by two neighbours in the same space: dotagents and agentsync.

Documentation · agent-sync.sh · MIT