agentssync

Sync AI agent instruction files via symlinks - maintain a single source of truth across Claude, Cursor, Copilot, Windsurf, and 15+ AI coding tools.

The Problem

Modern developers use multiple AI coding assistants. Each tool has its own instruction file:

• Claude Code reads CLAUDE.md
• GitHub Copilot reads .github/copilot-instructions.md
• Cursor reads .cursorrules
• Windsurf reads .windsurfrules
• OpenAI Codex CLI reads AGENT.md
• ...and many more

Maintaining identical instructions across all these files is tedious and error-prone.

The Solution

agentssync creates symlinks between AI instruction files, so you maintain one source file and all other agents automatically stay in sync.

CLAUDE.md (source - your single source of truth)
    ├── AGENTS.md → CLAUDE.md
    ├── .cursorrules → CLAUDE.md
    ├── .windsurfrules → CLAUDE.md
    ├── .clinerules → CLAUDE.md
    └── .github/copilot-instructions.md → CLAUDE.md

Installation

# Using npm
npm install -g agentssync

# Using bun
bun install -g agentssync

# Using pnpm
pnpm add -g agentssync

Quick Start

# Navigate to your project
cd my-project

# Run agentssync
agentssync

That's it! The interactive CLI will:

1. Scan for existing AI instruction files
2. Let you select the primary source file
3. Let you choose which agents to create symlinks for
4. Create the symlinks

Usage

Interactive Mode (Default)

agentssync

Non-Interactive Mode

# Auto-select all available agents
agentssync -y

# Preview without making changes
agentssync --dry-run

# Specify a different directory
agentssync ./my-project

CLI Options

| Option | Alias | Description | |--------|-------|-------------| | --help | -h | Show help message | | --version | -v | Show version number | | --dry-run | -d | Preview changes without creating symlinks | | --yes | -y | Auto-confirm all prompts (non-interactive) | | --verbose | | Show detailed output | | --config | -c | Path to config file |

Supported AI Agents

| Agent | Instruction File | Priority | |-------|-----------------|----------| | Universal (AGENTS.md) | AGENTS.md | 100 | | Claude Code | CLAUDE.md | 90 | | GitHub Copilot | .github/copilot-instructions.md | 85 | | Cursor | .cursorrules | 80 | | Windsurf | .windsurfrules | 75 | | Cline | .clinerules | 70 | | OpenAI Codex CLI | AGENT.md | 65 | | Gemini CLI | GEMINI.md | 60 | | Amazon Q Developer | .amazonq/rules/rules.md | 55 | | JetBrains AI | .junie/guidelines.md | 50 | | Roo Code | .roorules | 45 | | Augment Code | .augment/rules/rules.md | 40 | | Aider | CONVENTIONS.md | 35 | | Continue.dev | .continuerules | 30 | | Sourcegraph Cody | .cody/cody.json | 25 |

Priority determines which file is suggested as the primary source when multiple instruction files exist.

Configuration

Create a .agentssync.json file in your project root or home directory:

{
  "customAgents": [
    {
      "id": "my-agent",
      "name": "My Custom Agent",
      "patterns": ["MY_AGENT.md"],
      "primaryFile": "MY_AGENT.md",
      "priority": 50
    }
  ],
  "excludeAgents": ["amazonq", "cody"],
  "ignorePatterns": ["**/temp/**"],
  "defaultSource": "claude"
}

Configuration Options

| Option | Type | Description | |--------|------|-------------| | customAgents | AgentConfig[] | Add custom AI agents | | excludeAgents | string[] | Agent IDs to exclude from scanning | | ignorePatterns | string[] | Additional glob patterns to ignore | | defaultSource | string | Default source agent ID |

Programmatic API

You can also use agentssync as a library:

import {
  scanForInstructionFiles,
  analyzeConflicts,
  createSymlink,
  DEFAULT_AGENTS,
} from "agentssync";

// Scan for files
const files = await scanForInstructionFiles({
  cwd: process.cwd(),
  agents: DEFAULT_AGENTS,
});

// Analyze conflicts
const analysis = await analyzeConflicts(files);

// Create a symlink
const result = await createSymlink({
  source: "/path/to/CLAUDE.md",
  target: "/path/to/.cursorrules",
  force: true,
});

How It Works

1. Scanning: Uses fast-glob to recursively find AI instruction files
2. Conflict Detection: Compares file content hashes to detect actual conflicts
3. Symlink Creation: Creates relative symlinks for portability across machines
4. Cross-Platform: Works on macOS, Linux, and Windows (with Developer Mode or admin)

Windows Notes

On Windows, creating symlinks requires either:

• Developer Mode enabled (Settings > Update & Security > For Developers)
• Administrator privileges

If symlinks aren't available, agentssync will fall back to hard links.

Examples

Example 1: New Project Setup

# Create your instruction file
echo "# Project Instructions\n\nUse TypeScript..." > CLAUDE.md

# Sync to all agents
agentssync -y

Example 2: Preview Changes

$ agentssync --dry-run

┌  agentssync
│
◇  Found 1 file(s)
│
●  Found 1 AI instruction file(s):
│    Claude Code: CLAUDE.md (source)
│
◆  Using source: CLAUDE.md
│
●  Symlinks to create:
│    AGENTS.md -> CLAUDE.md
│    .cursorrules -> CLAUDE.md
│    .windsurfrules -> CLAUDE.md
│
▲  Dry run - no files were actually created
│
└  Done!

Example 3: Custom Config

// .agentssync.json
{
  "excludeAgents": ["copilot", "amazonq"],
  "customAgents": [
    {
      "id": "internal",
      "name": "Internal AI Tool",
      "patterns": [".internal/ai-rules.md"],
      "primaryFile": ".internal/ai-rules.md",
      "priority": 80
    }
  ]
}

Development

# Clone the repo
git clone https://github.com/mrtungdev/agentssync.git
cd agentssync

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun test

# Run tests with coverage
bun run test:coverage

# Link for local testing
bun link
agentssync --help

Contributing

Contributions are welcome! Here's how you can help:

Adding New AI Agents

1. Edit src/agents.ts
2. Add your agent to the DEFAULT_AGENTS array:

{
  id: "new-agent",
  name: "New Agent Name",
  patterns: [".newagent-rules"],
  description: "Description of the agent",
  primaryFile: ".newagent-rules",
  priority: 50,
}

3. Add tests in tests/agents.test.ts
4. Submit a PR

Reporting Issues

• Use GitHub Issues
• Include your OS, Node.js version, and steps to reproduce

Pull Request Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (bun test)
5. Commit with clear messages
6. Push and create a Pull Request

Roadmap

• [ ] Watch mode for auto-syncing on file changes
• [ ] GitHub Action for CI/CD integration
• [ ] VSCode extension
• [ ] Bi-directional sync detection
• [ ] Template system for instruction files

License

MIT License - see LICENSE for details.