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:

Release binaries are attached to the GitHub Releases page. The asset filename includes the release version, so use GitHub CLI to select the current asset by platform pattern. This example downloads the macOS Apple Silicon archive:

Terminal window
gh release download --repo dallay/agentsync --pattern '*aarch64-apple-darwin.tar.gz'
tar xzf agentsync-*-aarch64-apple-darwin.tar.gz
sudo install agentsync-*/agentsync /usr/local/bin/agentsync

Available targets are Linux x64/ARM64 with GNU or musl (x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-gnu, aarch64-unknown-linux-musl), macOS Intel/Apple Silicon (x86_64-apple-darwin, aarch64-apple-darwin), and Windows x64/ARM64 (x86_64-pc-windows-msvc, aarch64-pc-windows-msvc). Windows assets are .zip; the others are .tar.gz. Replace the target in the pattern to select another platform.

From Source (Requires Rust 1.89+)

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

If you have Rust (1.89+) installed, you can install the published crate from crates.io:

Terminal window
cargo install agentsync

To install from the repository, install Rust 1.89+ and Node.js 22.22.0+ first:

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

The npm wrapper requires Node.js 18 or newer. Building from source requires Rust 1.89+. The published crate does not require Node.js; installing from the Git repository also requires Node.js 22.22.0+ for generated build steps.

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.

Tip: Personal defaults

If you regularly use only a subset of agents, create a user-level template so init generates a leaner config every time:

Terminal window
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/agentsync"
# Copy and edit the default config, keeping only the agents you need
agentsync init && cp .agents/agentsync.toml "${XDG_CONFIG_HOME:-$HOME/.config}/agentsync/config.toml"
# Edit the config to keep only your preferred agents

Or use --template to point to any TOML file:

Terminal window
npx @dallay/agentsync init --template ~/my-template.toml

See CLI Reference for details.

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, Gemini CLI, OpenCode, 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”