1. Project Overview
CC Switch is a cross-platform desktop application that unifies provider, MCP, prompt, and skill configuration management for eight popular AI coding tools โ including Claude Code, Claude Desktop, and Codex โ replacing manual, error-prone edits to scattered config files with a single visual interface.
2. Background & Positioning
AI coding assistants like Claude Code, Codex, and Gemini CLI each store API keys, model endpoints, and provider settings in their own config files and formats. Developers who use several of these tools side by side, or who switch between multiple API providers for cost, latency, or availability reasons, end up hand-editing JSON/TOML files and restarting terminals just to change a provider. CC Switch was built to remove that friction: it centralizes provider presets, MCP servers, prompts, and skills in one SQLite-backed store and pushes the right format to each tool automatically.
Compared with simple shell-script "profile switchers" that only swap environment variables or a single config file, CC Switch differs by covering eight tools at once with 50+ built-in provider presets, offering a native GUI with system-tray quick switching, adding a local proxy layer with auto-failover and circuit breaking, and providing cross-device sync (Dropbox/OneDrive/iCloud/WebDAV) so a provider setup follows the developer across machines.
3. Feature Categories
- ๐ Provider Management โ 50+ presets across "8 supported tools, 50+ presets"; import, drag-and-drop reorder, and one-click switch providers for Claude Code, Codex, Gemini CLI, and others. Purpose: eliminate manual editing of each tool's provider config.
- ๐ Unified Configuration Sync โ one saved configuration can sync to Claude Code, Codex, and Gemini CLI simultaneously. Purpose: keep multiple CLI tools consistent and avoid configuration drift.
- ๐ก๏ธ Proxy & Failover โ local proxy with request format conversion, automatic failover, circuit breaker, and provider health checks. Purpose: keep coding sessions running even when a provider degrades or goes down.
- ๐งฉ MCP / Prompts / Skills Management โ dedicated panels for Model Context Protocol servers, prompt libraries, and skills, with cross-application sync and deep-link import. Purpose: manage extensions once instead of per tool.
- ๐ Session & History Browsing โ browse, search, and restore conversation history across supported session sources. Purpose: preserve continuity when moving between tools or machines.
- ๐ Usage Tracking โ dashboard for spend, token consumption, and request counts with trend charts and detailed logs. Purpose: give visibility into API cost and usage patterns.
- โ๏ธ Cloud Sync โ configuration sync via Dropbox, OneDrive, iCloud, or a custom WebDAV server. Purpose: keep the same provider/tool setup available across multiple devices.
4. Key Highlights
- Eight tools, one interface โ Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes are all configured from the same app instead of eight separate config files.
- System tray quick switching โ providers can be swapped from the tray menu without opening the full window, and Claude Code supports hot-switching without a restart.
- Local proxy with failover โ a built-in proxy performs format conversion between providers and automatically fails over with circuit-breaker protection when a provider becomes unhealthy.
- SQLite single source of truth โ providers, MCP configs, prompts, and skills are stored in one database (
~/.cc-switch/cc-switch.db) with atomic writes and mutex-protected concurrent access, avoiding config corruption. - Automatic backups โ the app keeps the ten most recent database backups and up to twenty skill snapshots before uninstallation, so configuration mistakes are recoverable.
- Native, code-signed builds โ Tauri 2 + Rust produces small, native binaries; macOS builds are code-signed and notarized by Apple.
5. Use Cases by Role
- General developers โ anyone using more than one AI coding assistant (e.g., Claude Code plus Codex or Gemini CLI) can maintain one provider list and switch instantly instead of editing config files per tool.
- DevOps / infrastructure-minded engineers โ the proxy's failover and circuit-breaker features help keep AI-assisted workflows resilient when a provider has an outage or rate-limits requests.
- Teams evaluating multiple LLM providers โ the 50+ presets and one-click switching make it easy to A/B test providers for cost, latency, or output quality without reconfiguring each CLI tool by hand.
- Developers working across multiple machines โ cloud sync (Dropbox/OneDrive/iCloud/WebDAV) keeps provider and MCP setups consistent between a laptop and a desktop.
6. Getting Started
Find what you need โ browse the built-in presets and feature panels (Providers, MCP, Prompts, Skills, Sessions, Usage) inside the app, or read the in-repo user manual and README for feature details.
Install / integrate:
# macOS (Homebrew)
brew install --cask cc-switch
# Linux (Arch, via AUR helper)
paru -S cc-switch-bin
Windows users and other Linux distributions can download MSI, portable ZIP, DEB, or RPM packages from the Releases page.
Contribute:
pnpm install
pnpm dev # start development mode with hot reload
pnpm typecheck # TypeScript validation
pnpm format:check # formatting check
pnpm test:unit # frontend unit tests
cargo fmt && cargo clippy && cargo test # Rust backend checks
Discuss feature proposals via GitHub issues first; pull requests are expected to pass type checking, formatting, and unit tests before submission.
7. Project Structure
cc-switch/
โโโ src/ # React + TypeScript frontend (UI, panels, state)
โโโ src-tauri/ # Rust + Tauri backend (IPC commands, proxy, SQLite access)
โโโ package.json # Frontend dependencies and pnpm scripts
โโโ README.md # Feature overview and setup instructions
The frontend (React 18, Vite, TailwindCSS, shadcn/ui) communicates with the Rust/Tauri backend over IPC; the backend owns the SQLite database at ~/.cc-switch/cc-switch.db, which acts as the single source of truth for providers, MCP servers, prompts, and skills.
8. Related Ecosystem
CC Switch integrates with and sits alongside the AI coding tools it manages: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes, as well as the Model Context Protocol (MCP) ecosystem for external tool servers. It depends on the Tauri framework for native desktop packaging and on cloud storage providers (Dropbox, OneDrive, iCloud, WebDAV) for cross-device sync.
9. License
- โ Use, modify, and distribute the software commercially or privately (MIT License)
- โ Include it in proprietary projects without needing to open-source your own code
- โ Hold the authors liable for damages arising from use of the software
- โน๏ธ The original copyright notice and license text must be retained in copies or substantial portions of the software
10. FAQ
Q: Which AI coding tools does CC Switch support?
A: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes.
Q: Do I need to restart my terminal after switching providers?
A: Most tools require restarting the CLI to pick up new configuration, but Claude Code supports hot-switching without a restart.
Q: Where is my configuration data stored?
A: In a local SQLite database and JSON settings files under ~/.cc-switch/, with automatic backup rotation.
Q: Can I keep using my official Claude/Codex login instead of a third-party provider?
A: Yes โ add the "Official Login" preset to return to the tool's default authentication.
Q: How do I install CC Switch on Windows or Linux distributions without a package manager?
A: Download the MSI, portable ZIP, DEB, RPM, or AppImage build from the Releases page.
11. Quick Links
- Repository: https://github.com/farion1231/cc-switch
- Official website: https://ccswitch.io
- Releases: https://github.com/farion1231/cc-switch/releases
- Issues (bug reports & feature discussion): https://github.com/farion1231/cc-switch/issues
12. Summary
CC Switch solves a real pain point for developers juggling multiple AI coding assistants: instead of hand-editing config files across eight different tools, it offers one native, cross-platform interface for providers, MCP servers, prompts, skills, and usage tracking, backed by a resilient local proxy and cross-device sync. It's most valuable for developers and teams who regularly switch between AI providers or use more than one coding assistant, and want that setup to be reliable, backed up, and consistent everywhere they work.