sync-agents-settings

Sync MCP server configurations and instruction files (CLAUDE.md) from Claude Code to Gemini CLI, Codex CLI, OpenCode, Kiro CLI, and Cursor.

README translations: 🇹🇼 繁體中文 | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어

Why

If you use Claude Code as your primary AI coding agent but also switch between other agents (Gemini CLI, Codex CLI, OpenCode, Kiro, Cursor) to take advantage of their free tiers or different models, you know the pain — every tool has its own MCP config format, and setting them up one by one is tedious. Same goes for instruction files — CLAUDE.md, GEMINI.md, AGENTS.md all need the same content but in different formats.

This tool lets you configure MCP servers and write instructions once in Claude Code, then sync everywhere with a single command.

Quick Start

Option A: Claude Code Plugin (recommended)

Use directly inside Claude Code with slash commands:

# Load the plugin for this session
claude --plugin-dir /path/to/sync-agents-settings

# Then use slash commands in the conversation:
#   /sync-list          — list all MCP servers
#   /sync               — sync MCP configs (with dry-run preview)
#   /sync-diff           — compare configs between agents
#   /sync-instructions   — sync CLAUDE.md to other agents

The plugin also includes a sync-awareness skill that automatically suggests syncing when you edit MCP settings or CLAUDE.md files.

Option B: CLI via npx

No installation needed — just run with npx:

# List all MCP servers detected from Claude Code
npx sync-agents-settings list

# Preview sync (no files modified)
npx sync-agents-settings sync --dry-run

# Sync to all targets (with automatic backup)
npx sync-agents-settings sync

# Sync CLAUDE.md instructions to all targets
npx sync-agents-settings sync-instructions

Option C: Global Install

# Global install for the `sync-agents` command
npm install -g sync-agents-settings

# Then use directly
sync-agents list
sync-agents sync

Usage

# Sync to a specific target
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 to Codex project-level config
sync-agents sync --target codex --codex-home ./my-project/.codex

# Compare differences
sync-agents diff

# Skip OAuth-only servers (e.g. Slack)
sync-agents sync --skip-oauth

# Skip backup
sync-agents sync --no-backup

# Verbose output
sync-agents sync -v

# Sync instruction files (CLAUDE.md → GEMINI.md / AGENTS.md / Kiro steering / Cursor rules)
sync-agents sync-instructions

# Sync only global instructions
sync-agents sync-instructions --global

# Sync only project-level instructions
sync-agents sync-instructions --local

# Sync to specific targets
sync-agents sync-instructions --target gemini codex

# Auto-overwrite without prompts (for CI)
sync-agents sync-instructions --on-conflict overwrite

# Preview instruction sync
sync-agents sync-instructions --dry-run

Development

git clone https://github.com/Leoyang183/sync-agents-settings.git
cd sync-agents-settings
pnpm install
pnpm dev list        # Run from source
pnpm test            # Run tests

How It Works

Claude Code is the single source of truth for MCP settings, synced to all supported targets.

                                                 ┌─→ 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

Stage	Description
Reader	Reads from `~/.claude.json` and enabled plugin `.mcp.json` files, merges into a unified format
Gemini Writer	JSON → JSON, `type: "http"` → `httpUrl`, `${VAR}` → `$VAR`
Codex Writer	JSON → TOML, `${VAR:-default}` → expanded to actual value (env value or fallback)
OpenCode Writer	JSON → JSON, `command`+`args` → merged `command` array, `env` → `environment`, `type: "local"`/`"remote"`
Kiro Writer	Same format as Claude, `${VAR:-default}` → expanded
Cursor Writer	Same format as Claude, `${VAR:-default}` → expanded

Instruction Sync (`sync-instructions`)

Syncs CLAUDE.md instruction files to each target's native format:

                                          ┌─→ ~/.gemini/GEMINI.md             (plain copy)
                                          ├─→ ~/.codex/AGENTS.md              (plain copy)
~/.claude/CLAUDE.md ─→ filter @imports ──┼─→ ~/.config/opencode/AGENTS.md    (plain copy)
                                          ├─→ ~/.kiro/steering/claude-instructions.md  (+ inclusion: always)
                                          └─→ ⚠ Cursor global not supported  (SQLite)

                                          ┌─→ ./GEMINI.md                     (plain copy)
                                          ├─→ ./AGENTS.md                     (Codex + OpenCode share)
./CLAUDE.md ──────────→ filter @imports ──┼─→ .kiro/steering/claude-instructions.md    (+ inclusion: always)
                                          └─→ .cursor/rules/claude-instructions.mdc   (+ alwaysApply: true)

Target	Global	Local	Format Transform
Gemini	`~/.gemini/GEMINI.md`	`./GEMINI.md`	Plain copy (filter `@import` lines)
Codex	`~/.codex/AGENTS.md`	`./AGENTS.md`	Plain copy (filter `@import` lines)
OpenCode	`~/.config/opencode/AGENTS.md`	`./AGENTS.md` (shared with Codex)	Plain copy (filter `@import` lines)
Kiro	`~/.kiro/steering/claude-instructions.md`	`.kiro/steering/claude-instructions.md`	Add `inclusion: always` frontmatter
Cursor	Not supported (SQLite)	`.cursor/rules/claude-instructions.mdc`	Add `alwaysApply: true` frontmatter

When a target file already exists, you'll be prompted to choose: overwrite, append (keep existing + add CLAUDE.md below), or skip. Use --on-conflict overwrite|append|skip for non-interactive mode.

Safety mechanisms:

Existing servers are never overwritten (idempotent, safe to re-run)
Automatic backup to ~/.sync-agents-backup/ by default (--no-backup to skip)
--dry-run previews changes without writing any files

Source: Claude Code

Reads MCP servers from two sources:

~/.claude.json → mcpServers object (user-configured servers)
~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/.mcp.json → enabled plugin MCP servers (matched against ~/.claude/settings.json enabledPlugins)

Claude Code has two .mcp.json formats:

// Format 1: Flat (e.g. context7, firebase)
{ "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } }

// Format 2: Nested under mcpServers (e.g. sentry, stripe)
{ "mcpServers": { "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" } } }

Target: Gemini CLI

Writes to ~/.gemini/settings.json → mcpServers object.

Key format differences from Claude:

Claude type: "http" → Gemini httpUrl
Claude type: "sse" → Gemini url
Claude command (stdio) → Gemini command (same)
Env var syntax: Claude ${VAR} → Gemini $VAR (auto-converted)

// Gemini settings.json
{
  "theme": "Dracula",          // existing settings preserved
  "mcpServers": {
    "context7": {              // stdio server
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sentry": {                // http server
      "httpUrl": "https://mcp.sentry.dev/mcp"
    }
  }
}

Target: Codex CLI

Writes to ~/.codex/config.toml (global) by default. Use --codex-home <path> to write to a project-level .codex/config.toml instead.

Note: Codex CLI does NOT merge global and project configs. When a project has .codex/, Codex only reads that directory. Global ~/.codex/ is ignored entirely.

Key format differences:

Uses TOML instead of JSON
command/args for stdio (same concept)
url for HTTP servers (no type field needed)
env is a TOML sub-table [mcp_servers.<name>.env]

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.sentry]
url = "https://mcp.sentry.dev/mcp"

[mcp_servers.n8n-mcp]
command = "npx"
args = ["n8n-mcp"]

  [mcp_servers.n8n-mcp.env]
  N8N_API_KEY = "your-key"
  N8N_API_URL = "https://your-n8n.example.com"

Target: OpenCode

Writes to ~/.config/opencode/opencode.json → mcp object.

Key format differences:

Root key is mcp (not mcpServers)
stdio servers use type: "local" with a merged command array (command + args combined)
HTTP/SSE servers use type: "remote"
Environment variables use environment field (not env)

// opencode.json
{
  "model": "anthropic/claude-sonnet-4-5",  // existing settings preserved
  "mcp": {
    "context7": {                          // stdio → local
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"]
    },
    "sentry": {                            // http → remote
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "n8n-mcp": {                           // env → environment
      "type": "local",
      "command": ["npx", "n8n-mcp"],
      "environment": {
        "N8N_API_KEY": "your-key"
      }
    }
  }
}

Target: Kiro CLI

Writes to ~/.kiro/settings/mcp.json → mcpServers object.

Same format as Claude Code. ${VAR:-default} syntax in URLs is auto-expanded during sync.

Target: Cursor

Writes to ~/.cursor/mcp.json → mcpServers object.

Same format as Claude Code. ${VAR:-default} syntax in URLs is auto-expanded during sync.

Transport Type Mapping

Claude Code	Gemini CLI	Codex CLI	OpenCode	Kiro CLI	Cursor
`command` + `args` (stdio)	`command` + `args`	`command` + `args`	`type: "local"`, `command: [cmd, ...args]`	same as Claude	same as Claude
`type: "http"` + `url`	`httpUrl`	`url`	`type: "remote"`, `url`	same as Claude	same as Claude
`type: "sse"` + `url`	`url`	`url`	`type: "remote"`, `url`	same as Claude	same as Claude
`env`	`env`	`env`	`environment`	`env`	`env`
`oauth`	skipped	skipped	skipped	skipped	skipped

Backup

Every sync automatically backs up all affected config files to ~/.sync-agents-backup/<timestamp>/ before writing, preserving the original directory structure relative to ~:

~/.sync-agents-backup/2026-03-20T00-06-08-042Z/
├── .claude.json                  # ← ~/.claude.json
├── .claude/
│   └── settings.json             # ← ~/.claude/settings.json
├── .gemini/
│   └── settings.json             # ← ~/.gemini/settings.json
├── .codex/
│   └── config.toml               # ← ~/.codex/config.toml
├── .config/
│   └── opencode/
│       └── opencode.json         # ← ~/.config/opencode/opencode.json
├── .kiro/
│   └── settings/
│       └── mcp.json              # ← ~/.kiro/settings/mcp.json
└── .cursor/
    └── mcp.json                  # ← ~/.cursor/mcp.json

Use --no-backup to skip. Target directories that don't exist (CLI not installed) will be skipped with a warning, not created.

Config File Locations

MCP Settings

Tool	Config Path	Format
Claude Code (user MCP)	`~/.claude.json`	JSON
Claude Code (settings)	`~/.claude/settings.json`	JSON
Claude Code (plugin MCP)	`~/.claude/plugins/cache/.../.mcp.json`	JSON
Gemini CLI	`~/.gemini/settings.json`	JSON
Codex CLI (global)	`~/.codex/config.toml`	TOML
Codex CLI (project)	`.codex/config.toml` (use `--codex-home`)	TOML
OpenCode (global)	`~/.config/opencode/opencode.json`	JSON
OpenCode (project)	`opencode.json` in project root	JSON
Kiro CLI (global)	`~/.kiro/settings/mcp.json`	JSON
Kiro CLI (project)	`.kiro/settings/mcp.json` in project root	JSON
Cursor (global)	`~/.cursor/mcp.json`	JSON
Cursor (project)	`.cursor/mcp.json` in project root	JSON

Instruction Files

Tool	Global Path	Project Path	Format
Claude Code	`~/.claude/CLAUDE.md`	`./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
Kiro CLI	`~/.kiro/steering/claude-instructions.md`	`.kiro/steering/claude-instructions.md`	Markdown + frontmatter
Cursor	Not supported (SQLite)	`.cursor/rules/claude-instructions.mdc`	MDC (Markdown + frontmatter)

Claude Code Plugin

This project can be used as a Claude Code plugin, providing slash commands and a contextual skill directly inside Claude Code conversations.

Slash Commands

Command	Description
`/sync`	Sync MCP server configs to other agents (with dry-run preview and confirmation)
`/sync-list`	List all MCP servers configured in Claude Code
`/sync-diff`	Compare MCP configs between Claude and other agents
`/sync-instructions`	Sync CLAUDE.md instruction files to other agent formats

Sync-Awareness Skill

The plugin includes a skill that automatically detects when you're editing MCP settings (.claude.json, .mcp.json) or CLAUDE.md files, and suggests syncing to other agents.

Plugin Development

# Validate plugin structure
claude plugins validate /path/to/sync-agents-settings

# Test locally (loads plugin for this session only)
claude --plugin-dir /path/to/sync-agents-settings

Limitations

OAuth servers (e.g. Slack with oauth.clientId) are synced as URL-only — you'll need to authenticate manually in each CLI
${CLAUDE_PLUGIN_ROOT} env vars won't resolve in other CLIs
Codex CLI doesn't support ${VAR:-default} syntax in URLs — these are auto-expanded during sync (env value if set, otherwise the default)
Re-running sync will not overwrite existing entries (safe to run multiple times)
Codex CLI does NOT merge global and project configs — when .codex/ exists in a project, global ~/.codex/ is ignored
If target config directories don't exist, sync will skip that target (won't create directories)

Star History

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.claude-plugin		.claude-plugin
.github		.github
bin		bin
commands		commands
docs/i18n		docs/i18n
skills/sync-awareness		skills/sync-awareness
src		src
.gitignore		.gitignore
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ci-local.sh		ci-local.sh
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

sync-agents-settings

Why

Quick Start

Option A: Claude Code Plugin (recommended)

Option B: CLI via npx

Option C: Global Install

Usage

Development

How It Works

Instruction Sync (`sync-instructions`)

Source: Claude Code

Target: Gemini CLI

Target: Codex CLI

Target: OpenCode

Target: Kiro CLI

Target: Cursor

Transport Type Mapping

Backup

Config File Locations

MCP Settings

Instruction Files

Claude Code Plugin

Slash Commands

Sync-Awareness Skill

Plugin Development

Limitations

Star History

License

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

sync-agents-settings

Why

Quick Start

Option A: Claude Code Plugin (recommended)

Option B: CLI via npx

Option C: Global Install

Usage

Development

How It Works

Instruction Sync (sync-instructions)

Source: Claude Code

Target: Gemini CLI

Target: Codex CLI

Target: OpenCode

Target: Kiro CLI

Target: Cursor

Transport Type Mapping

Backup

Config File Locations

MCP Settings

Instruction Files

Claude Code Plugin

Slash Commands

Sync-Awareness Skill

Plugin Development

Limitations

Star History

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Instruction Sync (`sync-instructions`)

Packages