The Ultimate Developer Guide to CC Switch
1. Introduction
The modern software engineering landscape has transitioned from simple, autocomplete-style AI inline suggestions to autonomous, terminal-resident AI agent workflows. Developers no longer just use AI; they collaborate with it in full-loop coding tasks. Tools such as Claude Code, Claude Desktop, Google's Gemini CLI, OpenAI's Codex, OpenCode, OpenClaw, and Hermes Agent represent a paradigm shift. They can search local projects, edit files, execute git commits, run unit tests, and resolve build errors directly.
However, as the proliferation of these command-line interface (CLI) agents has accelerated, so has the configuration overhead. Operating multiple separate agents across different workspaces requires managing fragmented configuration formats (JSON, TOML, YAML, `.env` files), handling custom API relays, orchestrating Model Context Protocol (MCP) servers, syncing system prompts, and debugging environment variables.
CC Switch is the definitive open-source desktop solution built to resolve these pain points. By providing a unified, local-first management system, CC Switch acts as the control panel for all your AI coding agents, enabling hot-switching of providers, local request proxying, high-availability failover, and bidirectional configuration syncing.
2. What is CC Switch?
CC Switch is an open-source, cross-platform desktop application built on the Tauri 2 and Rust framework. It acts as an orchestrator and manager for seven core developer-focused AI agent CLI tools:
- Claude Code: Anthropic’s high-performance terminal agent.
- Claude Desktop: Anthropic's flagship desktop client, supporting official sign-ins and third-party configuration profiles.
- Codex: OpenAI’s powerful code-generation CLI.
- Gemini CLI: Google's developer CLI tool powered by Gemini models.
- OpenCode: An open-source, terminal-based coding assistant.
- OpenClaw: A highly custom agent gateway.
- Hermes: An agent framework specialized in memory, tools, and MCP servers.
Instead of requiring developers to manually edit raw config files under hidden home directories
(~/.config/ or ~/.claude/), CC Switch provides a visually polished, local-first
interface to add, configure, test, and switch between more than 50 API provider presets.
3. Why It Exists & The Problems It Solves
AI agents are powerful, but the developer experience surrounding their configuration is highly fragmented. Below are the key problems CC Switch resolves:
Using different API providers (official, proxy services) requires manually editing configuration files across several distinct directories.
Fragmented Configurations
Each AI tool stores its settings differently. Claude Code uses a hidden JSON config, Codex uses a custom TOML or environment variables, and Gemini CLI relies on bash/zsh profiles. Switching from an official endpoint to an internal company gateway or a third-party relay requires editing several configurations across multiple files.
Lack of Centralized Logging and Spending Auditing
Developers running large agent tasks (like resolving a test suite) often have no direct visibility into how many tokens were consumed, which API endpoints were called, or what the actual dollar cost of the run was until they check their cloud provider billing console.
Single-Point-of-Failure (SPOF)
If an API provider goes down or experiences rate limits mid-workflow, the CLI agent fails immediately, halting the developer's momentum. There is no native mechanism in these tools to switch to a backup provider automatically.
MCP and Extension Fragmentation
Model Context Protocol (MCP) servers allow LLMs to read databases, inspect container states, or search documentation. Managing these servers across Claude Desktop, Claude Code, and Hermes separately results in sync issues and configuration drift.
4. Core Features
CC Switch is designed to be the ultimate cockpit for AI coding agents. Its key capabilities include:
1. Visual Provider Management
A single dashboard containing over 50 provider presets (including Anthropic, OpenAI, Google, AWS Bedrock, Nvidia NIM, SiliconFlow, Kimi, DeepSeek, GLM, and specialized dev relays like Cubence, DMXAPI, and PackyCode). Users can import their API keys, measure latencies via a built-in Speed Test service, and switch active profiles in one click.
2. Local Proxy Service & High Availability Gateway
CC Switch starts a local HTTP proxy server (http://127.0.0.1:15721) that acts as an
intelligent intermediary. When enabled, it intercepts agent traffic and applies advanced rules:
- Format Conversion: Translates Anthropic Messages format to OpenAI Chat Completions on the fly, allowing developers to run Claude Code using OpenAI-compatible endpoints or models like DeepSeek-Coder.
- Automatic Failover: Dynamically routes requests to a secondary provider in the queue if the primary provider fails or returns a rate-limit error.
- Circuit Breaker: Automatically suspends a failing provider for a set recovery period (default 60 seconds) to prevent infinite retry loops.
3. Unified MCP, Prompts, & Skills Management
MCP Panel: Centralizes MCP server definitions and handles bidirectional synchronization, ensuring that servers added to CC Switch are automatically populated in Claude Desktop and other supporting tools.
Prompt Sync: Markdown prompt editor with backfill protection that maintains sync between
files like CLAUDE.md, AGENTS.md, and GEMINI.md.
Skills Manager: Resolves one-click installations of skill scripts from Git repositories or local ZIP files directly into the target agent folders.
4. Cost and Token Tracking Dashboard
A visual analytics dashboard that reads SQLite request logs. It tracks total queries, token volumes, cache hit rates (critical for optimizing costs when using prompt caching on Claude 3.5 Sonnet), and live spending metrics based on customizable, model-specific pricing tables.
5. Supported AI Platforms & Presets
CC Switch contains deep integration for mainstream LLM platforms. The following catalog provides detail on preset configuration templates:
| Preset Name | Protocol Type | Target Model | Routing Badges |
|---|---|---|---|
| Claude Official | Anthropic Messages | claude-3-5-sonnet / claude-3-opus | Direct Connection |
| DeepSeek | Chat Completions | deepseek-coder / deepseek-reasoner | Local Routing Required |
| Kimi For Coding | Chat Completions | kimi-k2.7-code | Local Routing Required |
| SiliconFlow | OpenAI Compatible | multi-model support | Direct Routing |
| OpenAI Official | Chat Completions | gpt-4o / o1-pro / gpt-5.5-preview | Direct Connection |
| Google Official | Gemini Native | gemini-1.5-pro / gemini-2.0-flash | Direct OAuth |
6. Installation Guide
CC Switch supports all major desktop environments with native-compiled binaries. Follow the instructions corresponding to your operating system:
macOS Installation
The macOS app is signed and notarized by Apple. You can drag the .dmg into your Applications
folder or install via Homebrew:
# Install using Homebrew cask
brew install --cask cc-switch
# Upgrade package to latest version
brew upgrade --cask cc-switchWindows Installation
Requires the Microsoft Edge WebView2 runtime. Run the CC-Switch-v3.16.1-Windows.msi installer,
or use the portable .zip package.
# Install WebView2 via WinGet if needed
winget install Microsoft.EdgeWebView2RuntimeLinux Installation
Download the relevant release package (.deb, .rpm, .AppImage) or
install via the Arch User Repository (AUR):
# Arch Linux AUR installation
paru -S cc-switch-bin
# Run AppImage from shell
chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImageOn Wayland sessions utilizing NVIDIA GPUs, launch the AppImage with:
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage to bypass mouse pointer problems or
black screens on window resizes.
7. Technical Architecture
CC Switch is built upon a high-performance, security-focused architecture designed around Tauri 2 and Rust, with a modern UI fronted by React 18 and TypeScript.
Tauri IPC and Asynchronous Rust
Tauri acts as the secure bridge. It executes commands securely on the local operating system, passing structured JSON messages between the frontend and the Rust backend, avoiding the memory usage associated with Electron-based wrappers.
The backend core processes incoming connections in a multithreaded environment utilizing the Tokio async runtime. Structured database calls map directly to SQLite schemas via transaction-safe connection managers.
8. How It Works: The Local Proxy & Format Conversion
The defining technical breakthrough of CC Switch is its local proxy engine. Let’s look at the flow of a
developer query when executing claude code in the terminal:
- Request Capture: The user enters a prompt in the terminal. Claude Code sends a JSON POST request containing Anthropic messages data.
- Interception: Because CC Switch is running in the background with "App Takeover"
enabled, the local CLI tool is configured to point its endpoint base URL to
http://127.0.0.1:15721. - Local Format Rectification: If the active provider is configured with the OpenAI format
(e.g., DeepSeek Coder), CC Switch intercepts the request. The Rust proxy service translates the Anthropic
Messages structure (system instructions, user prompts, dynamic history) into standard OpenAI
chat/completionsschema arrays. - Forwarding & Stream Handling: The proxy executes the upstream HTTP request. It listens for the response stream. When chunks arrive from the upstream server, it converts the Server-Sent Events (SSE) from the OpenAI stream format back into Anthropic stream events on the fly, feeding them directly back to the terminal.
- Analytics Recording: Simultaneously, the token usage and cost metrics are written
asynchronously to
cc-switch.db.
9. Setup Workflow
Getting up and running with CC Switch takes less than 5 minutes:
Step 1: First hook - Upon startup, CC Switch scans your filesystem for existing agent settings (e.g., Claude Code configs or Google CLI configs) and auto-generates your default provider layout.
Step 2: Add provider configuration - Click the "+" icon, select a preset template (e.g., Kimi For Coding or SiliconFlow), paste your API key, and click Save.
Step 3: Toggle proxy gateway - Click the Proxy Toggle button at the top of the interface until it lights up green, then enable App Takeover for your desired CLI agents.
Step 4: Execute agent CLI - Start your agent in the terminal. Your requests will now route through CC Switch. You can switch active backends instantly via the system tray icon menu without interrupting your active shell session.
10. Advanced Configuration & Deep Customization
CC Switch stores files in local user paths for complete configuration control:
- Database:
~/.cc-switch/cc-switch.db- SQLite table containing providers, MCPs, logs, and prompt models. - Device Settings:
~/.cc-switch/settings.json- Stores local window preferences, dark/light themes, and minimized state toggles. - Backups:
~/.cc-switch/backups/- Automated database copy rotation keeping the 10 most recent states. - Skills Folders:
~/.cc-switch/skills/- Symlinked paths mapping directly to active agent plugin locations.
Model Mapping Customization
To use Claude Desktop with custom third-party relays, you must define custom model mapping rules. The following JSON structure maps upstream model ids into desktop sonnet, opus, or haiku profiles:
{
"claude-3-5-sonnet-20241022": "deepseek-coder",
"claude-3-opus-20240229": "deepseek-reasoner",
"claude-3-5-haiku-20241022": "deepseek-coder"
}11. Security, Performance & Developer Experience
Local-First Security: Your API keys, prompt logs, and session files are never sent to CC
Switch servers. Everything is stored locally in your SQLite database. The proxy server runs entirely on your
localhost loopback adapter (127.0.0.1), ensuring zero network exposure to third parties.
High Reliability via Atomic Writes: When writing configuration files back to disk, CC
Switch employs an Atomic Write Pattern. It writes updated payloads to a temporary file (e.g.,
config.json.tmp), calls OS-level flush operations, and performs an atomic replace. This
prevents corrupted settings if a crash occurs mid-write.
Low Memory Footprint: Tauri compiles directly to native OS web views rather than bundling an entire Chrome executable. When minimized to the system tray in Lightweight Mode, the main window is destroyed, keeping idle memory consumption below 15MB RAM.
12. Best Practices & Troubleshooting Tips
Optimize your agent configurations using these developer tips:
Resolve Proxy Port Conflicts
If the local proxy fails to start, the port 15721 is likely occupied by another process. Run
the diagnostics checks to verify:
# macOS & Linux port check
lsof -i :15721
# Windows port check
netstat -ano | findstr :15721Terminate the conflicting process, or modify the listening port setting inside the CC Switch Advanced settings panel.
Config Snippet Backfill Protection
When switching providers, your global agent variables (personas, ignore files, editor setups) might get wiped. Configure the **Shared Config Panel** and select "Write Shared Config" to ensure these properties carry over to new profiles automatically.
13. Frequently Asked Questions (FAQ)
Q: Does CC Switch cost money?
A: No, CC Switch is free and open-source under the MIT License.
Q: Do I need to restart my terminal after switching providers?
A: For Codex and Gemini CLI, yes. For Claude Code, no - it supports live hot-swapping configurations without terminal restarts.
Q: How does the auto-failover queue determine health status?
A: If a request returns a network error, timeout, or a status code of 5xx/429, CC Switch registers a failure. After 3 consecutive failures, the active provider status turns red and routes requests to the next standby provider in the queue automatically.
14. Future Scope
The CC Switch roadmap aims to incorporate several new key additions:
- Local LLM Routing: Built-in direct integrations for local offline model engines running Ollama or Llama.cpp.
- Dynamic Context Injection: Automatically inserting dynamic environment files (e.g., local Git diff states) into prompt streams before requests leave the local proxy gateway.
- Network Dashboard: Web dashboard interface enabling secure remote cost monitoring and log checking from different developer machines on the same local network.
15. Conclusion
As AI agents become an integral part of modern software development, having a structured, secure, and highly available configuration manager is essential. CC Switch simplifies this complexity. By offering visual provider management, local proxy conversion, robust failover queues, and unified MCP syncing in a lightweight Tauri package, it allows developers to focus on what matters most: building great software.
Whether you are a sole developer utilizing DeepSeek, or an enterprise team orchestrating custom internal models, CC Switch provides the tools you need to build a modern, high-performance AI development workflow.