The problem

Your team uses Cursor. And Copilot. And Claude Code. And someone's trying Windsurf. Every one of them reads its own config file:

CLAUDE.md
.cursor/rules/*.mdc
.github/copilot-instructions.md
.windsurf/rules/*.md
.clinerules/*.md
GEMINI.md
CONVENTIONS.md          # aider
.rules                  # zed

So your "use tabs, not spaces", "never touch /legacy", "tests live next to source" rules get copy-pasted into all of them — and drift out of sync the moment anyone edits one. New conventions land in CLAUDE.md but never reach Cursor. The AI happily violates rules half your tools never saw.

The fix

Keep one source of truth — AGENTS.md, the emerging open standard — and let agentsync project it into every tool's native format.

npx syncagents init     # detect your tools, create AGENTS.md, generate every config
npx syncagents watch    # edit AGENTS.md → all configs update on save

$ npx agentsync

agentsync · source: AGENTS.md
  + Claude Code      CLAUDE.md                          created
  + Cursor           .cursor/rules/agentsync.mdc        created
  + GitHub Copilot   .github/copilot-instructions.md    created
  ~ Windsurf         .windsurf/rules/agentsync.md       updated

✔ synced 4 of 4 target(s)

Edit AGENTS.md. Run agentsync. Done. Every assistant now reads the same rules.

Quick start

No install required — run it straight from npm:

# 1. Set up (auto-detects the AI tools already in your repo)
npx syncagents init

# 2. Edit AGENTS.md with your project rules, then:
npx syncagents

# Or keep it live while you work:
npx syncagents watch

The npm package is syncagents; it installs both the syncagents and agentsync commands (use whichever you like).

Prefer a local dev dependency?

npm install -D syncagents

Supported assistants

Your hand-written content is safe. For shared files like CLAUDE.md, agentsync only manages the region between its <!-- agentsync:start --> / <!-- agentsync:end --> markers. Anything you write outside those markers is preserved on every sync.

Keep your AI configs honest in CI

Add a check so a PR can't merge with stale assistant configs:

# .github/workflows/agentsync.yml
name: agentsync
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx syncagents check

agentsync check writes nothing and exits 1 if any config has drifted from AGENTS.md.

Or wire it into a pre-commit hook (e.g. with husky):

npx syncagents check

Configuration

Zero config works out of the box. To customize, init writes an agentsync.config.json:

{
  "source": "AGENTS.md",
  "targets": ["claude", "cursor", "copilot", "windsurf"]
}

You can also configure it from package.json:

{
  "agentsync": {
    "targets": ["claude", "cursor"]
  }
}

Need a target agentsync doesn't ship? Define a custom one:

{
  "targets": [
    "claude",
    { "path": "docs/ai-guidelines.md", "format": "md", "strategy": "block" }
  ]
}

• strategy: "full" — agentsync owns the whole file.
• strategy: "block" — only the marked region is managed; the rest is yours.

Commands

Flags: --cwd <dir>, --source <file>, --quiet, --help, --version.

Programmatic API

import { sync, init, detectTargets } from 'agentsync';

const report = sync({ cwd: process.cwd() });
console.log(report.inSync, report.results);

Why agentsync?

• Zero dependencies. Nothing to audit, nothing to get compromised in a supply-chain attack, installs in milliseconds.
• Non-destructive. Managed blocks mean your existing CLAUDE.md notes survive.
• Idempotent. Running it twice changes nothing the second time — safe in any hook.
• Standards-first. Built around the open AGENTS.md format.
• Cross-platform. Works on Windows, macOS, and Linux with zero dependencies.

Installation

npm install -g syncagents

FAQ

What is AGENTS.md?

AGENTS.md is the open, vendor-neutral standard for AI coding-assistant instructions (donated to the Linux Foundation, used by 60,000+ repos and read natively by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf and Zed). agentsync makes it the single source of truth and generates every tool-specific file from it.

How do I sync Cursor rules, CLAUDE.md and Copilot instructions from one file?

Run npx syncagents init, write your rules in AGENTS.md, then npx syncagents. It generates .cursor/rules/agentsync.mdc, CLAUDE.md, .github/copilot-instructions.md, Windsurf, Cline, Gemini, Aider and Zed configs — and keeps them in sync.

AGENTS.md vs CLAUDE.md vs Cursor rules vs Copilot instructions — do I need all of them?

Each AI tool reads its own file, so today you do. agentsync removes the duplication: you maintain one AGENTS.md and it projects the content into each tool's native format, so they never drift apart.

How is this different from rule-porter or copy-pasting?

agentsync is a zero-dependency CLI with a check mode (CI fails on drift), watch mode, non-destructive managed blocks (your hand-written CLAUDE.md notes survive), and idempotent output. It treats AGENTS.md as the canonical source rather than converting between formats ad hoc.

License

MIT — free for personal and commercial use.