syncagents 1.0.2

One AGENTS.md, every AI coding assistant in sync. Generate CLAUDE.md, Cursor rules, GitHub Copilot instructions, Windsurf, Cline, Gemini, Aider & Zed from a single source of truth. Zero-dependency CLI for the AGENTS.md standard.

🔄 agentsync

One AGENTS.md. Every AI coding assistant in sync.

Stop maintaining the same rules in 6 different files. Write your project's AI instructions once — agentsync generates and keeps in sync CLAUDE.md, Cursor rules, GitHub Copilot instructions, Windsurf, Cline, Gemini, Aider, Zed and more.

---

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 type hints", "never touch /legacy", "tests live in tests/" 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.

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

$ uvx 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 with uv:

uvx agentsync init     # set up (auto-detects the AI tools already in your repo)
# edit AGENTS.md, then:
uvx agentsync          # sync once
uvx agentsync watch    # keep it live while you work

Or install it:

pip install agentsync      # or: pipx install agentsync
agentsync init

Supported assistants

Tool	Generated file	Format
Claude Code	CLAUDE.md	markdown (managed block)
Cursor	.cursor/rules/agentsync.mdc	.mdc + frontmatter
GitHub Copilot	.github/copilot-instructions.md	markdown (managed block)
Windsurf	.windsurf/rules/agentsync.md	markdown
Cline	.clinerules/agentsync.md	markdown
Gemini CLI	GEMINI.md	markdown (managed block)
Aider	CONVENTIONS.md	markdown (managed block)
Zed	.rules	markdown
Anything else	custom path you define	markdown

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 outside those markers is preserved on every sync.

Keep your AI configs honest in CI

# .github/workflows/agentsync.yml
name: agentsync
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uvx agentsync check

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

Pre-commit hook:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: agentsync
        name: agentsync check
        entry: agentsync check
        language: system
        pass_filenames: false

Configuration

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

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

You can also configure it from pyproject.toml:

[tool.agentsync]
targets = ["claude", "cursor"]

Custom target not shipped by default:

{
  "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

Command	What it does
agentsync init	Create AGENTS.md + config, detect tools, run first sync
agentsync / agentsync sync	Regenerate all configs from AGENTS.md
agentsync check	CI mode — exit 1 if anything is out of sync
agentsync watch	Re-sync automatically on every save
agentsync list	Show supported assistants and which are detected

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

Python API

from agentsync import sync, init, detect_targets

report = sync()
print(report.in_sync, [r.path for r in report.results])

Why agentsync?

• Zero dependencies. Nothing to audit, installs instantly, nothing to be compromised in a supply-chain attack.
• 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.
• Mirror on npm. JS shop too? syncagents on npm produces byte-identical output — npx 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 in Python?

Run uvx agentsync init, write your rules in AGENTS.md, then uvx agentsync. 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: 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.

_{If agentsync saves you from one more copy-pasted rule, give it a ⭐ — it helps other devs find it.}