farion1231/cc-switch

CC Switch is a cross-platform desktop manager for AI coding tools: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, MiniMax Code, Kimi Code and Oh My Pi. It replaces hand-editing each tool's JSON/TOML/YAML config when you change API provider, and puts MCP servers, skills and prompts in one place CC Switch README.

What changes in a workflow

Instead of editing config files per tool, you add a provider once (from 90+ presets or a custom entry), then click to enable it. Switching rewrites only the connection fields — endpoint, key, model, API protocol, plus provider-specific options such as Codex reasoning effort and Gemini auth method. Plugins, hooks, permissions, MCP entries, user environment variables and comments are preserved, and the first rewrite of each config file is backed up to ~/.cc-switch/backups/live-first-write/ README FAQ. The app also has an Apps page to install, upgrade and diagnose CLI tools, a session reading view that summarizes each turn and marks failed steps, and usage/quotas collected from local session logs even without routing.

Three connection modes

Direct writes the provider's real address into the tool's config. Routing points the tool at a local service that translates between Anthropic Messages, OpenAI Chat Completions, OpenAI Responses and Gemini Native, with optional auto-failover across a provider queue. That is how OpenAI- or Gemini-format providers can be used in Claude Code, or Claude-format providers in Codex; official providers (except Codex's OpenAI Official) cannot be routed README. Aggregation for Claude Code and Codex lists models from several providers in the client's model picker; each request goes to the chosen model's provider, but there is no failover aggregation manual.

Requirements and caveats

CC Switch ships only as a GUI desktop app. Windows 10+, macOS 12+, or Linux with glibc 2.35+ and WebKitGTK 4.1; RHEL/Rocky/Alma 8–9 are not yet supported installation. A community CLI (CC Switch CLI) exists for servers and SSH, but its supported database version can lag behind the desktop app README FAQ.

Take-effect timing differs: Claude Code switches without restart; Codex, Gemini CLI and Grok Build need a terminal or tool restart; Claude Desktop must be fully quit and reopened, and Model Mapping requires CC Switch to keep running. Codex in Aggregation mode needs its shared daemon restarted, which interrupts running tasks. Routing addresses 127.0.0.1, so WSL2 NAT networking cannot reach it — mirrored networking is required. In Routing/Aggregation mode the config files contain the local address and a PROXY_MANAGED placeholder key; quitting CC Switch writes the direct config back first.

The built-in auth feature signs in to GitHub Copilot, ChatGPT and xAI accounts to use subscriptions as providers; the README warns that using a subscription outside its official client may violate the vendor's terms of service. Data lives in ~/.cc-switch (SQLite database, backups, OAuth credential files), with optional WebDAV/S3 sync that excludes device-level files. The project is MIT licensed repository.