Many Relays · One Click

CC Switch Tutorial

Stop editing config files by hand — switch AI CLI relay providers in one click

CC Switch is an open-source, cross-platform desktop tool (by farion1231, MIT-licensed, tens of thousands of GitHub stars). If you switch between multiple relay endpoints, or run Claude Code, Codex, and Gemini CLI side by side, it puts all their API provider configs into one visual interface that sits in your system tray — right-click to switch. This guide covers how it works, how to install it, and how to use it well.

// The Problem

1. What Headache It Actually Solves

If you have used relay endpoints, you know the scenario: relay A is cheap but flaky, B is stable but pricey, C just launched a discount. To switch, you have to dig into settings.json or env vars, manually change the endpoint and API key, then restart the terminal.

Running several tools makes it worse — Claude Code, Codex, and Gemini CLI each have their own config files in different formats. CC Switch is here to clean up that mess:

Centralize every tool's provider config into one visual interface
Switch providers with a single right-click in the tray, no file editing
Store each provider as a preset you can flip between, configs never lost
Cross-platform: Windows, macOS, Linux — MIT open-source and free

💡 One-line positioning: CC Switch = a "provider remote control" for AI CLI tools.

// Supported Tools

2. Supported Tools and What It Manages

It is a unified config manager for several mainstream AI coding CLIs, and the coverage keeps growing.

Category	Details
Supported tools	Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, and more
Managed config	API providers (endpoint + key), MCP servers, Skills for some tools
Core interaction	Tray-resident; right-click to switch the active provider in one click
Platforms	Windows 10+, macOS 12+, mainstream Linux distros
License	MIT, open-source and free

For relay users the first row is the most useful: store each relay as a provider preset, switch to whichever works best, and flip away the moment one acts up.

// How It Works

3. How It Works: No Magic, Just Editing Config For You

Understanding the mechanism makes you more confident and makes troubleshooting easier. What CC Switch does is plain:

Store presets

Each provider you add is saved into CC Switch’s own config store.

Write back config

When you switch, it writes that provider’s endpoint and API key back into the target tool’s config file (Claude Code’s settings.json, Codex’s config, etc.).

Tool picks it up

The tool reads the new config on next launch (or immediately, where hot-switch is supported), and requests now go to the new provider.

So it is not a proxy and does not take over your traffic (unless you enable the optional local proxy). Its core job is to edit the right config file safely and quickly. That also means whether the tool needs a restart afterward depends on whether that tool supports hot-switching.

⚠️ Since it writes tool config files directly, on first use confirm it does not overwrite existing config you care about. Newer versions handle "prevent overwriting Claude config", but keep a backup habit anyway.

// Install

4. Installation

It is a desktop GUI app — pick the install method for your platform.

macOS

# Install via Homebrew (recommended)
brew install --cask cc-switch

Windows / Linux

Go to the Releases page of the GitHub repo farion1231/cc-switch, download the installer for your platform (.exe / .msi for Windows, .AppImage / .deb for Linux), and run it.

💡 When unsure which build to grab, stick to Releases on the official farion1231/cc-switch repo to avoid same-named forks.

// Add a Provider

5. Add Your First Relay Provider

Once installed and opened, the core action is "add a provider". Using Claude Code with a relay as the example:

Select the tool

Pick the tool to configure in the UI, e.g. Claude Code.

Add a provider

Click "Add provider" and give it a recognizable name, e.g. "Relay A - cheap".

Fill endpoint and key

Enter the Base URL and API key your relay gave you. Both are available in the relay’s dashboard.

Save and switch

After saving, click the preset; CC Switch writes it into Claude Code’s config and it takes effect immediately (or after restarting the terminal).

You can add any number of providers under the same tool. Add all the relays you use, and switching later is a single click.

// Daily Switching

6. The Smoothest Way to Switch Day to Day

CC Switch's essence is the system tray. The daily flow:

It stays in the tray, so you do not need to open the main window each time
Right-click the tray icon to list all providers and click to switch the active one
When a relay slows down or errors, switch to a backup instantly without interrupting your work

About hot-switching

Early versions required restarting Claude Code after switching. Newer versions support hot-switching providers — it takes effect without restarting the terminal, which is much smoother. This depends on your installed version, so keep it reasonably updated.

💡 Configuring "a primary relay + 1–2 backups" and flipping on the fly when one acts up is the most satisfying workflow for relay users.

// Advanced

7. Advanced: Backup, MCP, and Local Proxy

Config backup

All provider presets live in CC Switch's own config, so you can migrate them when changing or reinstalling machines without hunting for keys again. Fold this config into your backup routine.

MCP server management

Beyond API providers, it can also centrally manage MCP server configs across tools, sparing you from re-configuring MCP in each tool.

Local proxy (optional)

It also offers an optional local HTTP proxy that can unify API requests across Claude Code, Codex, and Gemini CLI. This is an advanced capability you do not need for plain switching — enable it only if you want it.

// Troubleshooting

8. Common Troubleshooting

Symptom	Where to look
Switch had no effect	Does the tool need a restart; does your version support hot-switch; confirm config was actually written
Auth error	Wrong endpoint or API key; relay key expired or out of balance
Config overwritten	Upgrade to a newer version (has overwrite protection); keep a manual backup
Tool config not found	Ensure the target tool is installed and has run at least once to generate its config

Rule of thumb: CC Switch only edits config. When something breaks, first decide whether it is "config written wrong" or "a problem with the relay itself" — separating those two layers makes diagnosis easy.

// Summary

Summary

For anyone constantly hopping between relays, or running multiple AI CLIs at once, CC Switch is close to a must-have.

Centralize

Every tool’s provider config in one interface

One-Click Switch

Right-click the tray to swap relays, no file editing

Never Lose Config

Each relay saved as a preset, flip anytime

Install it, add your go-to relays, and switching providers becomes a single right-click — spend your energy writing code, not editing config.

No relays to switch between yet?

Pick a few relay platforms, add them to CC Switch, and switch anytime in one click

Browse Relay Platforms