agentsync (Spyrae)

代理同步

跨AI编码代理同步MCP服务器配置和规则。

______________________________________________________________________

问题

您使用多个AI编码代理——Claude Code、Cursor、Codex、Gemini。每个都以自己的格式（JSON、TOML）和自己的位置存储MCP服务器配置。手动保持它们同步是乏味且容易出错的。

解决方案

代理同步 获取单个真实源（您的Claude Code配置），并使用一个命令将其同步到所有代理。

┌──────────────┐
│  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   │  │              │
└──────────────┘  └──────────────┘  └──────────────┘

安装

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

快速开始

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

特性

• MCP服务器同步 --JSON↔ TOML自动转换
• 规则同步 --Markdown→ 使用frontmatter过滤Markdown/MDC
• 不区分大小写的重复数据删除 --手柄 Notion 对比 notion 来自不同来源
• 干运行模式 --编写前预览更改
• 备份 --每次写入前自动备份
• 验证 --结构检查、一致性、重复检测
• 可扩展 --基于适配器的架构用于添加新代理

支持的代理

配置

创建 agentsync.yaml 在项目根目录中：

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参考

全局选项

命令

# 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

退出代码

运作原理

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)

添加适配器

agentsync是为扩展而设计的。要添加对新AI代理的支持：

1. 创建 src/agentsync/adapters/youragent.py --执行 TargetAdapter
2. 在中注册 cli.py (create_targets)
3. 将类型添加到 KNOWN_TARGET_TYPES 在 config.py
4. 在中编写测试 tests/test_adapter_youragent.py
5. 更新此自述文件

看 贡献.md 了解详细的指南和完整的适配器接口。

贡献

欢迎投稿！看 贡献.md 作为指导方针。

请查看我们的 行为准则 在做出贡献之前。

更新日志

看 更改日志.md 发布历史。

许可证

麻省理工学院