CC Switch
CC Switch
Section titled “CC Switch”Pin checked 2026-09-28: README + changelog head at v3.20.4 (2026-09-22); tenth managed app is MiniMax Code. Ability-boundary section folded in same day from README FAQ + Codex routing guide.
Primary sources: GitHub farion1231/cc-switch · ccswitch.io · User manual · CHANGELOG
What it is (and is not)
Section titled “What it is (and is not)”| Is | Is not |
|---|---|
| Cross-platform desktop app (Windows / macOS / Linux) | An API relay that sells tokens |
Writer of each tool’s own config (settings.json, config.toml, …) | A replacement for Claude Code, Codex, Gemini CLI, Pi, etc. |
Optional local HTTP proxy (127.0.0.1:15721 by default) with failover + format conversion | Cloud-hosted inference |
SQLite-backed store (cc-switch.db) with atomic writes / backups | Headless server product (see community CLI below) |
Official docs and third-party provider guides stress: download only from ccswitch.io or GitHub Releases; any site that asks for payment, top-ups, or login for “CC Switch” itself is not official. You bring your own API keys.
Tech stack (README): Tauri 2 · Rust · React 18 · TypeScript · SQLite.
Managed tools (ten)
Section titled “Managed tools (ten)”Two provider modes:
- Switch — one active provider at a time; Enable flips the tool’s connection fields.
- Coexist — several providers written into the tool’s native config; you pick the model inside the tool.
| Tool | Mode | Local routing | Tray switch | MCP | Skills | Prompt file(s) | Sessions / usage |
|---|---|---|---|---|---|---|---|
| Claude Code | Switch | ✓ | ✓ | ✓ | ✓ | CLAUDE.md | ✓ |
| Claude Desktop | Switch | Model mapping only | – | –* | –* | – | mapping / limited |
| Codex | Switch | ✓ | ✓ | ✓ | ✓ | AGENTS.md | ✓ |
| Gemini CLI | Switch | ✓ | ✓ | ✓ | ✓ | GEMINI.md | ✓ |
| Grok Build | Switch | ✓ | ✓ | ✓ | ✓ | AGENTS.md | ✓ |
| OpenCode | Coexist | – | – | ✓ | ✓ | AGENTS.md | ✓ |
| OpenClaw | Coexist | – | – | – | – | workspace editor | sessions; no usage |
| Hermes | Coexist | – | – | ✓ | ✓ | Memory | sessions; no usage |
| Pi | Coexist | – | – | – | ✓ | AGENTS.md, SYSTEM.md, templates | ✓ |
| MiniMax Code | Coexist | – | – | ✓ | ✓ | AGENTS.md | ✓ |
* MCP / Skills / Prompts / Sessions opened from the Claude Desktop page apply to Claude Code.
v3.20.4 added MiniMax Code as the tenth app (~/.minimax, additive providers under custom_provider).
Ability boundary
Section titled “Ability boundary”What CC Switch owns vs what stays with the managed CLI, the OS, or other systems. Sourced from the README feature matrix + FAQ, settings / directories, and Using Claude in Codex (routing ≥ 3.17.0).
Can do
Section titled “Can do”| Capability | Scope |
|---|---|
| Provider Switch mode | Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build — exactly one active provider; Enable rewrites key connection fields |
| Provider Coexist mode | OpenCode, OpenClaw, Hermes, Pi, MiniMax Code — Add (Enable for Pi) appends providers into the tool’s native config; model pick stays inside the tool |
| Key-fields-only config writes | Endpoint, key, model, protocol (+ Codex reasoning effort, Gemini auth method, a few provider-tied compatibility flags). Plugins, hooks, permissions, user env, comments, formatting untouched |
| Local HTTP routing | Master switch + per-app takeover for Claude Code, Codex, Gemini CLI, Grok Build (default 127.0.0.1:15721). Claude Desktop: model-mapping path only |
| API format conversion | Anthropic Messages ↔ OpenAI Chat Completions ↔ OpenAI Responses ↔ Gemini native (stream + non-stream), while the client keeps talking its native protocol to localhost |
| Failover | Per-app failover queue, circuit breaker, provider health badges; requires routing/takeover |
| MCP / Skills / Prompts sync | Per matrix row above; Deep Link ccswitch://; Skills via symlink (copy fallback); optional ~/.agents/skills store |
| Projects | Snapshot provider + MCP + Skills + prompts for Claude Code / Codex (provider-only for Claude Desktop) |
| Usage / quotas / sessions | Session-log mining without proxy; proxy request logs when routed; browse/resume sessions where the matrix says ✓ |
| Secrets handling (local) | Real keys live in CC Switch’s SQLite / provider cards; under routing, live tool configs get localhost + placeholder PROXY_MANAGED; OAuth files under ~/.cc-switch/ (codex_oauth_auth.json, etc.) |
| Official ↔ third-party | Built-in Official cards; Codex ChatGPT multi-account via Auth Center; codex-login-stash.json when parking official login for a third-party direct switch |
| WSL path override (Windows) | Point a tool’s config dir into WSL; About can upgrade that WSL install. Routing still binds 127.0.0.1 — needs WSL mirrored networking to reach the Windows proxy |
| Cloud sync of its own DB | WebDAV / S3-compatible for the CC Switch data dir (device-local settings.json / live-state / first-write backups stay on-box) |
Cannot / will not (out of scope)
Section titled “Cannot / will not (out of scope)”| Outside | Why |
|---|---|
| Replace the CLI | Never ships Claude Code, Codex, Gemini, Pi, etc.; About can install/upgrade them, but they remain separate products |
| Be the research channel | Config manager only — does not fetch web, run agents, or substitute for Researchy / browser / X connectors |
| Nix / declarative provisioning | No flake modules, no system-wide env locking; operator-laptop GUI writes user-home configs. Flake PATH / spawnHook stay Flaky / orchestrator concerns |
| Headless / server first-party | Official product is GUI-only. Servers/SSH → community CC Switch CLI (separate release; DB schema can lag desktop) |
| Sell tokens / host inference | BYOK only; not an API relay business |
| Local routing for coexist apps | OpenCode / OpenClaw / Hermes / Pi / MiniMax Code: no local routing or tray switching in the matrix |
| Pi MCP panel | Pi: Skills + prompts + sessions/usage — no MCP column |
| Route most “Official” cards | Official Anthropic / Google / Grok cards blocked from local routing; Codex OpenAI Official is the documented exception |
| Guarantee hot-reload everywhere | Claude Code hot-switches providers; Codex / Gemini / Grok usually need restart (with routing on, next requests follow the new provider, but model catalog / model field changes still often need a Codex restart) |
| Verify keys via Connectivity check | Reachability only — not a live model round-trip |
Preserve in-tool /model across switches | Model is a key field of the provider card; in-tool picks do not write back to the previous provider |
| Delete the last Switch-mode provider | Minimal-intrusion: always keep one live config so uninstalling CC Switch does not brick the CLI |
| Auto-detect WSL | Manual directory override only |
| Move files when changing CC Switch data dir | You copy; it does not migrate |
| Compliance / ToS clearance for OAuth reverse proxies | Auth Center Copilot / ChatGPT / xAI paths are beta and explicitly ToS-risk; user assesses |
Codex deep dive (Switch + routing)
Section titled “Codex deep dive (Switch + routing)”Codex is a first-class Switch-mode app with full local routing, tray switching, MCP, Skills, AGENTS.md prompts, projects, sessions, and usage.
| Layer | Behavior |
|---|---|
| Default dirs | Tool: ~/.codex/ (config.toml, auth.json). CC Switch store: ~/.cc-switch/ |
| Direct switch writes | Key fields into config.toml; third-party API key goes to config.toml not auth.json. Optional setting: keep vs delete auth.json on third-party direct switch (stash/restore via codex-login-stash.json) |
| Routing takeover | Live base_url = "http://127.0.0.1:15721/v1"; auth placeholder; real key stays in CC Switch and is injected on forward. For Anthropic-upstream providers, wire_api = "responses" is forced — Codex keeps speaking Responses; the proxy converts to /v1/messages and back (guide) |
| Needs routing | Upstream format Anthropic Messages (or other non-native) → card marked Needs Routing; Enable without routing fails closed with an explicit error |
| Failover / rectifier | Same proxy machinery as Claude/Gemini/Grok once Codex takeover is on |
| What Codex still owns | Interactive TUI, /model UI, plugins that need official auth (when you preserve auth.json), session decryption quirks when resuming across providers, install location unless About/WSL override manages it |
| Restart | After Enable / catalog changes, restart the Codex process; routing makes provider flips take effect on the next request without rewriting a new upstream URL into the live file |
Inverse path (GPT-shaped upstream inside Claude Code) is the sibling guide Using GPT in Claude Code.
Config & secret write map (defaults)
Section titled “Config & secret write map (defaults)”| Location | Contents |
|---|---|
~/.cc-switch/cc-switch.db | Providers, MCP, prompts, Skills, projects, usage |
~/.cc-switch/settings.json | Device settings, per-tool directory overrides, sync connection (stays local; not cloud-synced) |
~/.cc-switch/backups/, live-first-write/ | Rolling backups; pre-first-rewrite snapshots of each tool config |
~/.cc-switch/*_oauth_auth.json, codex-login-stash.json, live-state.json | OAuth / login stash / direct-vs-routed state |
~/.claude/settings.json (+ optional ~/.claude/config.json for VS Code extension sync) | Claude Code live env / keys (or localhost + PROXY_MANAGED under routing) |
~/.codex/config.toml, ~/.codex/auth.json | Codex live config / official auth |
~/.gemini/, ~/.grok/, ~/.config/opencode/, ~/.openclaw/, ~/.hermes/, ~/.pi/agent/, ~/.minimax/ | Other managed tools (MiniMax / Hermes / Pi also honor their own env dir overrides) |
Decision cheat-sheet
Section titled “Decision cheat-sheet”- Need one active Codex/Claude/Gemini/Grok upstream and maybe failover → CC Switch Switch mode ± local routing.
- Need several providers listed inside OpenCode/Pi/… → Coexist mode; pick model in-tool; no CC Switch proxy for those apps.
- Need Claude protocol behind Codex’s Responses client (or OpenAI/Gemini behind Claude Code) → local routing + correct Upstream Format; not a direct URL paste.
- Need declarative / CI / Nix / headless fleet → not this product; use flake/modules or community CLI, knowing schema lag.
- Need research / agent execution → outside CC Switch entirely.
Core workflows
Section titled “Core workflows”Provider switch (direct mode)
Section titled “Provider switch (direct mode)”- Select the app in the top switcher.
- Add a preset (90+ listed in README) or custom endpoint + key + model.
- Enable (or Add for coexist tools).
- Effect: Claude Code hot-reloads; Codex / Gemini / Grok Build usually need a terminal/CLI restart; Claude Desktop needs an app restart.
Key-fields-only writes: switching replaces endpoint, key, model, protocol (and a few provider-tied options). Plugins, hooks, permissions, MCP, user env vars, comments, and formatting stay put.
Typical Claude Code write target: ~/.claude/settings.json (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, model env keys). Codex: ~/.codex/config.toml + auth.json.
Local routing (proxy)
Section titled “Local routing (proxy)”Turn on the top-bar Proxy toggle (or Settings → Proxy). Default listen: http://127.0.0.1:15721.
With takeover enabled, tools point at the local proxy instead of the upstream:
| Tool | Takeover shape |
|---|---|
| Claude Code | ANTHROPIC_BASE_URL=http://127.0.0.1:15721 |
| Codex | base_url = "http://127.0.0.1:15721/v1" |
| Gemini | GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721 |
Proxy roles:
- Request logs + usage / cost estimation
- Failover queue per app + circuit breaker / health badges
- API format conversion (streaming and non-streaming): Anthropic Messages ↔ OpenAI Chat Completions ↔ OpenAI Responses ↔ Gemini native — so Claude Code can talk to OpenAI-shaped backends, Codex can talk to Anthropic-shaped ones, etc.
- “Rectifier” fixes for awkward upstream quirks (e.g. thinking signatures, image fallback)
Official Anthropic / some official endpoints generally cannot go through local routing (Codex OpenAI Official is a documented exception path). Wrong upstream format without routing → typical 404/405.
MCP, Skills, Prompts, Projects
Section titled “MCP, Skills, Prompts, Projects”- MCP: one panel; sync per tool; import existing; Deep Link import.
- Skills: discover via skills.sh / GitHub / ZIP; sync by symlink (copy fallback); optional store under
~/.agents/skills. - Prompts: per-tool Markdown library; enabling writes
CLAUDE.md/AGENTS.md/GEMINI.mdafter saving prior file content back into the library. Pi also coversSYSTEM.md/APPEND_SYSTEM.md/ templates. - Projects: snapshot provider + MCP + Skills + prompts for Claude Code / Codex (provider-only for Claude Desktop); tray / top switcher restores the bundle.
Usage, auth, sync
Section titled “Usage, auth, sync”- Usage dashboard from local session logs even without proxy; proxy traffic counted too.
- Quota / balance badges for many official and Coding Plan providers; custom pricing or import from models.dev.
- OAuth Auth Center (beta): GitHub Copilot, ChatGPT, xAI accounts via device code — README warns subscription use outside official clients may violate ToS.
- Cloud sync: WebDAV or S3-compatible; or point the config directory at Dropbox / OneDrive / iCloud.
- Deep Link scheme:
ccswitch://for providers, MCP, prompts, skill repos.
Install snapshot
Section titled “Install snapshot”| Platform | Path |
|---|---|
| macOS | brew install --cask cc-switch (or signed/notarized .dmg from Releases) |
| Windows | .msi or portable .zip (x64 / arm64) |
| Linux | .deb / .rpm / AppImage (x86_64 / arm64); needs glibc 2.35+ and WebKitGTK 4.1; Arch: paru -S cc-switch-bin |
| Headless / SSH | Not the desktop app — community CC Switch CLI (TUI + CLI; brew install cc-switch-cli) |
Managed CLIs themselves still need Node (or their own installers). CC Switch’s About page can install/upgrade Claude Code, Codex, etc., and diagnose duplicates (WSL-aware on Windows).
Relevance for Noa’s stack
Section titled “Relevance for Noa’s stack”| Concern | CC Switch angle |
|---|---|
| Pi in Cloud agent orchestrator | First-class coexist app: Skills + AGENTS.md / SYSTEM.md / templates, sessions + usage; no local routing / tray / MCP in the feature matrix |
| Multi-CLI life (Claude Code, Codex, Gemini, OpenCode) | One panel instead of hand-editing fragmented JSON/TOML/YAML |
| Cheap / domestic / OpenAI-shaped backends into Claude Code | Proxy + upstream format = the supported path |
| Researchy “no Codex for research” | Orthogonal — CC Switch is a local config manager, not a research channel; still useful if Codex stays on the machine for coding |
Not a substitute for Nix flake PATH locking or Bend policy in the orchestrator; it sits at the operator laptop layer.
Caveats worth keeping
Section titled “Caveats worth keeping”See Ability boundary above for the full can/cannot map. Short reminders:
- Official site only — phishing / fake “CC Switch” paid mirrors are explicitly called out by the project and by provider docs (e.g. LongCat).
- Proxy off by default — “Proxy inactive” after first launch is expected until the top-bar toggle is green.
- Restart semantics differ by tool — Claude Code hot-switches; many others do not (unless local routing takeover is on for subsequent requests).
- Star counts are noisy — GitHub popularity is high; treat as community signal, not quality proof.
- WSL / flatpak / Linux Claude Desktop 3P — recently hard-won edges; read release notes before assuming parity.
- Desktop-only product surface; servers need the community CLI fork.
Sources
Section titled “Sources”- farion1231/cc-switch README (features matrix, FAQ, install, MIT)
- CHANGELOG v3.20.4 (MiniMax Code; proxy/Codex fixes)
- ccswitch.io docs / Getting started (cc-switch.cc mirror tutorial)
- Proxy service docs (port
15721, takeover, format conversion, failover) - LongCat × CC Switch integration (worked example writing
~/.claude/settings.json/ Codex toml) - Community CLI: SaladDay/cc-switch-cli
- Using Claude in Codex (routing guide)
- Using GPT in Claude Code
- Settings / directories