CC Switch: Provider Manager for AI Coding Tools

CC Switch is a desktop control panel for AI coding tool configuration. It began as a provider switcher, but the current application also manages MCP servers, instruction files, skills, sessions, usage records, and local proxy routing.

Version 3.20.0, released August 18, 2026, added Pi as a ninth managed application and expanded multi-account Codex support. The supported application list can change, so use the current release notes rather than an old screenshot when a tool is missing.

CC Switch versus similarly named tools#

Several projects use nearly the same words:

This guide covers only farion1231/cc-switch. The project’s official website is ccswitch.io, and its source and downloads are on the linked GitHub repository.

What it manages#

Provider cards are the visible part of CC Switch. A preset supplies the expected endpoint and fields; a custom provider lets you enter them manually. Enabling a card writes the live configuration for the selected application.

The rest of the application handles configuration shared across tools:

• MCP server definitions can be synchronized to supported clients.
• Prompts can update files such as CLAUDE.md, AGENTS.md, and GEMINI.md.
• Skills can be installed from a repository or ZIP file.
• Session views can browse and restore supported conversation histories.
• The usage dashboard records requests, tokens, and configured model prices.
• A local proxy can translate formats and fail over between providers.

flowchart LR
A[CC Switch database] --> B[Provider profiles]
A --> C[MCP and skills]
A --> D[Prompt files]
B --> E[Claude Code]
B --> F[Codex]
B --> G[Other managed clients]
B --> H[Optional local proxy]
C --> E
C --> F
D --> E
D --> F

Install CC Switch on Windows#

Download either the current MSI installer or portable ZIP from GitHub Releases. The release page publishes checksums for its assets. Compare the checksum after downloading when you are installing on a machine that stores API keys.

The project supports Windows 10 and later. macOS and Linux packages are also available, but configuration paths differ between operating systems.

On first launch, import an existing client configuration or add one provider. Do not synchronize every application immediately. A narrow first test makes it clear which file changed.

Add and activate a provider#

1. Select the application you want to manage.
2. Add a provider from a current preset or choose Custom.
3. Enter the endpoint, API key, and model mapping required by that application.
4. Save the card, then click Enable.
5. Restart the target CLI unless the manual says it hot-reloads configuration.
6. Run a small read-only prompt and inspect the provider’s usage page.

Presets are templates, not permanent facts. Model IDs and endpoints change. Compare a preset with the provider’s current documentation when authentication or model discovery fails.

Universal providers and model mapping#

A universal provider can synchronize one service across multiple clients, but the clients do not speak identical protocols. Claude Code uses Anthropic Messages conventions, current Codex relies on Responses, and other clients may use Chat Completions. CC Switch can use its local proxy for format conversion where supported.

Model mapping handles role names such as Sonnet, Opus, or Haiku when a client requests a role rather than a raw upstream ID. Map each role deliberately. Sending every role to one expensive reasoning model can turn a small helper request into unnecessary cost.

MCP, prompts, and skills#

The unified panels save repeated configuration work, but synchronized files can overwrite manual changes. Backfill protection and backups reduce risk; they do not replace source control.

Export the current configuration before the first bulk sync. Enable one MCP server or skill for one application, inspect the resulting file, and then expand the scope. Review a skill’s source before installing it because skills can instruct an agent to run commands or access data.

Prompt synchronization needs the same discipline. CLAUDE.md, AGENTS.md, and GEMINI.md have different consumers and sometimes different instruction rules. Shared text should be genuinely portable. Keep tool-specific commands in the appropriate file.

Local proxy and failover#

CC Switch’s local routing mode can translate requests, monitor health, open a circuit after failures, and move to another provider. It can take over routing for selected applications or providers rather than changing every client at once.

Begin with one direct provider and record a successful tool-calling test. Add a fallback only after that baseline works. Otherwise, an automatic fallback can hide the source of an error and send a sensitive prompt to a provider you did not expect.

Usage and cost figures depend on the pricing table configured in CC Switch. They are estimates unless reconciled with the provider invoice. Update custom pricing when a model changes rates.

Backups, cloud sync, and credentials#

CC Switch supports a custom configuration directory and cloud synchronization options including WebDAV and current release-specific backends. Configuration portability is useful, but provider keys and tokens may be part of that state.

Use an encrypted destination with a dedicated account. Do not place the configuration folder in a broadly shared OneDrive, Dropbox, or NAS directory. Test restore on a non-production profile before relying on cloud sync as the only backup.

The application uses atomic writes and automatic backups to reduce file corruption. Keep a manual export before a major version upgrade or a large cross-app sync.

Troubleshooting#

If switching does not take effect, restart the target terminal or CLI. Claude Code currently supports hot-switching, while other applications may keep configuration in memory.

An authentication error can come from the provider card, the local proxy, or the target client. Disable takeover and test the provider directly to narrow the path. For a model-not-found response, refresh the provider’s live model list or correct the mapping instead of repeatedly replacing the API key.

If manual configuration disappears after a sync, restore the automatic backup and decide whether CC Switch or the application should be the source of truth. Two tools writing the same file will keep undoing each other.

CC Switch fits users who want a desktop view of configuration shared across several AI tools. Terminal-first users may prefer CCS. For central request routing and fallback combos, compare 9Router and LiteLLM.