AgentSync

A fast, portable CLI tool for synchronizing AI agent configurations and MCP servers across multiple AI coding assistants using symbolic links.

How AgentSync works at a glance: many AI tools expect different config locations, so AgentSync turns .agents/ into one source of truth and syncs it everywhere.

flowchart LR
    subgraph Problem[Problem: fragmented AI tool setup]
        Claude[Claude Code]
        Gemini[Gemini CLI]
        Cursor[Cursor]
        Copilot[GitHub Copilot]
        Codex[OpenAI Codex]
        OpenCode[OpenCode]
    end

    Chaos[Scattered config files

Duplication and drift]
    Source[.agents/

Single source of truth]
    Sync[AgentSync

Rust CLI + npm wrapper]
    Output[Symlinks + MCP config

for each assistant]
    Result[Update once

Sync everywhere]

    Claude --> Chaos
    Gemini --> Chaos
    Cursor --> Chaos
    Copilot --> Chaos
    Codex --> Chaos
    OpenCode --> Chaos

    Chaos -->|replace with| Source
    Source --> Sync
    Sync --> Output
    Output --> Result

    classDef tools fill:#fff7ed,stroke:#f97316,color:#7c2d12,stroke-width:1px;
    classDef pain fill:#fef2f2,stroke:#ef4444,color:#7f1d1d,stroke-width:1px;
    classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a,stroke-width:1px;
    classDef success fill:#ecfdf5,stroke:#22c55e,color:#14532d,stroke-width:1px;

    class Claude,Gemini,Cursor,Copilot,Codex,OpenCode tools;
    class Chaos pain;
    class Source,Sync,Output core;
    class Result success;

Typical workflow

flowchart LR
    Init[agentsync init

Create or migrate config] --> Apply[agentsync apply

Create or refresh symlinks]
    Apply --> Status[agentsync status

Inspect sync state]
    Status --> Skill[agentsync skill ...

Manage installed skills]

    classDef action fill:#f8fafc,stroke:#475569,color:#0f172a,stroke-width:1px;
    class Init,Apply,Status,Skill action;

Why AgentSync?

Different AI coding tools expect configuration files in various locations:

Tool	Instructions	Commands	Skills
Claude Code	CLAUDE.md	.claude/commands/	.claude/skills/
GitHub Copilot	.github/copilot-instructions.md	-	-
Gemini CLI	GEMINI.md	.gemini/commands/	.gemini/skills/
Cursor	.cursor/rules/agentsync.mdc	-	.cursor/skills/
VS Code	-	-	-
OpenCode	AGENTS.md	.opencode/command/	.opencode/skills/
OpenAI Codex	AGENTS.md	-	.codex/skills/

AgentSync maintains a single source of truth in .agents/ and creates symlinks to all required locations.

Features

• 🔗 Symlinks over copies - Changes propagate instantly
• 📝 TOML configuration - Human-readable, easy to maintain
• 📋 Gitignore management - Automatically updates .gitignore
• 🛡️ Safe - Automatically backs up existing files before replacing them
• 🖥️ Cross-platform - Linux, macOS, Windows
• 🚀 CI-friendly - Gracefully skips when binary unavailable
• ⚡ Fast - Single static binary, no runtime dependencies
• 🧩 Curated skills - Install from the dallay/agents-skills collection or external providers

Catalog validation

AgentSync ships a full catalog installation E2E check that validates every skill entry can still be resolved, installed, and registered correctly.

• GitHub Actions workflow: Catalog E2E
• Manual run: Actions → Catalog E2E → Run workflow
• Scheduled run: every Monday at 08:00 UTC
• Local run:

git clone https://github.com/dallay/agents-skills ../agents-skills
export AGENTSYNC_LOCAL_SKILLS_REPO="$(pwd)/../agents-skills"
RUN_E2E=1 cargo test --test test_catalog_integration -- --ignored --nocapture

If you already keep agents-skills as a sibling checkout next to this repository, you can skip the environment variable and let the test auto-discover that sibling path instead.

This check is intentionally separate from normal CI because it depends on external networks and third-party skill repositories.

Installation

Node.js Package Managers (Recommended)

If you have Node.js (>=18) installed, the easiest way to install AgentSync is through a package manager.

Global Installation

# Using npm
npm install -g @dallay/agentsync

# Using pnpm
pnpm add -g @dallay/agentsync

# Using yarn (Classic v1)
yarn global add @dallay/agentsync

# Using bun
bun i -g @dallay/agentsync

One-off Execution

If you want to run AgentSync without a permanent global installation:

# Using npx (npm)
npx @dallay/agentsync apply

# Using dlx (pnpm)
pnpm dlx @dallay/agentsync apply

# Using dlx (yarn v2+)
yarn dlx @dallay/agentsync apply

# Using bunx (bun)
bunx @dallay/agentsync apply

Local Installation (Dev Dependency)

# Using npm
npm install --save-dev @dallay/agentsync

# Using pnpm
pnpm add -D @dallay/agentsync

# Using yarn
yarn add -D @dallay/agentsync

# Using bun
bun add -d @dallay/agentsync

From crates.io (Rust)

If you have Rust installed, you can install AgentSync directly from crates.io:

cargo install agentsync

From GitHub Releases (Pre-built Binaries)

Visit the GitHub Releases page to find the latest version number and correct platform identifier for your system.

To install via terminal, you can use the following script (be sure to replace the <version> placeholder with a real tag, e.g., 1.28.0):

# Define version and platform
VERSION="<version>"
# Detect architecture (macOS)
PLATFORM=$([ "$(uname -m)" = "arm64" ] && echo "aarch64-apple-darwin" || echo "x86_64-apple-darwin")
# Or specify manually for Linux, e.g., x86_64-unknown-linux-gnu
# PLATFORM="x86_64-unknown-linux-gnu"
TARBALL="agentsync-${VERSION}-${PLATFORM}.tar.gz"

# Download binary and checksum
curl -LO "https://github.com/dallay/agentsync/releases/download/v${VERSION}/${TARBALL}"
curl -LO "https://github.com/dallay/agentsync/releases/download/v${VERSION}/${TARBALL}.sha256"

# Verify integrity
if command -v sha256sum >/dev/null; then
  sha256sum --check "${TARBALL}.sha256"
else
  shasum -a 256 --check "${TARBALL}.sha256"
fi

if [ $? -ne 0 ]; then
  echo "Error: Checksum verification failed!"
  exit 1
fi

# Extract and install
tar xzf "${TARBALL}"
sudo mv agentsync-*/agentsync /usr/local/bin/

From Source (Requires Rust 1.89+)

Install directly from the GitHub repository (requires Node.js 22.22.0+ and Rust 1.89+):

cargo install --git https://github.com/dallay/agentsync

Or clone and build manually:

git clone https://github.com/dallay/agentsync
cd agentsync
cargo build --release

# The binary will be available at ./target/release/agentsync

Quick Start

New Projects

1. Initialize configuration in your project:

cd your-project
agentsync init

This creates .agents/agentsync.toml with a default configuration.

Existing Projects with Agent Files

If you already have agent configuration files scattered across your project (like CLAUDE.md, .cursor/, or .github/copilot-instructions.md), use the interactive wizard:

cd your-project
agentsync init --wizard

The wizard will scan for existing files, let you select which to migrate, and set up everything automatically.

---

1. Edit the configuration to match your needs (see Configuration)

2. Apply the configuration:

agentsync apply

1. Add to your project setup (e.g., package.json):

{
  "scripts": {
    "prepare": "agentsync apply || true"
  }
}

Team workflow note

AgentSync defaults to managed .gitignore mode ([gitignore].enabled = true), which is the recommended starting point for most teams. If your team intentionally wants to commit AgentSync-managed destinations instead, treat [gitignore].enabled = false as an explicit opt-out workflow. See the canonical guide: https://dallay.github.io/agentsync/guides/gitignore-team-workflows/

If you run AgentSync from Windows and need native symlink prerequisites, WSL guidance, or recovery steps, use the dedicated setup guide: https://dallay.github.io/agentsync/guides/windows-symlink-setup/

If your team wants agentsync apply to run after branch switches, merges, or rebases, use the Git hook automation guide for Lefthook, Husky, simple-git-hooks, and native hook examples: https://dallay.github.io/agentsync/guides/git-hook-automation/

Usage

# Initialize a new configuration
agentsync init

# Initialize with interactive wizard (for existing projects with agent files)
agentsync init --wizard

# Apply configuration (create symlinks)
agentsync apply

# Clean existing symlinks before applying
agentsync apply --clean

# Remove all managed symlinks
agentsync clean

# Use a custom config file
agentsync apply --config /path/to/config.toml

# Dry run (show what would be done without making changes)
agentsync apply --dry-run

# Skip gitignore reconciliation for this run only
agentsync apply --no-gitignore

# Filter by agent
agentsync apply --agents claude,copilot

# Verbose output
agentsync apply --verbose

# Show status of managed symlinks
agentsync status

# Run diagnostic and health check
agentsync doctor [--project-root <path>]

# Manage skills
agentsync skill install <skill-id>
agentsync skill update <skill-id>
agentsync skill uninstall <skill-id>

Status

Verify the state of AgentSync-managed targets. Useful for local verification and CI.

agentsync status [--project-root <path>] [--json]

• --project-root <path>: Optional. Path to the project root to locate the agentsync config.
• --json: Output machine-readable JSON (pretty-printed).

status is sync-type aware:

• symlink targets are checked as one managed destination symlink.
• symlink-contents targets are checked as destination directories whose managed child entries are the symlinks.
• An existing empty .agents/commands/ source directory is valid, so an empty destination like .claude/commands/ is not reported as missing or "not a symlink" just because it currently has 0 managed entries.

Exit codes: 0 = no problems, 1 = problems detected (CI-friendly)

Configuration

Configuration is stored in .agents/agentsync.toml:

```toml

Source directory (relative to this config file)

source_dir = "."

Optional: compress AGENTS.md and point symlinks to the compressed file

compress_agents_md = false

Default agents to run when --agents is not specified.

If empty, all enabled agents will be processed.

default_agents = ["claude", "copilot"]

Gitignore management

[gitignore] enabled