Paths: File paths (shared/, references/) are relative to skills repo root. Locate this SKILL.md directory and go up one level for repo root.

Config Syncer

Type: L3 Worker Category: 0XX Shared

Synchronizes skills (via symlinks) and MCP/hook settings from Claude Code (source of truth) to Gemini CLI and Codex CLI. Converts formats: JSON for Gemini, TOML for Codex.

Input / Output

Config Paths by OS

Workflow

Discover State  -->  Sync Skills  -->  Sync MCP  -->  Sync Hooks  -->  Report

Phase 1: Discover State

1. Read Claude settings (source of truth):
   • ~/.claude.json (primary) + ~/.claude/settings.json (fallback)
   • Merge: primary overrides fallback by server name
2. Read target configs (if exist):
   • Gemini: ~/.gemini/settings.json → extract mcpServers
   • Codex: ~/.codex/config.toml → extract [mcp_servers.*]
3. Check existing symlinks: ~/.gemini/skills, ~/.codex/skills
4. Display current state table

Phase 2: Sync Skills (symlinks/junctions)

For each target where disabled is not true:

Decision logic:

Phase 3: Sync MCP Settings

IF agent disabled: true → SKIP for that target.

3a: Claude to Gemini (JSON to JSON)

Gemini-only fields (preserve during merge, not mapped from Claude): timeout, trust, includeTools, excludeTools

3b: Claude to Codex (JSON to TOML)

Codex-only fields (preserve during merge, not mapped from Claude): bearer_token_env_var, enabled_tools, disabled_tools, startup_timeout_sec, tool_timeout_sec, enabled, required

Merge strategy (both targets): Claude servers override target by key name. Target-only servers preserved. Backup .bak before writing.

Phase 4: Sync Hooks

4a: Claude to Gemini (event name + tool name mapping)

Tool name mapping in hook matchers:

Hook scripts must support both tool name formats (same mapping as matchers above).

4b: Claude to Codex

Codex does NOT support hooks. SKIP hook sync for Codex. Report "hooks not supported by Codex CLI".

Phase 5: Report

Config Sync:
| Action         | Target | Status                         |
|----------------|--------|--------------------------------|
| Skills symlink | Gemini | created -> ~/.claude/plugins   |
| Skills symlink | Codex  | already linked                 |
| MCP sync       | Gemini | 4 servers synced (2 new)       |
| MCP sync       | Codex  | 4 servers synced (1 new)       |
| Hooks sync     | Gemini | 3 events synced                |
| Hooks sync     | Codex  | skipped (not supported)        |

Critical Rules

1. Claude = source of truth. Never write TO Claude settings. Read-only source
2. Non-destructive merge. Target-only servers and settings preserved. Only Claude servers added/updated
3. No data loss. Real directories (not symlinks) at target path → warn and skip, never delete
4. Backup before write. Create .bak copy before modifying any config file
5. Respect disabled flags. Skip all operations for disabled agents
6. Idempotent. Safe to run multiple times. Already-synced state is skipped

Anti-Patterns

Definition of Done

• Claude settings read successfully (both config locations)
• Skills symlinks created/verified for each non-disabled target
• MCP settings synced with correct format conversion (JSON for Gemini, TOML for Codex)
• Hook events and tool names mapped for Gemini
• Codex hooks skipped with report
• Backup files created before any config modification
• Final report table displayed

Version: 1.0.0 Last Updated: 2026-03-20