CC Switch

CC Switch is a free, open-source desktop app (MIT licensed) for managing provider configuration across AI coding tools. It writes configuration into each tool's own files, and the tools still connect directly to the provider — it does not proxy or log your requests.

Supported tools: Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Pi.

When to use it#

• You need to switch between a subscription and API usage: move to Amux pay-as-you-go without reconfiguring the tool itself
• You keep several provider configurations: each one is stored separately and can be switched with one click
• You want Claude Code's three model tiers mapped to different models: CC Switch includes a dedicated model-mapping UI
• You already configured tools manually and want one place to manage them: CC Switch swaps the whole configuration at once, which avoids stale environment variables

1. Install#

macOS#

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

You can also download a DMG or ZIP from GitHub Releases and drag CC-Switch.app into Applications.

Windows#

Download the .msi from Releases and run it. Or take the portable .zip, extract it anywhere, and run CC-Switch.exe.

Linux#

# Debian / Ubuntu
sudo dpkg -i cc-switch_*.deb

# AppImage
chmod +x CC-Switch_*.AppImage
./CC-Switch_*.AppImage

2. Create an Amux key#

Create one on the keys page in the console. The key remains viewable there after creation, so you do not need to rotate it just to retrieve it again.

To track usage per tool, create a separate key for each: everything sent with one key is recorded against that key and cannot be split apart afterwards.

3. Add Amux as a provider#

Open CC Switch, pick the tool in the top navigation, and click "Add Provider". Three fields:

Each section below gives the values to enter and what CC Switch ends up writing into that tool's configuration — which is useful when something does not work: open that file and you immediately know whether the configuration was never written, or was written and the tool has not re-read it.

Claude Code and Claude Desktop (Anthropic protocol)#

No /v1 on the address: Anthropic clients append /v1/messages themselves, and the extra segment turns into /v1/v1/messages, which comes back 404.

Model mapping takes Amux canonical IDs:

The tiers do not have to be Claude. Protocol and model are two separate things — mapping the Opus tier to openai/gpt-5.6 or deepseek/deepseek-v3.2 works just as well, and Claude Code carries on as usual.

What ends up in Claude Code's configuration looks roughly like this:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.amux.ai",
    "ANTHROPIC_AUTH_TOKEN": "<your Amux key>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Codex (OpenAI protocol)#

What ends up in ~/.codex/config.toml:

model_provider = "amux"
model = "openai/gpt-5.6"

[model_providers.amux]
name = "Amux"
base_url = "https://gateway.amux.ai/v1"
wire_api = "responses"

wire_api can be responses or chat. Both endpoints are implemented natively; responses is the default and usually the better first choice.

Gemini CLI (Gemini protocol)#

What ends up in ~/.gemini/.env:

GOOGLE_GEMINI_BASE_URL=https://gateway.amux.ai
GEMINI_API_KEY=<your Amux key>
GEMINI_MODEL=google/gemini-3-pro

OpenCode, OpenClaw, Hermes Agent and Pi (OpenAI protocol)#

OpenCode's comes out like this:

{
  "npm": "@ai-sdk/openai-compatible",
  "options": {
    "baseURL": "https://gateway.amux.ai/v1",
    "apiKey": "<your Amux key>"
  },
  "models": {
    "anthropic/claude-opus-5": { "name": "Claude Opus 5 (via Amux)" }
  }
}

4. Switch over#

Click the toggle next to Amux in the provider list.

Claude Code supports hot switching — the current session picks it up immediately. The other tools need a fresh terminal or an application restart, since they read their configuration at startup.

Universal provider#

CC Switch has a "universal provider" option: turn it on and one Amux configuration is shared across Claude Code, Codex, Gemini CLI and OpenCode, while each tool keeps its own model mapping. It saves adding the provider several times when you run more than one tool.

Note that the Base URL differs by protocol (Anthropic without /v1, OpenAI with it), so each tool still follows its own row above.

Checking it works#

Send any message after switching. A reply means you are through.

In Claude Code, /status shows the address and auth method currently in effect, so you can confirm it is Amux.

Troubleshooting#

Authentication failure / invalid key#

Check the Base URL field first — the wrong protocol also surfaces as an auth-style error, and people go looking at the key. Then check that the key was copied in full (leading or trailing whitespace is the usual culprit), that it is still enabled in the console, and that the workspace has balance.

macOS says the app is damaged or cannot be opened#

Download only from the official GitHub Releases. Then go to System Settings → Privacy & Security, find CC Switch in the blocked list, and click "Open Anyway".

Nothing happens in the tool after switching#

Check three things in order: CC Switch is still running; the Amux entry shows as active in the list; the tool needs a restart (everything except Claude Code does). If all three are fine, open the configuration file listed in the section above and see whether the values are actually there.

Model unavailable / protocol mismatch#

Model IDs need the vendor prefix (anthropic/claude-opus-5, not claude-opus-5). Also, not every model supports every protocol — each model's page lists the protocols actually available for it, so a tool speaking Anthropic needs a model that supports Anthropic. Asking for an unsupported combination fails with a clear error rather than degrading silently.

Can a subscription and Amux coexist?#

Yes. Both configurations can live in CC Switch and be toggled at will, though only one is active at a time.

Does it proxy or log my requests?#

Not by default — it only writes configuration into the tool, and the tool connects directly. There is an optional local proxy-and-failover mode; only with that enabled do requests pass through it and produce local logs.

Where do I see usage?#

On the usage page in the Amux console. It is counted per key and cannot be split by tool — create a separate key per tool if you need that.