CC Switch: moving between Claude Code and Codex
Published Jul 15, 2026 · Checked against the official docs
CC Switch is a free, open-source desktop app that stores every provider setup for Claude Code, Codex, and other CLIs in one place, then rewrites the live config files when you pick one from a menu or the system tray. Add your providers once and switch without hand-editing ~/.claude/settings.json or ~/.codex/config.toml. It backs up before every write.
CC Switch is a desktop app that keeps every provider setup for your AI coding CLIs in one SQLite database, then writes the right one into the live config files when you switch. You add your Claude Code and Codex providers once, then flip between them from the app window or the system tray instead of hand-editing JSON and TOML. Version 3.17.0 shipped 13 July 2026 under an MIT license and runs on Windows, macOS, and Linux (repo).
Install
It’s a Tauri desktop build, so you grab the package for your OS. Fastest paths:
# macOS
brew install --cask cc-switch
# Arch Linux
paru -S cc-switch-binOn Windows, download CC-Switch-v3.17.0-Windows.msi (or the portable ZIP) from the releases page and run it. Debian and Ubuntu get a .deb, Fedora and RHEL get a .rpm, and there’s a universal .AppImage too.
How switching works
Once it’s installed:
- Click Add Provider, pick a preset or paste your own base URL, key, and model.
- Do that for each Claude Code and Codex provider you run.
- Select one and hit Enable, or switch straight from the tray menu.
Under the hood it writes your real config files. For Claude Code it sets env.ANTHROPIC_BASE_URL and env.ANTHROPIC_AUTH_TOKEN in ~/.claude/settings.json. For Codex it updates the key in ~/.codex/auth.json and the base_url and model fields in ~/.codex/config.toml (config-files doc). Its own data sits in ~/.cc-switch/: the cc-switch.db database plus a backups/ folder that keeps the last 10 versions and auto-backs-up before each write (repo).
The docs say Claude Code picks up the swap without a restart, while Codex needs you to restart the CLI so it re-reads the config (repo).
If it fails
Get it from the right place first. The README flags ccswitch.io as the only official site, so treat any other domain that claims to host it as suspect. Install from the GitHub releases or Homebrew to stay clean.
If Codex or Claude throws a 401 right after a switch, the key CC Switch wrote is wrong, expired, or doesn’t match the base URL for that provider. Re-check the provider entry in the app, then confirm the base URL and key belong together. Details on Stream error: 401 Unauthorized.
Don’t hand-edit the live files while CC Switch owns them. It treats its database as the source of truth and re-syncs on switch, so manual changes to settings.json or config.toml can get overwritten on the next flip. Edit the values inside the app instead.
Related
- model_provider: the Codex config key CC Switch sets when you switch.
- model_providers.base_url: the endpoint it writes into config.toml.
- Stream error: 401 Unauthorized: the usual failure after a bad switch.
- Prefer headless? There’s a community CLI fork.
By the Codex Insider Desk.