agentsync

One source of truth for all your AI coding agents.

Write your project rules once in AGENTS.md, and agentsync mirrors them to every tool — Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, Aider, and Gemini CLI. No more keeping six near-identical instruction files in sync by hand.

---

The problem

You use more than one AI coding tool. Each wants its own rules file:

Tool	File it reads
Claude Code	CLAUDE.md
Cursor	.cursor/rules/*.mdc
Windsurf	.windsurfrules
GitHub Copilot	.github/copilot-instructions.md
Cline	.clinerules
Aider	CONVENTIONS.md
Gemini CLI	GEMINI.md

Update your conventions once and you have to copy-paste into all of them. They drift. Some get stale. New teammates' tools get the wrong rules.

The fix

npx @keradd/agentsync init     # creates AGENTS.md + agentsync.json
npx @keradd/agentsync sync     # generates every tool file from AGENTS.md

Now AGENTS.md is the single source. Edit it, run sync, done. Every generated file carries a banner so nobody edits the wrong one by accident.

Install

Run it on demand with npx @keradd/agentsync …, or install globally:

npm install -g @keradd/agentsync

Commands

Command	What it does
agentsync init	Scaffold AGENTS.md and agentsync.json.
agentsync sync	Generate every enabled target file from the source.
agentsync check	Verify all targets are in sync — exits 1 if not. Great for CI.
agentsync list	Show every supported target.

Options

Flag	Applies to	Effect
--dry-run	sync	Preview changes without writing.
--force	init	Overwrite existing files.
--cwd <dir>	all	Run against another directory.
-h, --help	—	Show help.
-v, --version	—	Show version.

Configuration

agentsync.json is optional — without it, every target is generated from AGENTS.md. To customize:

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

• source — the canonical file you edit. Default AGENTS.md.
• targets — which tools to generate. Default: all. Run agentsync list for ids.

Keep it enforced in CI

Add a check so a stale rules file can never be merged:

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

If someone edits AGENTS.md without running sync, CI fails with a clear list of what's stale.

How it works

agentsync reads your source file and renders one output per target, each with a managed banner header. For Cursor it emits a proper .mdc rule with frontmatter; everything else is plain markdown. Generation is deterministic and idempotent — running sync twice changes nothing the second time, which is exactly what makes check reliable.

The codebase keeps pure logic (src/core.js, src/targets.js) separate from filesystem side-effects (src/fs.js), so behavior is easy to test and easy to extend.

Adding a new tool

Open src/targets.js and add one adapter:

{
  id: "mytool",
  label: "My Tool",
  path: ".mytoolrules",
  render: md, // or a custom (source, body) => string
}

Add a test, run npm test, send a PR. See CONTRIBUTING.md.

Development

npm install
npm test     # node:test — unit + end-to-end CLI tests
npm start    # run the CLI locally

License

MIT © Keradd