sync-agents-settings

March 29, 2026 · View on GitHub

將 Claude Code 的 MCP server 設定和指令檔（CLAUDE.md）同步到 Gemini CLI、Codex CLI、OpenCode、Kiro CLI、Cursor、Kimi CLI、Vibe CLI（Mistral）、Qwen Code、Amp（Sourcegraph）、Cline CLI、Windsurf 和 Aider CLI。

其他語言： 🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 支援矩陣： CLI 相容性矩陣

為什麼需要這個工具

如果你主要用 Claude Code 開發，但也會切換其他 AI agent（Gemini CLI、Codex CLI、OpenCode、Kiro、Cursor、Kimi CLI、Vibe CLI、Qwen Code、Amp、Cline CLI、Windsurf、Aider CLI）來善用各家的免費額度或不同模型，你一定知道這個痛點 — 每個工具的 MCP 設定格式都不一樣，一個一個設定實在太累。指令檔也是一樣 — CLAUDE.md、GEMINI.md、AGENTS.md、CONVENTIONS.md 都需要同樣的內容，但格式各不相同。

這個工具讓你只在 Claude Code 設定一次 MCP servers 和撰寫指令，一行指令同步到所有目標。

快速開始

方式 A：Claude Code Plugin（推薦）

透過 marketplace 安裝 Claude Code plugin：

# 1. 新增 marketplace
claude plugin marketplace add Leoyang183/sync-agents-settings

# 2. 安裝 plugin
claude plugin install sync-agents-settings

# 在任何對話中使用 slash commands：
#   /sync               — 同步 MCP 設定（含 dry-run 預覽）
#   /sync-list          — 列出所有 MCP servers
#   /sync-diff          — 比較各 agent 的設定差異
#   /sync-doctor        — 偵測 MCP 設定偏移
#   /sync-validate      — 驗證 schema 與目標相容性
#   /sync-reconcile     — 驗證 + 偵測偏移 + 只同步缺少的
#   /sync-instructions  — 同步 CLAUDE.md 到其他 agent
#   /report-schema      — 產生或寫入 report JSON schema 文件

Plugin 還包含 sync-awareness skill，當你編輯 MCP 設定或 CLAUDE.md 時會自動建議同步。

方式 B：透過 npx

不需安裝，直接用 npx：

# 列出所有 Claude Code 的 MCP servers
npx sync-agents-settings list

# 預覽同步（不修改任何檔案）
npx sync-agents-settings sync --dry-run

# 同步到所有目標（自動備份）
npx sync-agents-settings sync

# 同步 CLAUDE.md 指令檔到所有目標
npx sync-agents-settings sync-instructions

方式 C：全域安裝

# 全域安裝，使用 sync-agents 指令
npm install -g sync-agents-settings

# 直接使用
sync-agents list
sync-agents sync

使用方式

# 同步到特定目標
sync-agents sync --target gemini
sync-agents sync --target codex
sync-agents sync --target opencode
sync-agents sync --target kiro
sync-agents sync --target cursor
sync-agents sync --target kimi
sync-agents sync --target vibe
sync-agents sync --target qwen
sync-agents sync --target amp
sync-agents sync --target cline
sync-agents sync --target windsurf

# 同步到 Codex 專案層級設定
sync-agents sync --target codex --codex-home ./my-project/.codex

# 同步到 Kimi 專案層級設定
sync-agents sync --target kimi --kimi-home ./my-project/.kimi

# 比較差異
sync-agents diff

# 跳過需要 OAuth 的伺服器（如 Slack）
sync-agents sync --skip-oauth

# 跳過備份
sync-agents sync --no-backup

# 詳細輸出
sync-agents sync -v

# 同步指令檔（CLAUDE.md → GEMINI.md / AGENTS.md / Kiro steering / Cursor rules / Amp AGENTS.md / Qwen AGENTS.md / Aider conventions）
sync-agents sync-instructions

# 只同步全域指令
sync-agents sync-instructions --global

# 只同步專案層級指令
sync-agents sync-instructions --local

# 同步到特定目標
sync-agents sync-instructions --target gemini codex kimi vibe qwen amp aider

# 自動覆蓋不詢問（適用於 CI）
sync-agents sync-instructions --on-conflict overwrite

# 保留舊行為：移除獨立行 @import，不展開內容
sync-agents sync-instructions --import-mode strip

# 允許獨立行 @import 讀取專案根目錄外檔案（請謹慎使用）
sync-agents sync-instructions --allow-unsafe-imports

# 預覽指令同步
sync-agents sync-instructions --dry-run

運作原理

Claude Code 是 MCP 設定的 single source of truth，同步到所有支援的目標。

                                                 ┌─→ Gemini Writer   ─→ ~/.gemini/settings.json
                                                 ├─→ Codex Writer    ─→ ~/.codex/config.toml
~/.claude.json ─────┐                            │
                     ├─→ Reader ─→ UnifiedMcpServer[] ─┼─→ OpenCode Writer ─→ ~/.config/opencode/opencode.json
~/.claude/plugins/ ──┘                            │
                                                 ├─→ Kiro Writer     ─→ ~/.kiro/settings/mcp.json
                                                 ├─→ Cursor Writer   ─→ ~/.cursor/mcp.json
                                                 ├─→ Kimi Writer     ─→ ~/.kimi/mcp.json
                                                 ├─→ Vibe Writer     ─→ ~/.vibe/config.toml
                                                 ├─→ Qwen Writer     ─→ ~/.qwen/settings.json
                                                 ├─→ Amp Writer      ─→ ~/.config/amp/settings.json
                                                 ├─→ Cline Writer    ─→ ~/.cline/data/settings/cline_mcp_settings.json
                                                 └─→ Windsurf Writer ─→ ~/.codeium/windsurf/mcp_config.json

階段	說明
Reader	從 `~/.claude.json` 和已啟用 plugin 的 `.mcp.json` 讀取，合併為統一格式
Gemini Writer	JSON → JSON，`type: "http"` → `httpUrl`，`${VAR}` → `$VAR`
Codex Writer	JSON → TOML，`${VAR:-default}` → 展開為實際值
OpenCode Writer	JSON → JSON，`command`+`args` → 合併為 `command` 陣列，`env` → `environment`，`type: "local"`/`"remote"`
Kiro Writer	與 Claude 相同格式，`${VAR:-default}` → 展開
Cursor Writer	與 Claude 相同格式，`${VAR:-default}` → 展開
Kimi Writer	與 Claude 相同格式，`${VAR:-default}` → 展開
Vibe Writer	JSON → TOML `[[mcp_servers]]`，需要 transport 欄位，`${VAR:-default}` → 展開
Qwen Writer	JSON → JSON，`type: "http"` → `httpUrl`，`${VAR}` → `$VAR`（與 Gemini 相同模式）
Amp Writer	JSON → JSON，使用 `"amp.mcpServers"` 點號鍵，`${VAR}` 保留
Cline Writer	與 Claude 相同格式（Claude format）
Windsurf Writer	JSON → JSON，`url` → `serverUrl`，`${VAR}` → `${env:VAR}`

指令檔同步（`sync-instructions`）

將 CLAUDE.md 指令檔同步到各目標的原生格式：

目標	全域路徑	專案路徑	格式轉換
Gemini	`~/.gemini/GEMINI.md`	`./GEMINI.md`	直接複製（展開獨立行 `@import`）
Codex	`~/.codex/AGENTS.md`	`./AGENTS.md`	直接複製（展開獨立行 `@import`）
OpenCode	`~/.config/opencode/AGENTS.md`	`./AGENTS.md`（與 Codex 共用）	直接複製（展開獨立行 `@import`）
Kimi	`~/.kimi/AGENTS.md`	`./AGENTS.md`（與 Codex / OpenCode / Vibe 共用）	直接複製（展開獨立行 `@import`）
Vibe	`~/.vibe/AGENTS.md`	`./AGENTS.md`（與 Codex / OpenCode / Kimi 共用）	直接複製（展開獨立行 `@import`）
Qwen	`~/.qwen/AGENTS.md`	`./AGENTS.md`（與 Codex / OpenCode / Kimi / Vibe 共用）	直接複製（展開獨立行 `@import`）
Amp	`~/.config/amp/AGENTS.md`	`./AGENTS.md`（與 Codex / OpenCode / Kimi / Vibe / Qwen 共用）	直接複製（展開獨立行 `@import`）
Aider	`~/.aider/CONVENTIONS.md`	`.aider/CONVENTIONS.md`	直接複製 + 自動更新 `.aider.conf.yml` `read`
Kiro	`~/.kiro/steering/claude-instructions.md`	`.kiro/steering/claude-instructions.md`	加上 `inclusion: always` frontmatter
Cursor	不支援（SQLite）	`.cursor/rules/claude-instructions.mdc`	加上 `alwaysApply: true` frontmatter

當目標檔案已存在時，會詢問你選擇：覆蓋、附加（保留原有內容 + 加上 CLAUDE.md）、或跳過。使用 --on-conflict overwrite|append|skip 可跳過互動式詢問。

補充：

專案來源會優先使用 ./.claude/CLAUDE.md，不存在時 fallback ./CLAUDE.md。
會自動合併 .claude/rules/**/*.md（若已被 @import 引入則不重複）。
若 rule frontmatter 含 paths，僅在至少一個專案檔案符合時才會套用。
@import 預設為 inline（展開內容），可用 --import-mode strip 改成只移除獨立行 @import。
預設只允許獨立行 @import 讀取目前專案根目錄內的檔案；若需放寬可加 --allow-unsafe-imports。
內嵌展開有防護上限（最大深度 20、最大檔案數 200），避免遞迴展開失控。
Aider 同步會自動補上 .aider.conf.yml 的 read，讓 CONVENTIONS.md 在 global/project 都可自動載入。
Kimi CLI 目前只會從工作目錄載入 AGENTS.md；~/.kimi/AGENTS.md 會作為可重用的全域模板同步。

安全機制

已存在的 server 不會覆蓋（idempotent，可重複執行）
預設自動備份到 ~/.sync-agents-backup/（--no-backup 跳過）
--dry-run 預覽變更，不寫入任何檔案

設定檔路徑

工具	設定檔路徑	格式
Claude Code（使用者 MCP）	`~/.claude.json`	JSON
Claude Code（設定）	`~/.claude/settings.json`	JSON
Claude Code（plugin MCP）	`~/.claude/plugins/cache/.../.mcp.json`	JSON
Gemini CLI	`~/.gemini/settings.json`	JSON
Codex CLI（全域）	`~/.codex/config.toml`	TOML
Codex CLI（專案）	`.codex/config.toml`（用 `--codex-home`）	TOML
OpenCode（全域）	`~/.config/opencode/opencode.json`	JSON
Kiro CLI（全域）	`~/.kiro/settings/mcp.json`	JSON
Cursor（全域）	`~/.cursor/mcp.json`	JSON
Kimi CLI（全域）	`~/.kimi/mcp.json`	JSON
Kimi CLI（專案）	`.kimi/mcp.json`（用 `--kimi-home ./.kimi`）	JSON
Vibe CLI（全域）	`~/.vibe/config.toml`	TOML
Vibe CLI（專案）	`.vibe/config.toml`（用 `--vibe-home ./.vibe`）	TOML
Qwen Code（全域）	`~/.qwen/settings.json`	JSON
Amp（全域）	`~/.config/amp/settings.json`	JSON
Cline CLI（全域）	`~/.cline/data/settings/cline_mcp_settings.json`	JSON
Windsurf（全域）	`~/.codeium/windsurf/mcp_config.json`	JSON

指令檔路徑

工具	全域路徑	專案路徑	格式
Claude Code	`~/.claude/CLAUDE.md`	`./.claude/CLAUDE.md`（fallback `./CLAUDE.md`）	Markdown
Gemini CLI	`~/.gemini/GEMINI.md`	`./GEMINI.md`	Markdown
Codex CLI	`~/.codex/AGENTS.md`	`./AGENTS.md`	Markdown
OpenCode	`~/.config/opencode/AGENTS.md`	`./AGENTS.md`	Markdown
Kimi CLI	`~/.kimi/AGENTS.md`	`./AGENTS.md`	Markdown
Vibe CLI	`~/.vibe/AGENTS.md`	`./AGENTS.md`	Markdown
Qwen Code	`~/.qwen/AGENTS.md`	`./AGENTS.md`	Markdown
Amp	`~/.config/amp/AGENTS.md`	`./AGENTS.md`	Markdown
Aider CLI	`~/.aider/CONVENTIONS.md`	`.aider/CONVENTIONS.md`	Markdown
Kiro CLI	`~/.kiro/steering/claude-instructions.md`	`.kiro/steering/claude-instructions.md`	Markdown + frontmatter
Cursor	不支援（SQLite）	`.cursor/rules/claude-instructions.mdc`	MDC（Markdown + frontmatter）
Cline CLI	不支援指令同步	不支援指令同步	—
Windsurf	不支援指令同步	不支援指令同步	—

Claude Code Plugin

本專案同時是 Claude Code plugin 和 marketplace，在 Claude Code 對話中直接提供 slash commands 和情境感知 skill。

安裝

# 從 GitHub 安裝（遠端 — clone repo）
claude plugin marketplace add Leoyang183/sync-agents-settings
claude plugin install sync-agents-settings

# 或從本地路徑安裝（symlink — 即時反映本地變更）
claude plugin marketplace add /path/to/sync-agents-settings
claude plugin install sync-agents-settings

Slash Commands

指令	說明
`/sync`	同步 MCP server 設定到其他 agent（含 dry-run 預覽和確認）
`/sync-list`	列出所有 Claude Code 中的 MCP servers
`/sync-diff`	比較 Claude 和其他 agent 之間的 MCP 設定差異
`/sync-doctor`	偵測 Claude 和目標之間的 MCP 設定偏移
`/sync-validate`	驗證 MCP schema 與目標能力相容性
`/sync-reconcile`	驗證 + 偵測偏移 + 只同步缺少的 server
`/sync-instructions`	同步 CLAUDE.md 指令檔到其他 agent 格式
`/report-schema`	產生或寫入 report JSON schema 文件

Sync-Awareness Skill

Plugin 包含一個 skill，會自動偵測你正在編輯 MCP 設定（.claude.json、.mcp.json）或 CLAUDE.md 檔案時，建議同步到其他 agent。

Plugin 開發

# 驗證 plugin/marketplace 結構
claude plugin validate /path/to/sync-agents-settings

限制

OAuth servers（如 Slack）只會同步 URL，需要在各 CLI 手動認證
${CLAUDE_PLUGIN_ROOT} 環境變數在其他 CLI 中無法解析
Codex CLI 不支援 URL 中的 ${VAR:-default} 語法，同步時會自動展開
重複執行不會覆蓋已存在的設定（安全可重複）
若目標設定目錄不存在，會跳過該目標（不會自動建立目錄）

授權

MIT