agentsync

English | 简体中文

agentsync is a small Go CLI that keeps AI coding-agent instructions and reusable skills in one canonical place.

It prevents drift across many AI coding agents — Codex, Claude Code, OpenCode, Gemini CLI, Qwen Code, Copilot CLI, Kimi Code, Grok, Amp, Crush, Goose, Factory Droid, iFlow, Kilo, Cursor, Windsurf, Zed, CodeBuddy, Qoder, Junie, Kiro, JoyCode, and more — by converging their global instruction files and SKILL.md directories into shared sources under ~/.config/agentsync.

Only Touches Installed Runtimes

Each supported runtime is gated on its own home directory (for example ~/.codex, ~/.gemini, ~/.joycode). If that directory does not exist, agentsync treats the runtime as not installed and reports it as skipped — it never creates directories or alias files for tools you do not use. Install a new agent, run agentsync again, and it converges on the next pass.

What It Manages

Canonical instruction file:

~/.config/agentsync/AGENTS.md

Tool-specific instruction aliases (created only when the runtime is installed):

~/.codex/AGENTS.md
~/.config/opencode/AGENTS.md
~/.claude/CLAUDE.md
~/.gemini/GEMINI.md
~/.qwen/QWEN.md
~/.copilot/copilot-instructions.md
~/.kimi-code/AGENTS.md
~/.grok/AGENTS.md
~/.config/amp/AGENTS.md
~/.config/crush/CRUSH.md
~/.config/goose/AGENTS.md
~/.factory/AGENTS.md
~/.iflow/IFLOW.md
~/.config/kilo/AGENTS.md
~/.cursor/rules/AGENTS.mdc
~/.codeium/windsurf/memories/global_rules.md
~/.config/zed/AGENTS.md
~/.codebuddy/CODEBUDDY.md
~/.qoder/AGENTS.md
~/.junie/AGENTS.md
~/.kiro/steering/AGENTS.md
~/.joycode/AGENTS.md
~/.agents/AGENTS.md

Cursor's entry is a managed .mdc rule (alwaysApply: true frontmatter + source body), not a bare symlink — Cursor ignores plain rule files without frontmatter. If Settings lists the rule but the Agent cannot quote its body, Cursor often skips file-backed ~/.cursor/rules when the workspace is $HOME / Agents Window has no project open; open a real project workspace, or paste critical text into Settings → User Rules (see docs/AGENTSYNC_GUIDE.md).

Canonical skill directory:

~/.config/agentsync/skills/<skill-name>/SKILL.md

Tool-specific skill aliases (created only when the runtime is installed), each pointing at ~/.config/agentsync/skills:

~/.claude/skills          ~/.config/amp/skills
~/.codex/skills           ~/.config/crush/skills
~/.config/opencode/skills ~/.factory/skills
~/.qwen/skills            ~/.iflow/skills
~/.copilot/skills         ~/.aider-desk/skills
~/.kimi-code/skills       ~/.cursor/skills
~/.grok/skills            ~/.codeium/windsurf/skills
~/.codebuddy/skills       ~/.qoder/skills
~/.kiro/skills            ~/.joycode/skills
~/.agents/skills

Each skill is managed as a whole directory under the canonical skill root. A skill must contain SKILL.md; any scripts, templates, references, or assets next to it stay with that skill. Because tool-specific skill roots point at the canonical root, adding, deleting, or renaming a canonical skill is reflected by every tool immediately.

Install

With Homebrew:

brew install --cask x0c/tap/agentsync

Or with Go:

go install github.com/x0c/agentsync@latest

Or from a checkout:

go install .

Usage

Preview changes without writing anything:

agentsync --check

Converge global instructions and skills:

agentsync

Running agentsync repeatedly is intended to be idempotent. After the first convergence, later runs should report ok for managed aliases.

Repository Mode

Inside a Git repository:

agentsync --repo

This uses the repository AGENTS.md as the source and manages:

CLAUDE.md -> AGENTS.md

Batch process repositories under a directory:

agentsync --all ~/Codes

Safety

• --check is read-only.
• Existing unique instruction content is appended to the canonical source before aliases are created.
• Existing skill directories are copied into the canonical skill directory before tool-specific skill roots are replaced with aliases.
• Replaced files and directories are backed up under ~/.config/agentsync/backups/.
• Hidden skill directories such as Codex .system internals are preserved in the canonical skill root before tool-specific skill roots are replaced.
• macOS and Linux use symlinks first.
• Windows tries symlinks first, then hardlinks, then a managed copy with a marker comment.

Development

Project documentation is indexed in AGENTS.md.

go test ./...
go build ./...
agentsync --check

Tagged releases are built by GoReleaser. To publish the Homebrew cask, create the x0c/homebrew-tap repository and add a HOMEBREW_TAP_GITHUB_TOKEN secret with permission to push to that tap.

License

MIT