Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

Agent Sync (Standalone Utility)

Type: Standalone Utility Category: 0XX Shared

Synchronizes skills and MCP server configurations from Claude Code (source of truth) to Gemini CLI and Codex CLI. Creates symlinks for skills, copies/converts MCP settings.

When to Use This Skill

After adding/removing MCP servers in Claude Code settings
After installing new plugins in Claude Code
First-time setup of Gemini CLI or Codex CLI alongside Claude Code
Periodic sync to keep all agents aligned

Input Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | targets | No | both | gemini, codex, or both | | mode | No | full | skills (symlinks only), mcp (MCP only), or full (both) | | dry_run | No | false | Show planned actions without executing |

Workflow

Detect OS → Discover Configs → Sync Skills → Sync MCP → Report

Phase 0: OS Detection

| Check | Result | Impact | |-------|--------|--------| | uname or platform | win32 / darwin / linux | Junction vs symlink | | Home directory | $HOME or $USERPROFILE | Config paths |

Paths by OS:

| Agent | Windows | macOS / Linux | |-------|---------|---------------| | Claude | %USERPROFILE%\.claude.json (primary) | ~/.claude.json (primary) | | Claude | %USERPROFILE%\.claude\settings.json (fallback) | ~/.claude/settings.json (fallback) | | Gemini | %USERPROFILE%\.gemini\settings.json | ~/.gemini/settings.json | | Codex | %USERPROFILE%\.codex\config.toml | ~/.codex/config.toml |

Phase 1: Discover Current State

Read Claude settings (check both sources, merge):
- Parse ~/.claude.json → extract mcpServers block (primary source, app state file)
- Parse ~/.claude/settings.json → extract mcpServers block (fallback, user settings file)
- Merge: primary overrides fallback by server name
- If no mcpServers in either → WARN "No MCP servers configured in Claude", skip MCP sync
Read target configs (if exist):
- Gemini: Parse ~/.gemini/settings.json → extract existing mcpServers
- Codex: Parse ~/.codex/config.toml → extract existing [mcp_servers.*]
Detect installed plugins:
- Glob ~/.claude/plugins/*/plugin.json → list plugin directories
- Also check if skills repo itself is a plugin source
Check existing symlinks:
- ~/.gemini/skills → exists? points where?
- ~/.codex/skills → exists? points where?

Show current state:

Current State:
| Agent | Skills | MCP Servers | Config Exists |
|-------|--------|-------------|---------------|
| Claude (source) | 5 plugins | 4 servers | yes |
| Gemini | no link | 2 servers | yes |
| Codex | → ~/.claude/plugins | 4 servers | yes |

Phase 2: Sync Skills (symlinks/junctions)

FOR EACH target IN (gemini, codex) WHERE target in targets:

Determine link path:
- Gemini: ~/.gemini/skills
- Codex: ~/.codex/skills
Check if already linked correctly:
- IF link exists AND points to correct source → SKIP (already synced)
- IF link exists AND points to wrong source → WARN, ask user before replacing
- IF regular directory (not link) exists → WARN "Target is a real directory, not a link. Skip to avoid data loss."
Determine source:
- IF single plugin: link directly to plugin dir
- IF multiple plugins: ask user which plugin to share
Create link:

| OS | Command | |----|---------| | Windows | cmd /c mklink /J "{target_path}" "{source_path}" | | macOS / Linux | ln -s "{source_path}" "{target_path}" |
Verify: Check link exists and resolves correctly

Phase 3: Sync MCP Settings

Source: ~/.claude.json (primary) + ~/.claude/settings.json (fallback) → merged mcpServers

3a: Claude → Gemini (JSON → JSON)

Read Claude mcpServers as JSON object
Read Gemini settings.json (or create {} if missing)
Merge strategy: Claude servers override Gemini servers by key name. Gemini-only servers preserved.
Write updated settings.json

Conversion: Transport type mapping required:

| Claude field | Gemini field | Notes | |---|---|---| | type: "http" + url | httpUrl | Streamable HTTP | | type: "sse" + url | url | SSE transport | | command + args | command + args + cwd | stdio (same format) | | env | env | Same format ($VAR_NAME syntax in Gemini) | | headers | headers | Same format (JSON object, for url/httpUrl) |

Gemini-only fields (not mapped from Claude):

timeout — request timeout in ms (default: 10min)
trust — bypass tool confirmations
includeTools / excludeTools — tool whitelist/blacklist

3b: Claude → Codex (JSON → TOML)

Read Claude mcpServers as JSON object
Read Codex config.toml (or create empty if missing)
Convert each server:

| Claude JSON field | Codex TOML field | Notes | |-------------------|------------------|-------| | command | command | Same | | args | args | JSON array → TOML array | | env | [mcp_servers.{name}.env] | Nested table | | type: "http" + url | url | Streamable HTTP (Codex auto-detects by url presence) | | type: "sse" + url | url | SSE → Streamable HTTP (same url field) | | headers | http_headers | Different key name! Static header values |

Example conversion:
```
"context7": {
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"]
}
```
```
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
```
Merge strategy: Claude servers override. Codex-only servers preserved.
Write updated config.toml

Codex-only fields (preserve as-is, no Claude equivalent):

bearer_token_env_var — Codex bearer token auth
enabled_tools / disabled_tools — Codex tool filtering
startup_timeout_sec / tool_timeout_sec — Codex timeouts
enabled / required — Codex server lifecycle
env_vars / env_http_headers — Codex env-based headers

Phase 4: Report

Sync Complete:
| Action | Target | Status |
|--------|--------|--------|
| Skills symlink | Gemini | Created → ~/.claude/plugins/... |
| Skills symlink | Codex | Already linked |
| MCP sync | Gemini | 4 servers synced (2 new, 2 updated) |
| MCP sync | Codex | 4 servers synced (1 new, 3 updated) |

Critical Rules

Claude = source of truth. Never write TO Claude settings. Read-only source.
Non-destructive merge. Target-only servers/settings preserved. Only Claude servers added/updated.
No data loss. If target is a real directory (not symlink) — warn and skip, never delete.
Backup before write. Before modifying any config file, create .bak copy.
Dry run first. If dry_run=true, show all planned actions without executing.
Ask on conflict. If symlink points to different source — ask user, don't auto-replace.

Anti-Patterns

Writing TO Claude settings from Gemini/Codex (reverse sync)
Deleting target-only MCP servers during sync
Creating symlinks inside symlinks (circular)
Modifying config files without backup

Definition of Done

| # | Criterion | |---|-----------| | 1 | Claude settings read successfully | | 2 | Skills symlinks created/verified for each target | | 3 | MCP settings synced with format conversion (JSON→TOML for Codex) | | 4 | Backup files created before any config modification | | 5 | Report shown with all actions and warnings |

Version: 1.1.0 Last Updated: 2026-03-09