agentsync (ai-rules-sync)

What It Does

agentsync is a zero-dependency CLI tool that converts AI coding-agent rule files between 9 formats: AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules, CONVENTIONS.md, GEMINI.md, and QWEN.md. You maintain one source file (typically AGENTS.md) and the tool regenerates all others from it. It can also generate a fresh AGENTS.md from a project spec, scan a repo to auto-detect language and framework, merge multiple existing rule files into one, lint rule files for stale commands and missing paths, and detect the format of any rule file. The core engine (467 lines) is isomorphic: it runs identically in Node.js and in a browser playground. The tool targets developers who use more than one AI coding agent and need their rule files to stay consistent without manual duplication.

The Good

Zero dependencies, 908 KB total repo, 467-line core engine. The entire conversion, generation, merge, and lint engine lives in a single file (src/core/agentsync.js) with zero imports. This means fast installs, no supply chain risk, and a codebase anyone can audit in one sitting. The published npm package is 908 KB unpacked.

67 passing tests covering every feature. The test suite covers format detection, cross-format conversion, round-trip fidelity through 5 intermediate formats, semantic parsing of flat rule files, merge deduplication, sync state tracking, auto-mode conflict detection, config initialization, lint error/warning classification, and git staging. Zero failures. CI runs on Node 18, 20, and 22.

Intelligent semantic parsing. Flat, heading-less rule files (like classic .cursorrules) get classified into semantic sections: "Build and test commands", "Code style and conventions", and "Do not". Command lines, style notes, and prohibitions are sorted by heuristic classifiers rather than dumped into one blob. This produces cleaner output than a naive line-by-line copy.

9 format support with honest warnings. Every format pair gets a dedicated parser and renderer. Tool-specific constructs that lack an equivalent in other formats (Cursor's globs frontmatter, Claude's @path imports) produce explicit warnings instead of silent data loss. The user always knows what did not translate.

One-command setup with git hook integration. agentsync setup generates AGENTS.md from a repo scan, writes the config, runs the first sync, and installs a pre-commit hook. The --auto flag lets the hook accept edits to any rule file (not just the source), making the workflow flexible for teams that switch between tools.

The Bad

Single-commit repo, young project. The entire history is one commit (9d6b3e1). All three versions (0.1.0, 0.2.0, 0.3.0, 0.3.1) shipped within 3 days (June 1-3, 2026). The changelog documents version progression, but there is no issue history, no PR history, and no track record of responding to community feedback. The tool works today, but long-term maintenance is uncertain.

Round-trip fidelity is structural, not exact. Converting AGENTS.md to CLAUDE.md and back preserves headings, commands, and bullet text, but whitespace, blank line counts, and trailing newlines may shift. Users expecting byte-identical round-trips will find small diffs. The tests verify content preservation, not exact byte equality.

No error recovery for malformed input. The parser handles frontmatter and headings, but feeding it binary data or severely corrupted text produces unhelpful errors. A --strict lint flag exists, but the convert command does not validate input before parsing. This is fine for the intended use case (rule files are always text) but worth knowing.

Sync does not handle nested targets or monorepos. The agentsync.json config expects flat file paths relative to the config location. Teams with monorepo structures (multiple packages, each with their own CLAUDE.md) need to run agentsync per-package rather than once at the root. This is a current limitation, not a bug.

Smoke Test Results

All testing done on macOS (host), aarch64, Node.js 22.x. The repo was cloned from GitHub and the npm package was verified via npx.

Run A -- Fresh npx install

$ npx @panishandsome/agentsync@latest --help
agentsync: one source of truth for your AI coding-agent rules
...
 agentsync setup [--auto] [--no-hook]
 agentsync init [dir] [-o <out>] [--force]
 agentsync sync --init
 agentsync sync [--check] [--watch]
 agentsync sync --auto [--source <file>]
 agentsync convert <file> [--to agents|claude|cursor|copilot|windsurf|cline|aider|gemini] [--from <fmt>] [-o <out>]
 agentsync merge <file> <file> ... [--to <fmt>] [-o <out>]
 agentsync generate --name <n> [--language ts] [--framework next] [--test "npm test"] ... [-o <out>]
 agentsync lint <file> [--strict]
 agentsync detect <file>
 agentsync formats

✅ npx install and help output work.

Pass rate: 1 of 1.

Run B -- Unit test suite

$ cd /tmp/ai-rules-sync && node test/run.mjs
 ✓ detect filename .cursorrules
 ✓ detect filename CLAUDE.md
 ✓ detect copilot by path
 ✓ cursor→agents has AGENTS title
 ✓ cursor→agents keeps rules
 ✓ claude @import produces a warning
 ✓ claude→copilot keeps Setup heading
 ✓ generate has title
 ✓ generate includes test cmd
 ✓ generate has PR checklist
 ... (57 more tests)
 67 passed, 0 failed

✅ All 67 tests pass.

Pass rate: 67 of 67. This is the canonical pass rate.

Run C -- Functional verification (end-to-end sync workflow)

$ mkdir /tmp/agentsync-func-test && cd /tmp/agentsync-func-test && git init -q
$ echo '{"name":"test","type":"module","scripts":{"test":"npm test","build":"npm run build"}}' > package.json
$ node /tmp/ai-rules-sync/bin/agentsync.mjs generate --name "test-project" --language TypeScript --test "npm test" --build "npm run build" -o AGENTS.md
✓ wrote AGENTS.md

$ node /tmp/ai-rules-sync/bin/agentsync.mjs sync --init
✓ wrote agentsync.json
 source: AGENTS.md
 targets: CLAUDE.md, .cursorrules

$ node /tmp/ai-rules-sync/bin/agentsync.mjs sync
✓ updated CLAUDE.md
 ✓ updated .cursorrules

$ cat CLAUDE.md
# test-project
...
## Build & test commands
- Install: `npm install`
- Build: `npm run build`
- Test: `npm test`
...

$ node /tmp/ai-rules-sync/bin/agentsync.mjs lint AGENTS.md
✓ AGENTS.md looks good

$ node /tmp/ai-rules-sync/bin/agentsync.mjs formats
agents AGENTS.md AGENTS.md (Codex / open standard)
claude CLAUDE.md CLAUDE.md (Claude Code)
cursor .cursorrules .cursorrules (Cursor)
copilot .github/copilot-instructions.md copilot-instructions.md (GitHub Copilot)
windsurf .windsurfrules .windsurfrules (Windsurf)
cline .clinerules .clinerules (Cline)
aider CONVENTIONS.md CONVENTIONS.md (Aider)
gemini GEMINI.md GEMINI.md (Gemini CLI)
qwen QWEN.md QWEN.md (Qwen Code)

$ node /tmp/ai-rules-sync/bin/agentsync.mjs convert examples/.cursorrules --to agents
# AGENTS.md
...
## Build & test commands
- Install deps with `uv sync`.
...
## Do not
Never commit secrets. Do not edit anything under `app/migrations/`.

$ node /tmp/ai-rules-sync/bin/agentsync.mjs convert examples/.cursorrules --to copilot --json
{
 "from": "cursor",
 "to": "copilot",
 "warnings": [],
 "output": "# Copilot instructions\n..."
}

✅ Generate, sync init, sync, lint, formats, convert (with --json), and semantic parsing all work correctly.

Functional pass rate: 8 of 8.

What the runs tell you

The npx install works immediately. All 67 unit tests pass, covering every feature from format detection to conflict resolution. The end-to-end functional test proves that the core workflow (generate, sync to multiple targets, convert between formats, lint) works as documented. The tool delivers on every claim in the README.

Setup Walkthrough

1. Install: npx @panishandsome/agentsync@latest --help (no install needed, or npm install -g @panishandsome/agentsync).
2. In your repo: agentsync setup to generate AGENTS.md from a scan, create config, run first sync, and install a pre-commit hook.
3. Edit only AGENTS.md from then on. The pre-commit hook regenerates CLAUDE.md, .cursorrules, and other targets before each commit.
4. For CI: agentsync sync --check exits non-zero if any target is out of sync.
5. For flexible editing: agentsync sync --auto lets you edit whichever file your current tool prefers, and regenerates the rest.

No post-install gotchas. Node 18+ is required. The tool has zero runtime dependencies.

Alternatives

1. he-yufeng/RuleForge -- auto-generates agent rules from codebase analysis rather than syncing existing ones. Complementary: use RuleForge to generate, agentsync to sync.
2. razr001/align-dev -- generates shared coding standards as SKILL.md for multi-agent teams. Higher level (team standards) vs agentsync's lower level (file format conversion).
3. Manual copy-paste -- the default for most teams. Works until rule files drift apart, which happens faster than most teams expect.