If you switch between Claude Code, Codex, Cursor, OpenCode, Gemini CLI, and a handful of newer agent CLIs on the same machine, you have probably hit the same quiet tax: every client stores MCP servers, Skills, model providers, and global instructions in a different file path, serialization format, and top-level key.
Symlinking a single config file across hosts seems clever until one CLI rewrites its startup fields and wipes your JSON, or rejects a key because it expects TOML instead of JSON.
This reference maps the verified local disk paths, root keys, formats, and gotchas across 15 AI coding agents, organized around what can actually be shared safely on a Mac.
Why Dotfiles Symlinks Break Across AI Coding Harnesses
Four schema incompatibilities make blind symlinking brittle:
-
Incompatible root keys: Claude Code and Cursor expect
mcpServersin JSON, Codex reads[mcp_servers.*]in TOML, and OpenCode nests entries insidemcp(notmcpServers) insideopencode.json. - Mixed file formats: Current agent CLIs span JSON, TOML, JSON5 (with comments), and YAML.
- Runtime rewrites: Several clients write dynamic auth state or last-used model caches into the same config directory or file at startup.
-
Separate surfaces on the same brand: Cursor IDE vs. Cursor CLI, Codex Desktop vs. Codex CLI, Antigravity Desktop vs.
agyCLI, and Oh My Pi (OMP) vs.Pido not share identical capabilities even when they live on the same laptop.
Group A — 6 Core Coding Agent Hosts (Verified Disk Paths)
These 6 clients are primary multi-agent coding harnesses with full MCP, Skill, hook, and local session directory structures:
| Host (Surface) | MCP Config Path & Format | Model / Provider / Hooks | Skill & Global Instruction Paths | Key Gotchas |
|---|---|---|---|---|
| Claude Code CLI |
~/.claude.json (JSON · key mcpServers) |
~/.claude/settings.json (Hooks & provider env) |
~/.claude/skills/<name>/SKILL.md, ~/.claude/CLAUDE.md
|
Supports user + project CLAUDE.md rules alongside native lifecycle hooks. |
| Codex (Desktop / CLI) |
~/.codex/config.toml (TOML · [mcp_servers.<name>]) |
~/.codex/config.toml, ~/.codex/hooks.json
|
~/.codex/skills/<name>/SKILL.md, ~/.codex/AGENTS.md
|
Repo-level AGENTS.override.md or custom CODEX_HOME supersedes global instructions. |
| Cursor (IDE / CLI) |
~/.cursor/mcp.json (JSON · key mcpServers) |
~/.cursor/hooks.json |
~/.cursor/skills/<name>/SKILL.md |
UI "User Rules" live outside documented filesystem files; .mdc rules require workspace project scope. |
| Antigravity Desktop |
~/.gemini/config/mcp_config.json (JSON · key mcpServers) |
~/.gemini/config/hooks.json |
~/.gemini/config/skills/<name>/SKILL.md, ~/.gemini/config/rules
|
Model selection stays inside Desktop UI; external tools should not rewrite private Desktop auth caches. |
| OMP (Oh My Pi CLI) |
~/.omp/agent/mcp.json (JSON · key mcpServers) |
~/.omp/agent/models.yml, ~/.omp/agent/config.yml, ~/.omp/agent/hooks/pre/
|
~/.omp/agent/commands/*.md, ~/.omp/agent/AGENTS.md
|
Respects .yaml siblings; avoid mixed legacy settings.json/models.json; subagents skip root AGENTS.md. |
| OpenCode CLI |
~/.config/opencode/opencode.json (JSON · key mcp) |
~/.config/opencode/opencode.json, ~/.config/opencode/plugins/
|
~/.config/opencode/skills, ~/.config/opencode/commands/*.md
|
Single JSON houses both providers and mcp (not mcpServers). |
Group B — 9 Extended Coding & Assistant Clients
Beyond those 6 primary harnesses, 9 additional clients use distinct schemas and stricter boundaries:
| Client | MCP Config Path & Format | Provider Config | Skills / Instruction Paths | Explicit Constraints |
|---|---|---|---|---|
| Claude Desktop |
~/Library/Application Support/Claude/claude_desktop_config.json (JSON · mcpServers) |
Managed inside Desktop app (or .mcpb bundles) |
No managed global prompt directory | Local MCP JSON / .mcpb extensions only; no session relay. |
| Gemini CLI |
~/.gemini/settings.json (JSON · mcpServers) |
No external provider rewrite | No managed global Skill folder | Local MCP entries and snapshots only. |
| Grok Build CLI |
~/.grok/config.toml (TOML · mcp_servers) |
Provider blocks read natively |
~/.grok/skills, ~/.grok/AGENTS.md
|
Global default model override is unsupported. |
| Kimi Code CLI |
~/.kimi-code/mcp.json (JSON · mcpServers) |
~/.kimi-code/config.toml (TOML) |
~/.kimi-code/skills, ~/.kimi-code/AGENTS.md
|
Split JSON MCP + TOML provider files. |
| MiniMax Code |
~/.minimax/mcp.json (JSON · mcpServers) |
~/.minimax/config.yaml (YAML) |
~/.minimax/skills, ~/.minimax/AGENTS.md
|
JSON MCP + YAML provider files. |
| Pi CLI |
~/.pi/agent/mcp.json (JSON · mcpServers) |
~/.pi/agent/models.json, ~/.pi/agent/settings.json
|
~/.pi/agent/skills, ~/.pi/agent/AGENTS.md
|
Strictly separate from OMP; avoid rewriting hand-authored JSON5 configs. |
| Hermes Agent |
~/.hermes/config.yaml (YAML · mcp_servers) |
~/.hermes/config.yaml (custom_providers) |
~/.hermes/skills, ~/.hermes/SOUL.md
|
Global instructions target SOUL.md instead of AGENTS.md. |
| OpenClaw | No native MCP sync |
~/.openclaw/openclaw.json (JSON5 preserving comments · models.providers) |
~/.openclaw/skills, ~/.openclaw/AGENTS.md
|
Comments must be preserved in JSON5; native MCP syncing is unsupported. |
| agy (Antigravity CLI) |
~/.gemini/config/mcp_config.json (JSON · mcpServers) |
Process env (GEMINI_API_KEY, GOOGLE_GEMINI_BASE_URL) + ~/.gemini/antigravity-cli/settings.json
|
~/.gemini/config/skills, ~/.gemini/config/AGENTS.md
|
Credentials belong in env/private profile rather than plaintext copies. |
Two Practical Architectures Depending on Your Setup
Before reaching for extra tooling, match the approach to your OS and team constraints:
-
Cross-platform teams (Windows / Linux / Intel Mac): Keep shared conventions in Git-committed
CLAUDE.md+AGENTS.md($0). It works across every OS without running a local background service. -
Single-Mac Apple Silicon (
macOS 14.0+ arm64) developers switching across harnesses locally: If you want format-aware translation with pre-write diff checks, automatic rollback snapshots, macOS Keychain secret isolation, and/contextcorefull-transcript session relay across the 6 core hosts, you can layer on Senrelay (qingsongcui/ContextCore) ($0, MIT License, no account required; does not support Windows, Linux, or Intel Macs, and public Beta builds need a one-timexattr -cr /Applications/Senrelay.appafterbrew install --cask qingsongcui/tap/senrelay).
For the full machine-readable config matrix and safety boundaries, see the canonical reference at senrelay.com/hosts.html.
Top comments (0)