If you use Claude Code, Codex, and Gemini CLI side by side, you've probably hit this problem before: every time you switch API providers — official endpoint, a relay, a local model — you have to manually open ~/.claude/settings.json, ~/.codex/config.toml, and ~/.gemini/.env and edit each one separately, while remembering the config field format for every tool. CC Switch exists to solve exactly this pain point — it's a cross-platform desktop app that lets you manage Provider configs, MCP servers, and Skills for every AI CLI tool from a single interface, switching with one click instead of hand-editing config files.

What Is CC Switch?

CC Switch (official site: ccswitch.io, GitHub: farion1231/cc-switch) is an open-source desktop app created by developer Jason Young, built on the Tauri 2 framework, with an install size of about 10 MB. As of June 2026, the project has surpassed 67,000 GitHub stars with 125 contributors — making it the most actively maintained AI CLI management tool in the community.

It supports managing the configuration of the following 7 AI coding tools simultaneously:

  • Claude Code (Anthropic's official CLI)
  • Claude Desktop
  • Codex (OpenAI's official CLI)
  • Gemini CLI (Google's official CLI)
  • OpenCode
  • OpenClaw
  • Hermes Agent

The core value of CC Switch

Every AI CLI has its own config format, Provider syntax, MCP setup, and Skills directory. CC Switch flattens those differences into one visual interface, so you can switch providers without memorizing the configuration details of every individual tool.

Why Do Developers Need CC Switch?

As AI coding tools have proliferated, it's now common for a single developer to run 2–3 CLI tools at once. Before CC Switch existed, switching API providers looked like this:

  • Find ~/.claude/settings.json, manually edit ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
  • Find ~/.codex/config.toml, edit base_url and the API key
  • Find ~/.gemini/.env, update the corresponding variables
  • Restart the terminal, verify it took effect
  • Repeat all of the above the next time you switch

With CC Switch, that whole flow becomes: right-click the system tray icon → pick the target Provider → done. Claude Code and Gemini CLI even support hot-switching, so you don't need to restart the terminal at all.

For developers routing through relays, CC Switch also ships with 50+ built-in presets for relay providers and third-party providers — no need to type in a base_url by hand, just pick the preset and paste your API key. This is a big part of why it gets recommended so often in relay-focused communities.

Installation

macOS

Homebrew is recommended, since it supports auto-updates:

brew tap farion1231/ccswitch
brew install --cask cc-switch

You can also download the .dmg file from the GitHub Releases page, then double-click to install and drag it into your Applications folder. System requirement: macOS 12+ (Monterey or later).

Windows

Download the CC-Switch-vX.X.X-Windows.msi installer from the GitHub Releases page, double-click, and follow the prompts. A portable .zip build is also available — unzip it and run CC-Switch.exe directly, no install needed. System requirement: Windows 10+.

Linux

Pick the format that matches your distro:

  • Ubuntu/Debian: download the .deb package, sudo dpkg -i cc-switch_*.deb
  • Arch Linux: paru -S cc-switch-bin (AUR)
  • Fedora/RHEL: download the .rpm package
  • Generic: download the .AppImage, mark it executable, and run it directly

Note: on Linux, if the system tray icon disappears, install gnome-shell-extension-appindicator and restart your session.

No GUI (server environments)

CC Switch is a desktop app and can't run on a headless command-line-only server. If you need the same functionality in a headless environment, check out the community project SaladDay/cc-switch-cli — it reads the same config format but runs as a pure CLI tool.

Core Features Explained

1. Provider management (the core feature)

On first launch, CC Switch auto-detects any AI CLI tools you already have installed and imports their existing configs. Steps to add a new Provider:

  1. Click the "+" button in the top-right corner
  2. Choose the Provider type: App-specific Provider (applies to only the current CLI) or Universal Provider (shared across Claude Code, Codex, and Gemini CLI)
  3. Pick a target provider from 50+ presets (covering AWS Bedrock, NVIDIA NIM, popular relay services, and more), or manually fill in a custom base_url
  4. Paste your API key — CC Switch auto-fills the endpoint URL and protocol format
  5. Click "Enable" to complete the switch

When the switch actually takes effect varies by tool: Claude Code and Gemini CLI support hot-switching (no terminal restart needed); Codex, OpenCode, OpenClaw, and Hermes Agent require a terminal restart to take effect.

CC Switch writes configuration directly into each tool's native config file, without introducing any extra runtime dependency:

  • Claude Code → ~/.claude/settings.json
  • Codex → ~/.codex/auth.json + ~/.codex/config.toml
  • Gemini CLI → ~/.gemini/.env + ~/.gemini/settings.json
  • OpenCode → ~/.config/opencode/opencode.json

Note for Codex users

Codex 0.137.0+ has dropped support for wire_api = "chat" and now only accepts the Responses API. If your relay doesn't support the OpenAI Responses API, you'll get a 404 error even with CC Switch configured correctly. When picking a Provider, confirm your relay explicitly supports the Responses API, or enable the "Needs Local Routing" option in CC Switch so its local proxy layer can handle protocol conversion for you.

2. Local proxy and hot-switching

CC Switch runs a built-in local proxy layer — it's not just writing config files. It also supports:

  • Hot-switching: no terminal restart required, changes take effect immediately (for supported CLIs)
  • Protocol conversion: converts Codex's Responses API requests into OpenAI Chat Completions format, so relays that don't support the Responses API can still serve Codex
  • Automatic failover: with multiple Providers configured, it automatically switches to a backup if the primary Provider becomes unavailable
  • Health checks: sends test requests to configured Providers to verify the API key and endpoint are valid

3. Unified MCP server management

MCP (Model Context Protocol) is the standard protocol that lets AI CLI tools connect to external tools — databases, filesystems, search engines, and more. CC Switch provides a unified MCP management panel that lets you:

  • View and manage the MCP server list for each CLI (read from each tool's native config location, e.g., Claude Code's ~/.claude.json)
  • Toggle MCP servers on/off per CLI
  • Import MCP configs with one click via Deep Link
  • Sync MCP server configs bidirectionally across multiple CLIs

4. Skills installation and management

Skills are a plugin mechanism that extends AI CLIs with additional instructions and prompt capabilities (similar to Claude Code's /commands and Prompts). CC Switch supports:

  • One-click installation of Skills from a GitHub repo or a ZIP file
  • Bulk-updating installed Skills
  • Choosing an install mode: symlink mode (one file shared across multiple CLIs) or copy mode (for sandboxed CLIs that don't support symlinks)

5. Usage stats and session history

CC Switch has a built-in usage dashboard that tracks token consumption and spend per Provider, along with call history broken down by CLI tool. Its session manager lets you browse and search historical conversations across multiple apps.

6. Cloud sync

CC Switch stores its local data in ~/.cc-switch/ (a SQLite database + JSON config + Skills directory) and supports syncing across devices via Dropbox, OneDrive, iCloud, NAS, or WebDAV. Note: it's not recommended to sync the cc-switch.db SQLite file directly to a plain cloud drive (it lacks file locking) — use WebDAV or a sync solution that supports file locking instead.

Quick Start: 3 Steps to Your First Switch

  1. Install and launch: follow the installation steps for your platform above; on first launch it will auto-detect any installed CLI tools.
  2. Add a Provider: click "+" in the top right, pick a relay preset (or fill in a custom base_url), paste the API key, and save.
  3. Enable and verify: click "Enable" next to the target config in the Provider list, then click "Health check" to verify connectivity, and open a terminal to run claude (or codex/gemini) to confirm it's working.

If you're a Codex user, after switching you need to fully quit the Codex process (not just close the prompt) and restart it for the new config to load — that's Codex's own startup caching behavior, not a CC Switch issue.

Who Is CC Switch Best For?

CC Switch is especially valuable if:

  • You use Claude Code + Codex together, or all three including Gemini CLI
  • You switch frequently between official APIs, relays, and local models
  • Your team shares one set of Provider configs and needs to distribute it across devices via cloud sync
  • You need to manage MCP servers across tools without duplicating config
  • You want to monitor token consumption and spend across multiple AI CLIs

If you only use one AI CLI with a single fixed API provider, CC Switch's convenience is relatively limited — just hardcoding the key into an environment variable would do. But the moment you have a "multiple CLIs, multiple Providers, frequent switching" need, CC Switch is about as mature a solution as exists today.

Tip for pairing with a relay

CC Switch's 50+ built-in presets cover popular relay providers (PoloAPI, SiliconFlow, 302.AI, ofox.ai, and more). If your relay isn't in the preset list, choose "Custom Provider" and manually fill in the base_url (usually in the format https://your-relay.com/v1) and API key. Note that Claude Code uses the Anthropic protocol while Codex uses the OpenAI Responses API protocol — when picking a relay, confirm it supports whichever protocol you need.

Related Resources

For a side-by-side comparison of popular relay providers, see our AI API relay comparison page.

Further Reading