agentsync

Sync MCP server configs and rules across AI coding agents.

The Problem

You use multiple AI coding agents — Claude Code, Cursor, Codex, Gemini. Each stores MCP server configs in its own format (JSON, TOML) and its own location. Keeping them in sync manually is tedious and error-prone.

The Solution

agentsync takes a single source of truth (your Claude Code config) and syncs it to all your agents with one command.

┌──────────────┐
│  Claude Code │  Source of Truth
│  .claude.json│  ─── MCP Servers
│  .mcp.json   │  ─── Rules (CLAUDE.md)
│  CLAUDE.md   │
└──────┬───────┘
       │  agentsync sync
       ├──────────────────┐─────────────────┐
       ▼                  ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│    Cursor    │  │    Codex     │  │  Antigravity │
│  mcp.json   │  │ config.toml  │  │mcp_config.json│
│ project.mdc │  │  AGENTS.md   │  │              │
└──────────────┘  └──────────────┘  └──────────────┘

Installation

pip install agentsync-cli     # pip
pipx install agentsync-cli    # pipx (recommended for CLI tools)
uvx agentsync-cli             # uv (run without installing)

Quick Start

agentsync init       # Create agentsync.yaml config
agentsync sync       # Sync to all agents
agentsync validate   # Verify everything is correct

Features

• MCP server sync — JSON ↔ TOML automatic conversion
• Rules sync — Markdown → filtered Markdown / MDC with frontmatter
• Case-insensitive deduplication — handles Notion vs notion from different sources
• Dry-run mode — preview changes before writing
• Backups — automatic backups before every write
• Validation — structural checks, consistency, duplicate detection
• Extensible — adapter-based architecture for adding new agents

Supported Agents

Configuration

Create agentsync.yaml in your project root:

version: 1

source:
  type: claude
  global_config: ~/.claude.json
  project_mcp: .mcp.json
  rules_file: CLAUDE.md

targets:
  cursor:
    type: cursor
    mcp_path: ~/.cursor/mcp.json
    rules_path: .cursor/rules/project.mdc
    exclude_servers: []

  codex:
    type: codex
    config_path: ~/.codex/config.toml
    rules_path: AGENTS.md
    exclude_servers: [codex]

  antigravity:
    type: antigravity
    mcp_path: ~/.gemini/antigravity/mcp_config.json
    protocols: [stdio]

rules:
  exclude_sections:
    - "MCP Servers"
    - "Context Management & Agents"

CLI Reference

Global Options

Commands

# Sync — push source configs to targets
agentsync sync                  # Full sync (MCP + rules)
agentsync sync --dry-run        # Preview changes without writing
agentsync sync --mcp-only       # Only MCP server configs
agentsync sync --rules-only     # Only rules files
agentsync sync -t cursor        # Sync specific target only
agentsync sync --no-backup      # Skip creating backup files

# Validate — check target configs match source
agentsync validate              # Full validation
agentsync validate -v           # Verbose (show passed checks too)
agentsync validate -t codex     # Validate specific target only

# Init — create config
agentsync init                  # Create agentsync.yaml
agentsync init --force          # Overwrite existing config

# Status — show sync state
agentsync status                # Source info, target health, drift

Exit Codes

How It Works

agentsync sync
  │
  ├─ Load config (agentsync.yaml)
  ├─ Read source (Claude Code)
  │   ├─ ~/.claude.json         → global MCP servers
  │   ├─ .mcp.json              → project MCP servers
  │   └─ CLAUDE.md              → rules sections
  │
  ├─ Deduplicate (case-insensitive)
  ├─ Filter (exclude_servers, exclude_sections, protocols)
  │
  └─ Generate + Write per target
      ├─ Cursor:       mcp.json + project.mdc (MDC frontmatter)
      ├─ Codex:        config.toml (marker-based) + AGENTS.md
      └─ Antigravity:  mcp_config.json (stdio-only)

Adding an Adapter

agentsync is designed for extension. To add support for a new AI agent:

1. Create src/agentsync/adapters/youragent.py — implement TargetAdapter
2. Register it in cli.py (create_targets)
3. Add the type to KNOWN_TARGET_TYPES in config.py
4. Write tests in tests/test_adapter_youragent.py
5. Update this README

See CONTRIBUTING.md for detailed guidelines and the full adapter interface.

Roadmap

Have an idea? Open a discussion or request an adapter.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Please review our Code of Conduct before contributing.

Changelog

See CHANGELOG.md for release history.

License

MIT