Skip to content
AgentSync

Getting started

agentsync is a fast, portable CLI tool for synchronizing AI agent configurations across multiple coding assistants using symbolic links.

Installation

Section titled “Installation”
Section titled “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

Section titled “Global Installation”
Terminal window
# 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

Section titled “One-off Execution”
Terminal window
# 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

From GitHub Releases

Section titled “From GitHub Releases”

Download the latest release for your platform:

macOS (Apple Silicon)

Section titled “macOS (Apple Silicon)”
Terminal window
curl -LO https://github.com/dallay/agentsync/releases/latest/download/agentsync-aarch64-apple-darwin.tar.gz
tar xzf agentsync-aarch64-apple-darwin.tar.gz
sudo mv agentsync-*/agentsync /usr/local/bin/

Linux (x86_64)

Section titled “Linux (x86_64)”
Terminal window
curl -LO https://github.com/dallay/agentsync/releases/latest/download/agentsync-x86_64-unknown-linux-gnu.tar.gz
tar xzf agentsync-x86_64-unknown-linux-gnu.tar.gz
sudo mv agentsync-*/agentsync /usr/local/bin/

From Source (Requires Rust 1.89+)

Section titled “From Source (Requires Rust 1.89+)”

If you have Rust (1.89+) and Node.js (22.22.0+) installed, you can install directly from crates.io or from the repository:

Terminal window
# From crates.io


cargo install agentsync


# From GitHub


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

Basic Usage

Section titled “Basic Usage”

1. Initialize Configuration

Section titled “1. Initialize Configuration”

New Projects

Section titled “New Projects”

Run init in your project root to create the default structure:

Terminal window
npx @dallay/agentsync init

This creates a .agents/ directory with an initial agentsync.toml and an AGENTS.md file.

Existing Projects with Agent Files

Section titled “Existing Projects with Agent Files”

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

Terminal window
npx @dallay/agentsync init --wizard

The wizard will:

  1. Scan your project for existing agent-related files — instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, .windsurfrules, AMPCODE.md, etc.), skill directories (.claude/skills/, .cursor/skills/, .codex/skills/, and more), command directories (.claude/commands/, .gemini/commands/, .opencode/command/), and MCP configurations
  2. Let you select which files to migrate to .agents/
  3. Migrate skills from any detected agent into .agents/skills/ (with collision detection — duplicates are skipped with a warning)
  4. Migrate commands into .agents/commands/ as the canonical location
  5. Note MCP configs found in agent directories and suggest manual migration to [mcp_servers] in your config
  6. Optionally create backups of your original files (with confirmation)
  7. Generate a configuration that manages everything with symlinks

This makes it easy to transition from manual file management to AgentSync — even if you already have skills, commands, or configs spread across multiple agent directories!

2. Configure your Agents

Section titled “2. Configure your Agents”

Edit .agents/agentsync.toml to define which assistants you use. By default, it includes configurations for Claude Code, GitHub Copilot, Cursor, Codex CLI, and a root AGENTS.md target.

[agents.claude]
enabled = true


# ... configuration ...

Optional: Limit default agents

If you work with many agents but only want a subset to run by default, add the default_agents field:

# Only these agents will run when using 'agentsync apply' without --agents
default_agents = ["copilot", "claude"]


[agents.copilot]
enabled = true


[agents.claude]
enabled = true


[agents.gemini]
enabled = true  # Enabled, but won't run by default

See Configuration Reference for more options.

Section titled “3. Apply Symlinks”

Create the symbolic links in your project root:

Terminal window
npx @dallay/agentsync apply

This will create files like CLAUDE.md and .github/copilot-instructions.md that point back to your single source of truth in .agents/.

By default, agentsync apply also manages a marker-delimited .gitignore block for those destinations. Most teams should keep that default. If your team instead wants to commit AgentSync-managed destinations, treat that as an intentional opt-out and follow the Gitignore Team Workflows guide rather than changing setup ad hoc.

If you run AgentSync from Windows and hit symlink-permission or shell-context issues, use the Windows Symlink Setup guide for native prerequisites, WSL guidance, and verification steps.

4. Integration with pnpm/npm

Section titled “4. Integration with pnpm/npm”

We recommend adding the apply command to your prepare script to ensure symlinks are always present for your team:

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

Note: || true ensures the install process does not fail if agentsync is not yet installed, such as on a fresh clone or in CI environments.

If you use a prepare hook, collaborators can usually rely on that automation after pulling changes. They should still run agentsync apply manually when the hook does not run or after changing AgentSync config.

If your team also wants symlinks refreshed after branch switches, merges, or rebases, follow the Git Hook Automation guide for Lefthook, Husky, simple-git-hooks, and native Git hook examples.

Next Steps

Section titled “Next Steps”