agentsync

One source of truth for all your AI coding agent rule files.

The problem

Open a typical AI-assisted project and you'll find this:

AGENTS.md          ← OpenAI Codex, OpenCode
CLAUDE.md          ← Claude Code
.cursorrules       ← Cursor (legacy)
.cursor/rules/     ← Cursor (modern)
.github/copilot-instructions.md  ← GitHub Copilot
GEMINI.md          ← Gemini CLI
.windsurfrules     ← Windsurf

Almost the same content. In every file. Maintained separately. Drifting apart.

Every time you update your coding conventions, you update seven files. Every time you add a team member using a different tool, you create another file.

agentsync fixes this.

How it works

Edit one file. Run one command. Every tool gets the right format.

pip install rulesync
rulesync init      # sets up .agentsync/rules.md
rulesync sync      # generates all rule files

rulesync sync
--------------------------------------------------
  canonical: .agentsync/rules.md
  created:   7
  updated:   0
  unchanged: 0
--------------------------------------------------
  [+] AGENTS.md
  [+] CLAUDE.md
  [+] .cursorrules
  [+] .cursor/rules/main.mdc
  [+] .github/copilot-instructions.md
  [+] GEMINI.md
  [+] .windsurfrules

Install

pip install rulesync

Zero dependencies. Pure Python 3.10+.

Quick start

# 1. Initialise in your project
cd my-project
rulesync init

# 2. Edit the canonical rules file
nano .agentsync/rules.md   # or your editor of choice

# 3. Sync to all tools
rulesync sync

# 4. Check status any time
rulesync status

# 5. Preview changes before writing
rulesync sync --dry-run

Commands

rulesync init              # initialise in current project
rulesync sync              # sync all tool files from canonical source
rulesync sync --dry-run    # preview what would change
rulesync diff              # alias for sync --dry-run
rulesync status            # check which files are out of sync
rulesync add gemini_md     # add a new tool
rulesync remove cursorrules  # remove a tool
rulesync list              # list all 9 supported tools
rulesync adopt             # adopt your existing rules as the canonical source

Supported tools

Migrating from existing files

Already have a CLAUDE.md or .cursorrules? Use rulesync adopt to import the best existing file as the canonical source:

rulesync init
rulesync adopt   # finds the most complete existing rule file and imports it
rulesync sync    # regenerate all other files from the canonical source

Python API

from agentsync import AgentSyncer

syncer = AgentSyncer()
report = syncer.sync()
print(report.summary())

# Check status
statuses = syncer.status()
for s in statuses:
    print(s["path"], s["status"])  # ok / stale / missing

# Dry run
report = syncer.sync(dry_run=True)
print(f"Would create: {report.created}, update: {report.updated}")

Pre-commit hook

Add to .pre-commit-config.yaml:

- repo: local
  hooks:
    - id: agentsync
      name: agentsync
      entry: rulesync sync
      language: system
      pass_filenames: false
      always_run: true

Now every commit automatically regenerates your rule files if the canonical source changed.

CI/CD integration

- name: Check agent rules are in sync
  run: |
    pip install rulesync
    rulesync status

rulesync status exits with code 1 if any files are stale or missing — perfect for PR checks.

The canonical format

.agentsync/rules.md is plain markdown — no special syntax to learn:

# Project Rules

## Stack
- Python 3.11+, FastAPI, PostgreSQL

## Conventions
- Use type hints throughout
- Write docstrings for all public functions
- Follow PEP 8

## Testing
- Run: pytest tests/ -v
- Coverage > 80%
- All new features need tests

## Important constraints
- Never commit secrets or credentials
- Ask before refactoring across multiple files

agentsync translates this into the right format for each tool automatically.

Why not just symlinks?

Symlinks break on Windows, don't survive git clones cleanly, and don't handle format differences between tools — Cursor's .mdc format needs YAML frontmatter, .aider.conf.yml is YAML not markdown. agentsync handles all of that.

Linda Oraegbunam | LinkedIn | Twitter | GitHub