@dallay/agentsync

Effortlessly synchronize AI agent configurations across tools like Copilot, Claude, Cursor, and other MCP-compatible servers using symbolic links and an intuitive CLI.

🌟 Explore the Full Documentation Here

✨ Key Features

• Simple CLI: Manage symbolic links with minimal setup.
• Multi-assistant support: Compatible across Copilot, Claude, Gemini, Cursor, VS Code, OpenCode and 32+ more assistants. See the full list and file locations in the main documentation: https://dallay.github.io/agentsync/ (or the repo README).
• Cross-platform binaries: Available for Linux, MacOS, and Windows.
• Node.js integration: Use programmatically within your applications.

🚀 Installation

Make sure you have Node.js (>=18) installed.

Using pnpm (recommended):

pnpm install -g @dallay/agentsync

Using npm:

npm install -g @dallay/agentsync

Using yarn:

yarn global add @dallay/agentsync

Using bun:

bun add -g @dallay/agentsync

Verify installation:

agentsync --help

🛠️ Usage

Managing Configurations

Sync Configurations:

Run the following to create symbolic links across your AI coding assistants:

agentsync apply

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, treat [gitignore].enabled = false as an opt-out workflow instead of a new default. Full guide: https://dallay.github.io/agentsync/guides/gitignore-team-workflows/

Running from Windows? Use the setup guide for native symlink prerequisites, WSL as an optional lower-friction path, and verification steps: https://dallay.github.io/agentsync/guides/windows-symlink-setup/

Clean Configurations:

Remove previously created symbolic links:

agentsync clean

🎯 Example Workflows:

• Programmatic Usage in Node.js:

  const { main } = require('@dallay/agentsync');
  
  main(['apply']).catch((error) => {
     console.error(error);
     process.exit(1);
  });
  

• Integrate with npm scripts: Add configuration syncing to your npm scripts to automate process workflows. For example, in your package.json:

  {
    "scripts": {
      "precommit": "pnpm exec agentsync apply --dry-run",
      "prepare": "pnpm exec agentsync apply"
   }
  }
  

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

• For complex workflows, see the detailed API documentation.

MCP & Skills

• Claude Code — .mcp.json (agent id: claude) — JSON; Standard format
• Claude Desktop — Global OS-dependent config (agent id: claude-desktop) — JSON; Global; disabled by default
• GitHub Copilot — .vscode/mcp.json (agent id: copilot) — JSON; Shared with VS Code
• OpenAI Codex CLI — .codex/config.toml (agent id: codex) — TOML; Maps headers to http_headers
• Gemini CLI — .gemini/settings.json (agent id: gemini) — JSON; Adds trust: true
• VS Code — .vscode/mcp.json (agent id: vscode) — JSON; Shared with GitHub Copilot
• Cursor — .cursor/mcp.json (agent id: cursor) — JSON; Standard format
• OpenCode — opencode.json (agent id: opencode) — JSON; Standard format
• Z-Code — .zcode/config.json (agent id: zcode) — JSON; Uses the mcp.servers object and preserves other Z-Code settings
• MiniMax Code — .mcp.json (agent id: minimax) — JSON; Project-level standard format

• The typed registry and focused CI validator govern this list.
• Skills live under .agents/skills/ in the project.

👷 Development

This package is part of the AgentSync mono-repo. It serves as a Node.js wrapper for the high-performance Rust core.

Prerequisites

• pnpm: Dependency manager.
• Node.js >= 22.22.0 (for development).
• Rust: For building the core CLI.

Steps

1. Clone the repository:

   git clone https://github.com/dallay/agentsync.git
   cd agentsync
   

2. Install dependencies:

   pnpm install
   

3. Build:

   make js-build
   # or
   pnpm run build
   

4. Run tests and type checks:

   make js-test
   # or
   pnpm run typecheck
   

5. Format:

   make fmt
   

🛠️ Troubleshooting

PNPM_NO_MATURE_MATCHING_VERSION

If pnpm install fails with this error, it's likely due to a strict package release age policy. You can try installing with --ignore-scripts or wait for the package to "mature" in the registry.

Lefthook installation failure

If pnpm install fails during the lefthook setup, you can try:

pnpm install --ignore-scripts

🌐 Resources

• Project Repository: GitHub Repository
• Submit Issues: GitHub Issues
• Explore Full Documentation: Documentation Website

📜 License

MIT License. See the LICENSE for details.

🙏 Acknowledgments

Special thanks to the developer community for their contributions and feedback. For suggestions and improvements, feel free to open a pull request!

📣 Ready? Start syncing agent configs today with @dallay/agentsync!