CC Switch: A Visual Provider Manager for Claude Code, Codex, and Gemini CLI

If you use more than one AI coding CLI, or more than one model provider behind a single CLI, you have probably felt the friction: every tool keeps its configuration in a different place and a different format. Claude Code reads a settings file, Codex uses its own config, and provider routing usually means editing environment variables or JSON by hand. Switching from one backend to another is a small, repetitive, error-prone chore, and a misplaced comma can break the whole setup.

CC Switch is an open-source desktop app that turns that chore into a single click. This guide explains what it does, how it works internally, when it helps, and what to watch for before you trust it with your API keys.

1. What CC Switch Is

CC Switch is a cross-platform desktop application that manages provider configurations for several AI coding CLIs from one visual interface. According to its GitHub repository and official site, it supports five command-line tools: Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw.

The project is released under the MIT license and is built with Tauri 2, using a Rust backend and a React plus TypeScript frontend. It ships native installers for Windows, macOS, and Linux. The single official website is ccswitch.io; treat lookalike domains and unofficial builds with caution, because this is a tool that handles API credentials.

The core idea is narrow and useful: instead of editing config files to change which provider a CLI talks to, you import providers once and switch between them from a list or the system tray.

2. The Problem It Solves

Modern AI-assisted coding leans on terminal tools, and each one defines its own configuration format. Claude Code uses JSON settings, Codex uses its own file, and other tools use TOML or environment variables. If you keep several providers, for example an official subscription plus one or two relay services, you end up maintaining several variants of each config and swapping them by hand.

Beyond provider keys, there is a second kind of fragmentation: MCP servers, system prompts, and skills are configured separately in every tool. There is no built-in way to keep them aligned across Claude Code, Codex, and Gemini CLI.

CC Switch addresses both. It centralizes provider definitions and offers unified panels for MCP, prompts, and skills, so the same setup can be applied across tools instead of being copied by hand. For background on why provider routing matters for developers in China, see our companion guide on using Chinese LLMs in Claude Code.

3. Key Features

Provider switching. CC Switch ships with 50+ provider presets, including options such as AWS Bedrock and NVIDIA NIM alongside community relays. You copy your key, import a preset, and switch with one click. A system tray menu lets you change provider without opening the full app, and providers can be sorted, imported, and exported.

Unified MCP, prompts, and skills. A single MCP panel manages servers across multiple apps with bidirectional sync and deep-link import. Prompts are edited in Markdown and synced to the live files each tool expects, such as CLAUDE.md, AGENTS.md, and GEMINI.md. Skills can be installed from GitHub repositories or ZIP files with one click.

Local proxy and failover. An optional local proxy mode supports hot-switching, format conversion between provider APIs, automatic failover, a circuit breaker, and provider health monitoring.

Usage and cost tracking. A dashboard tracks spending, requests, and tokens, with trend charts and per-model pricing.

Sessions, sync, and quality-of-life. It can browse and restore conversation history across supported tools, sync configuration across devices through Dropbox, OneDrive, iCloud, or a WebDAV server, and import providers, MCP servers, prompts, and skills through a ccswitch:// deep link. It also includes light and dark themes, auto-launch, and an auto-updater.

4. How It Works Internally

CC Switch follows a single-source-of-truth design. According to the project documentation, all syncable data lives in a SQLite database at ~/.cc-switch/cc-switch.db, while device-level UI preferences live in ~/.cc-switch/settings.json. Automatic backups are kept under ~/.cc-switch/backups/, rotated to the ten most recent.

Switching is a two-way sync. When you enable a provider, CC Switch writes the configuration into the live files the CLI actually reads. When you edit the currently active provider, it backfills changes from those live files so the database stays accurate. Writes use a temp-file-and-rename pattern so an interrupted save cannot corrupt your config, and the database connection is mutex-protected to avoid race conditions.

One detail matters for daily use: most tools require restarting the terminal or the CLI for a provider change to take effect, but the project notes that Claude Code currently supports hot-switching provider data without a restart.

The design also follows a minimal-intrusion principle. Because CC Switch writes standard config files rather than hijacking the tools, your CLIs keep working even if you uninstall it. The app intentionally keeps one provider always active, which is why it will not let you delete the currently enabled provider.

5. Installing It

System requirements are Windows 10 or newer, macOS 12 (Monterey) or newer, and mainstream Linux distributions such as Ubuntu 22.04+, Debian 11+, or Fedora 34+.

On macOS, the simplest path is Homebrew:

brew install --cask cc-switch

The macOS build is code-signed and notarized by Apple, so it installs without extra steps. On Windows, download the .msi installer or the portable .zip from the Releases page. On Linux, choose the .deb, .rpm, or .AppImage build; Arch users can install cc-switch-bin through paru.

On first launch, you can import your existing CLI configuration as the default provider, so you do not start from an empty slate.

6. A Practical First Workflow

Start small and verify before you rely on it. Add one provider you already use as the default, add a second provider you want to compare against, then switch between them and confirm each CLI behaves as expected.

For Claude Code, you can switch providers and keep working thanks to hot-switching. For Codex, Gemini CLI, and the others, restart the terminal after switching. Use the official-login preset when you want to return to a vendor's normal account flow; after switching to it, run that tool's login or OAuth flow.

Once provider switching is reliable, layer in the rest: bring your MCP servers into the unified panel, move shared prompts into the Markdown editor so CLAUDE.md and AGENTS.md stay aligned, and install skills you reuse across tools.

7. When CC Switch Helps, and When You May Not Need It

CC Switch earns its place when you regularly juggle multiple providers or multiple CLIs, when you want MCP and skills aligned across tools, or when you want tray-level switching and usage tracking without scripting it yourself.

If you only use one CLI with one provider and never change it, the value is smaller. The same is true if you prefer fully scripted, version-controlled environment setup; in that case a checked-in shell profile or per-project environment file may fit your workflow better. CC Switch is a convenience and management layer, not a requirement for any of these tools to run.

8. Security and Operational Notes

This is a tool that stores API credentials, so handle it with the same care you would give any secret manager.

Download only from the official site or the project's GitHub releases. Because providers and keys live in a local SQLite database, anyone with access to your machine and that file effectively has your keys; protect the device accordingly, and think carefully before syncing that database through a third-party cloud folder.

Keep credentials out of your repositories. Provider keys belong in CC Switch, your shell environment, or a secret manager, never committed to git. If you enable the local proxy, understand that requests will route through it, and confirm that failover targets are providers you actually trust.

As always, the switching layer changes which model answers, not whether the output is correct. Review diffs, run your project's checks, and keep a human approval gate for anything that touches authentication, payments, migrations, or publishing.

Conclusion

CC Switch is a focused answer to a real annoyance: keeping several AI coding CLIs and several providers configured without hand-editing fragile config files. Its SQLite single-source-of-truth, two-way sync, and atomic writes make the switching itself dependable, and the unified MCP, prompt, and skills panels reduce the copy-paste that usually comes with running more than one tool.

It does not replace good judgment about which provider to use or whether to trust a given output. Used carefully, with keys kept local and changes still reviewed, it is a practical way to make multi-provider, multi-CLI development less tedious and less error-prone.