agentsync

Status: beta (v0.1.0). Ships Claude Code, OpenCode, and Codex end-to-end. The tool is functional and tested under just test-release; the canonical layout, CLI surface, and state schema are stabilizing toward 1.0.0 and may still change. A few documented trade-offs remain (see Known limits).

What it does

If you use more than one AI coding agent, you keep re-entering the same config in each one's native format, you forget to install a plugin everywhere, and your configs quietly drift apart. agentsync fixes the fan-out:

• Edit once, apply everywhere. Add an MCP server or install a plugin a single time; it's projected into each agent's native config — fully where the agent has the concept, lossily-but-reported where it doesn't, skipped (never silently) where it can't.
• Bidirectional, chezmoi-style. When an agent edits its own config, agentsync detects the drift and offers a merge: adopt the edit into your source, or re-impose the source. Nothing is overwritten behind your back.
• Secrets stay secret. Reference ${secret:github.token}; agentsync resolves it at apply time from an age-encrypted vault and never writes the cleartext back into your (committable) source.

New here? The User guide takes you 0→100.

Quickstart

agentsync init
agentsync agent add claude
agentsync agent add opencode
agentsync mcp add github --command npx --args "-y,@modelcontextprotocol/server-github"
agentsync apply --dry-run    # preview what would change vs. is already synced
agentsync apply

Documentation

The full docs are published with search and rendered diagrams at agentsync.cc (source in website/). The canonical markdown also lives in docs/:

Supported agents at a glance

Full ✓/◐/✗ breakdown per component: capability matrix.

Install

macOS — Homebrew

brew tap spxrogers/tap
brew install agentsync

Linux — deb / rpm

Pick the package for your architecture (amd64 or arm64).

Debian/Ubuntu:

curl -fsSL https://github.com/spxrogers/agentsync/releases/latest/download/agentsync_linux_amd64.deb -o agentsync.deb
sudo dpkg -i agentsync.deb

RPM:

sudo rpm -i https://github.com/spxrogers/agentsync/releases/latest/download/agentsync_linux_amd64.rpm

Any platform — prebuilt binary

Download the archive for your OS/arch from the latest release (linux / darwin / windows × amd64 / arm64), extract it, and put the agentsync binary on your PATH. This is the install path for Windows until Scoop/Chocolatey land.

From source

go install github.com/spxrogers/agentsync/cmd/agentsync@latest

or clone and go build ./cmd/agentsync.

Coming soon

Scoop (Windows), Chocolatey (Windows), and AUR (Arch) packaging is wired in .goreleaser.yaml but not published yet — tracked in issue #13. Until then, use the prebuilt binary or go install above.

Cross-machine sync

agentsync is single-machine. To sync ~/.agentsync/ across machines, use chezmoi (or any dotfile manager):

chezmoi add ~/.agentsync

Secrets — age key backup

If you lose your age private key, you lose access to all encrypted secrets. Recommended: store the key in a 1Password Secure Note or your machine-setup repo. agentsync does not back up the key for you.

agentsync secrets set accepts the value three ways:

agentsync secrets set github.token --stdin    # value from stdin (best for scripts / 1Password CLI)
agentsync secrets set github.token            # prompt with echo off
agentsync secrets set github.token=ghp_…      # back-compat; warns — argv is visible to ps(1) and shell history

agentsync diff redacts every resolved ${secret:…} value before printing, so a piped diff doesn't leak credentials to logs.

Known limits

• OpenCode hooks: OpenCode hooks are JS/TS plugins, not declarative shell commands. agentsync does NOT auto-translate Claude hooks to OpenCode. Hand-author a small JS/TS plugin if you need a hook on OpenCode.
• Codex projections are lossy where Codex differs: subagents project to Codex's TOML agent format (the tools/color frontmatter has no target and is dropped, reported in the apply report); slash commands map to Codex custom prompts which are global-only, so a project-scope command is skipped; hooks mirror Claude's declarative hook schema as inline [hooks.*] tables in ~/.codex/config.toml but only for the events Codex recognizes (Claude's SessionEnd/Notification drop). All of these are surfaced in the translation report — nothing is dropped silently.
• Cursor adapter: not implemented yet — registers as a no-op adapter (planned), and agent add cursor is rejected unless AGENTSYNC_ALLOW_UNIMPLEMENTED=1. Cursor's planned coverage includes skills and subagents (which it stores on the filesystem under .cursor/skills/ and .cursor/agents/), but its user-level rules live in app-local storage (not the filesystem), so the adapter will manage rules at project scope only.
• LSP projection beyond Claude: OpenCode/Cursor LSP support is deferred (Codex has no LSP concept at all). Claude plugins that include LSP servers install correctly on Claude itself; on other agents you'll see lsp server X skipped in the apply translation report.
• cursor agent registration: agent add cursor is rejected because its adapter is a noop. Set AGENTSYNC_ALLOW_UNIMPLEMENTED=1 to register anyway (apply will silently emit zero ops for it).
• TOML / JSONC comment preservation: comments in ~/.agentsync/mcp/*.toml, in agent-side opencode.json, and in Codex's ~/.codex/config.toml are NOT preserved across reconcile [w]rite-back or import / apply. Hand-edited comments survive in unrelated sections; the rewritten section will be re-emitted without comments. Deferred to a later release.
• Hand-edits to agentsync-owned keys in shared agent files (e.g. an MCP server entry in ~/.claude.json that agentsync owns): the next apply overwrites them with NO foreign-collision backup, because agentsync considers them its own. Use agentsync reconcile (the drift classifier catches the edit and offers [w]rite-back) BEFORE the next apply if you want to keep them.
• Plain-http / git:// plugin sources are rejected by default to prevent MITM swap. Set AGENTSYNC_ALLOW_INSECURE_URLS=1 for internal mirrors.
• Symlinked destinations (e.g. ~/.claude.json is a chezmoi symlink into your dotfiles repo) are rejected by default — a rename onto the path would replace the symlink with a regular file and strand your linked source. Set AGENTSYNC_ALLOW_SYMLINK_DEST=1 to write through the symlink instead (the underlying file is updated in place; the link survives).
• Continue, Gemini CLI, Aider: planned — not yet implemented.

Environment overrides

Troubleshooting

• First apply on a populated machine: agentsync sees pre-existing native config files and triggers foreign-collision. The original is backed up to ~/.agentsync/.state/backups/<ts>/ before the new content lands. Recommend agentsync apply --dry-run first to preview the translation report.
• One-time backup churn after upgrading: state keys are now stored ${HOME}-relative (portable across machines) instead of with absolute paths. If you ran a pre-portability build, the first apply after upgrading will not recognize the old absolute-path entries, so every managed destination is treated as a foreign-collision once: the current content is backed up to ~/.agentsync/.state/backups/<ts>/ and then re-owned. This is expected, non-destructive (nothing is lost — it's backed up), and self-heals after that single apply. Run agentsync apply --dry-run first if you want to see which files will be backed up.
• agentsync update fails to fetch a marketplace: verify the marketplace URL with git ls-remote. agentsync uses go-git and falls back to system git for sparse clones if needed.
• ${secret:foo} not resolving: run agentsync secrets get foo to verify the key exists in the decrypted file. age library errors will surface here.

Testing

Every just test* recipe runs inside a hermetic container (podman first, docker fallback) — except the two explicit on-host opt-ins (test-fast and test-live) called out below. The repo is mounted read-only, the network is off, and every test's HOME is a fresh tmpdir — the suite cannot touch your real ~/.claude.json, ~/.config/opencode/, or ~/.agentsync/.

If just test-release is green, ship.

For fast in-place iteration without spinning up the container, just test-fast runs the unit/integration layer directly on the host. The existing tests already redirect HOME via AGENTSYNC_TARGET_ROOT, so they are still safe; the container is the release gate.

If you reach for the obvious go test ./..., the filesystem-touching packages refuse to run on the host and print a long banner pointing you at the recipes above. To bypass the guard manually (e.g. for go test -run on a single test), set AGENTSYNC_TEST_IN_CONTAINER=1:

AGENTSYNC_TEST_IN_CONTAINER=1 go test ./internal/cli/ -run TestApply_FirstRun

just test-live runs the live cohort (build tag live) — currently the obra/superpowers projection check, which clones the real upstream plugin to verify agentsync's projector keeps working as the upstream evolves. It runs on host because it needs network access; it is opt-in and NOT part of test-release, so the release gate stays hermetic and offline.

License

MIT.