agentsync

One source of truth for your AI coding-agent rules.

🔗 Live playground: https://panishandsome.github.io/ai-rules-sync/

Codex reads AGENTS.md. Claude Code reads CLAUDE.md. Cursor reads .cursorrules. Copilot reads .github/copilot-instructions.md. Keeping them in sync by hand is tedious and they drift. agentsync converts between all of them — or generates a clean AGENTS.md from a short spec.

Zero dependencies. The exact same engine (src/core/agentsync.js) powers both the CLI and the browser playground.

Install

npm install -g @panishandsome/agentsync   # installs the `agentsync` command
# or run without installing:
npx @panishandsome/agentsync --help

Or just clone and run from source — there are no dependencies:

git clone https://github.com/PanisHandsome/ai-rules-sync
cd ai-rules-sync
node bin/agentsync.mjs --help

Set it up in one command

agentsync setup

That's the lazy path. In your repo it: generates AGENTS.md (by scanning the project), writes an agentsync.json, runs the first sync, and installs a git pre-commit hook so every commit keeps the files in sync. From then on you just edit AGENTS.md and commit. Use agentsync setup --auto to let the hook accept edits to any rule file, or --no-hook to skip the hook.

Quick start (manual)

# Point it at your repo and let it write AGENTS.md for you
agentsync init

# Convert an existing rule file
agentsync convert .cursorrules --to agents -o AGENTS.md
agentsync convert CLAUDE.md --to copilot

# Generate from explicit fields instead of scanning
agentsync generate --name my-app --language TypeScript --framework Next.js \
    --test "pnpm test" --build "pnpm build" -o AGENTS.md

# Check an AGENTS.md for stale commands / missing paths
agentsync lint AGENTS.md

Keep one source of truth, sync the rest

Write AGENTS.md once and let the other tools' files be generated from it. Create the config (it auto-detects which rule files you already have):

agentsync sync --init      # writes agentsync.json

{
  "source": "AGENTS.md",
  "targets": ["CLAUDE.md", ".cursorrules", ".github/copilot-instructions.md"]
}

agentsync sync            # regenerate every target from AGENTS.md
agentsync sync --watch    # regenerate on every save
agentsync sync --check    # CI: exit non-zero if anything is out of sync

Make it automatic with a pre-commit hook (so the committed files are always in sync):

npx husky init
echo "npx agentsync sync && git add -A" > .husky/pre-commit

Edit only AGENTS.md from then on — the other files are generated outputs.

Don't want to be tied to one file? Use --auto

With --auto you can edit whichever file your current tool prefers (CLAUDE.md in Claude Code, .cursorrules in Cursor, AGENTS.md in Codex…). agentsync tracks a snapshot in .agentsync-state.json, figures out which file you changed, and regenerates the rest from it:

agentsync sync --auto

If you edited two files since the last sync, it stops and asks which one wins:

agentsync sync --auto --source CLAUDE.md

Hook it up the same way: echo "npx agentsync sync --auto && git add -A" > .husky/pre-commit.

Merge existing files into one

Already have several rule files? Fold them into a single AGENTS.md:

agentsync merge CLAUDE.md .cursorrules -o AGENTS.md

Try it in the browser

→ https://panishandsome.github.io/ai-rules-sync/ — paste any rule file on the left, see the converted output on the right, or switch to Generate mode and fill in a short form. Runs entirely client-side; nothing is uploaded.

To run the playground locally:

npm run web      # → http://localhost:5173

Supported formats

| id | file | tool | |-----------|---------------------------------------|---------------| | agents | AGENTS.md | Codex / open standard | | claude | CLAUDE.md | Claude Code | | cursor | .cursorrules | Cursor | | copilot | .github/copilot-instructions.md | GitHub Copilot| | windsurf| .windsurfrules | Windsurf | | cline | .clinerules | Cline | | aider | CONVENTIONS.md | Aider | | gemini | GEMINI.md | Gemini CLI | | qwen | QWEN.md | Qwen Code |

Run agentsync formats to list them.

How it works

Every format is parsed into one normalized intermediate representation (sections, intro, file globs, warnings), then rendered into the target format. Adding a new tool means writing one parser and one renderer — nothing else changes. Tool-specific constructs that don't translate (Cursor's globs frontmatter, Claude's @path imports) surface as warnings instead of being silently dropped.

Flat, heading-less rule files are classified semantically: command lines, style notes, and prohibitions are sorted into proper Build & test commands, Code style and Do not sections rather than dumped into one blob.

CLI reference

agentsync init [dir] [-o <out>] [--force]
agentsync sync [--check] [--watch]
agentsync convert <file> [--to <fmt>] [--from <fmt>] [-o <out>] [--json]
agentsync merge <file> <file> ... [--to <fmt>] [-o <out>] [--json]
agentsync generate --name <n> [--language ..] [--framework ..] [--test ..] [-o <out>]
agentsync lint <file> [--strict] [--json]
agentsync detect <file> [--json]
agentsync formats

Tests

npm test

Contributing

See CONTRIBUTING.md. The repo's own AGENTS.md was generated by agentsync itself (agentsync generate), so a coding agent can pick up the conventions before touching anything.

Changelog

See CHANGELOG.md. A short build journal lives in docs/JOURNAL.md.

License

MIT — see LICENSE.