# CC Switch ### The All-in-One Manager for Claude Code, Codex, Gemini CLI, OpenCode & OpenClaw [![Version](https://img.shields.io/badge/version-3.11.1-blue.svg)](https://github.com/farion1231/cc-switch/releases) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/farion1231/cc-switch/releases) [![Built with Tauri](https://img.shields.io/badge/built%20with-Tauri%202-orange.svg)](https://tauri.app/) [![Downloads](https://img.shields.io/endpoint?url=https://api.pinstudios.net/api/badges/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest)

English | [中文](README_ZH.md) | [日本語](README_JA.md) | [Changelog](CHANGELOG.md)

## ❤️Sponsor

Click to collapse

[![MiniMax](assets/partners/banners/minimax-en.jpeg)](https://platform.minimax.io/subscribe/coding-plan?code=ClLhgxr2je&source=link) MiniMax-M2.5 is a SOTA large language model designed for real-world productivity. Trained in a diverse range of complex real-world digital working environments, M2.5 builds upon the coding expertise of M2.1 to extend into general office work, reaching fluency in generating and operating Word, Excel, and Powerpoint files, context switching between diverse software environments, and working across different agent and human teams. Scoring 80.2% on SWE-Bench Verified, 51.3% on Multi-SWE-Bench, and 76.3% on BrowseComp, M2.5 is also more token efficient than previous generations, having been trained to optimize its actions and output through planning. [Click](https://platform.minimax.io/subscribe/coding-plan?code=ClLhgxr2je&source=link) to get an exclusive 12% off the MiniMax Coding Plan! ---

	Thanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more. PackyCode provides special discounts for our software users: register using this link and enter the "cc-switch" promo code during first recharge to get 10% off.
	Thanks to AIGoCode for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The platform offers flexible subscription plans, zero risk of account suspension, direct access with no VPN required, and lightning-fast responses. AIGoCode has prepared a special benefit for CC Switch users: if you register via this link, you'll receive an extra 10% bonus credit on your first top-up!
	Thanks to AICodeMirror for sponsoring this project! AICodeMirror provides official high-stability relay services for Claude Code / Codex / Gemini CLI, with enterprise-grade concurrency, fast invoicing, and 24/7 dedicated technical support. Claude Code / Codex / Gemini official channels at 38% / 2% / 9% of original price, with extra discounts on top-ups! AICodeMirror offers special benefits for CC Switch users: register via this link to enjoy 20% off your first top-up, and enterprise customers can get up to 25% off!
	Thanks to Cubence for sponsoring this project! Cubence is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more with flexible billing options including pay-as-you-go and monthly plans. Cubence provides special discounts for CC Switch users: register using this link and enter the "CCSWITCH" promo code during recharge to get 10% off every top-up!
	Thanks to DMXAPI for sponsoring this project! DMXAPI provides global large model API services to 200+ enterprise users. One API key for all global models. Features include: instant invoicing, unlimited concurrency, starting from $0.15, 24/7 technical support. GPT/Claude/Gemini all at 32% off, domestic models 20-50% off, Claude Code exclusive models at 66% off! Register here
	Thanks to UCloud CompShare for sponsoring this project! CompShare is UCloud's AI cloud platform, providing stable and comprehensive domestic and international model APIs with just one key. Featuring cost-effective monthly and pay-as-you-go Coding Plan packages at 60-80% off official prices. Supports Claude Code, Codex, and API access. Enterprise-grade high concurrency, 24/7 technical support, and self-service invoicing. Users who register via this link will receive a free 5 CNY platform trial credit!
	Thank you to Right Code for sponsoring this project! Right Code reliably provides routing services for models such as Claude Code, Codex, and Gemini. It features a highly cost-effective Codex monthly subscription plan and supports quota rollovers—unused quota from one day can be carried over and used the next day. Invoices are available upon top-up. Enterprise and team users can receive dedicated one-on-one support. Right Code also offers an exclusive discount for CC Switch users: register via this link, and with every top-up you will receive pay-as-you-go credit equivalent to 25% of the amount paid.
	Thanks to AICoding.sh for sponsoring this project! AICoding.sh — Global AI Model API Relay Service at Unbeatable Prices! Claude Code at 19% of original price, GPT at just 1%! Trusted by hundreds of enterprises for cost-effective AI services. Supports Claude Code, GPT, Gemini and major domestic models, with enterprise-grade high concurrency, fast invoicing, and 24/7 dedicated technical support. CC Switch users who register via this link get 10% off their first top-up!
	Thanks to Crazyrouter for sponsoring this project! Crazyrouter is a high-performance AI API aggregation platform — one API key for 300+ models including Claude Code, Codex, Gemini CLI, and more. All models at 55% of official pricing with auto-failover, smart routing, and unlimited concurrency. Crazyrouter offers an exclusive deal for CC Switch users: register via this link to get $2 free credit instantly, plus enter promo code `CCSWITCH` on your first top-up for an extra 30% bonus credit!
	Thanks to SSSAiCode for sponsoring this project! SSSAiCode is a stable and reliable API relay service, dedicated to providing stable, reliable, and affordable Claude and Codex model services, offering high cost-effective official Claude service at just ¥0.5/$ equivalent, supporting monthly and pay-as-you-go billing plans with same-day fast invoicing. SSSAiCode offers a special deal for CC Switch users: register via this link to enjoy $10 extra credit on every top-up!

## Why CC Switch? Modern AI-powered coding relies on CLI tools like Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw — but each has its own configuration format. Switching API providers means manually editing JSON, TOML, or `.env` files, and there is no unified way to manage MCP and Skills across multiple tools. **CC Switch** gives you a single desktop app to manage all five CLI tools. Instead of editing config files by hand, you get a visual interface to import providers with one click, switch between them instantly, with 50+ built-in provider presets, unified MCP and Skills management, and system tray quick switching — all backed by a reliable SQLite database with atomic writes that protect your configs from corruption. - **One App, Five CLI Tools** — Manage Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw from a single interface - **No More Manual Editing** — 50+ provider presets including AWS Bedrock, NVIDIA NIM, and community relays; just pick and switch - **Unified MCP & Skills Management** — One panel to manage MCP servers and Skills across four apps with bidirectional sync - **System Tray Quick Switch** — Switch providers instantly from the tray menu, no need to open the full app - **Cloud Sync** — Sync provider data across devices via Dropbox, OneDrive, iCloud, or WebDAV servers - **Cross-Platform** — Native desktop app for Windows, macOS, and Linux, built with Tauri 2 - **Built-in Utilities** — Includes various utilities for first-launch login confirmation, signature bypass, plugin extension sync, and more ## Screenshots | Main Interface | Add Provider | | :-----------------------------------------------: | :--------------------------------------------: | | ![Main Interface](assets/screenshots/main-en.png) | ![Add Provider](assets/screenshots/add-en.png) | ## Features [Full Changelog](CHANGELOG.md) | [Release Notes](docs/release-notes/v3.11.1-en.md) ### Provider Management - **5 CLI tools, 50+ presets** — Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw; copy your key and import with one click - **Universal providers** — One config syncs to multiple apps (OpenCode, OpenClaw) - One-click switching, system tray quick access, drag-and-drop sorting, import/export ### Proxy & Failover - **Local proxy with hot-switching** — Format conversion, auto-failover, circuit breaker, provider health monitoring, and request rectifier - **App-level takeover** — Independently proxy Claude, Codex, or Gemini, down to individual providers ### MCP, Prompts & Skills - **Unified MCP panel** — Manage MCP servers across 4 apps with bidirectional sync and Deep Link import - **Prompts** — Markdown editor with cross-app sync (CLAUDE.md / AGENTS.md / GEMINI.md) and backfill protection - **Skills** — One-click install from GitHub repos or ZIP files, custom repository management, with symlink and file copy support ### Usage & Cost Tracking - **Usage dashboard** — Track spending, requests, and tokens with trend charts, detailed request logs, and custom per-model pricing ### Session Manager & Workspace - Browse, search, and restore conversation history across all apps - **Workspace editor** (OpenClaw) — Edit agent files (AGENTS.md, SOUL.md, etc.) with Markdown preview ### System & Platform - **Cloud sync** — Custom config directory (Dropbox, OneDrive, iCloud, NAS) and WebDAV server sync - **Deep Link** (`ccswitch://`) — Import providers, MCP servers, prompts, and skills via URL - Dark / Light / System theme, auto-launch, auto-updater, atomic writes, auto-backups, i18n (zh/en/ja) ## FAQ

Which AI CLI tools does CC Switch support?

CC Switch supports five tools: **Claude Code**, **Codex**, **Gemini CLI**, **OpenCode**, and **OpenClaw**. Each tool has dedicated provider presets and configuration management.

Do I need to restart the terminal after switching providers?

For most tools, yes — restart your terminal or the CLI tool for changes to take effect. The exception is **Claude Code**, which currently supports hot-switching of provider data without a restart.

My plugin configuration disappeared after switching providers — what happened?

CC Switch provides a "Shared Config Snippet" feature to pass common data (beyond API keys and endpoints) between providers. Go to "Edit Provider" → "Shared Config Panel" → click "Extract from Current Provider" to save all common data. When creating a new provider, check "Write Shared Config" (enabled by default) to include plugin data in the new provider. All your configuration items are preserved in the default provider imported when you first launched the app.

macOS shows "unidentified developer" warning — how do I fix it?

The author doesn't have an Apple Developer account yet (registration in progress). Close the warning, then go to **System Settings → Privacy & Security → Open Anyway**. After that, the app will open normally.

Why can't I delete the currently active provider?

CC Switch follows a "minimal intrusion" design principle — even if you uninstall the app, your CLI tools will continue to work normally. The system always keeps one active configuration, because deleting all configurations would make the corresponding CLI tool unusable. If you rarely use a specific CLI tool, you can hide it in Settings. To switch back to official login, see the next question.

How do I switch back to official login?

Add an official provider from the preset list. After switching to it, run the Log out / Log in flow, and then you can freely switch between the official provider and third-party providers. Codex supports switching between different official providers, making it easy to switch between multiple Plus or Team accounts.

Where is my data stored?

- **Database**: `~/.cc-switch/cc-switch.db` (SQLite — providers, MCP, prompts, skills) - **Local settings**: `~/.cc-switch/settings.json` (device-level UI preferences) - **Backups**: `~/.cc-switch/backups/` (auto-rotated, keeps 10 most recent) - **Skills**: `~/.cc-switch/skills/` (symlinked to corresponding apps by default)

## Documentation For detailed guides on every feature, check out the **[User Manual](docs/user-manual/en/README.md)** — covering provider management, MCP/Prompts/Skills, proxy & failover, and more. ## Quick Start ### Basic Usage 1. **Add Provider**: Click "Add Provider" → Choose a preset or create custom configuration 2. **Switch Provider**: - Main UI: Select provider → Click "Enable" - System Tray: Click provider name directly (instant effect) 3. **Takes Effect**: Restart your terminal or the corresponding CLI tool to apply changes (Claude Code does not require a restart) 4. **Back to Official**: Add an "Official Login" preset, restart the CLI tool, then follow its login/OAuth flow ### MCP, Prompts, Skills & Sessions - **MCP**: Click the "MCP" button → Add servers via templates or custom config → Toggle per-app sync - **Prompts**: Click "Prompts" → Create presets with Markdown editor → Activate to sync to live files - **Skills**: Click "Skills" → Browse GitHub repos → One-click install to all apps - **Sessions**: Click "Sessions" → Browse, search, and restore conversation history across all apps > **Note**: On first launch, you can manually import existing CLI tool configs as the default provider. ## Download & Installation ### System Requirements - **Windows**: Windows 10 and above - **macOS**: macOS 10.15 (Catalina) and above - **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ and other mainstream distributions ### Windows Users Download the latest `CC-Switch-v{version}-Windows.msi` installer or `CC-Switch-v{version}-Windows-Portable.zip` portable version from the [Releases](../../releases) page. ### macOS Users **Method 1: Install via Homebrew (Recommended)** ```bash brew tap farion1231/ccswitch brew install --cask cc-switch ``` Update: ```bash brew upgrade --cask cc-switch ``` **Method 2: Manual Download** Download `CC-Switch-v{version}-macOS.zip` from the [Releases](../../releases) page and extract to use. > **Note**: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it first, then go to "System Settings" → "Privacy & Security" → click "Open Anyway", and you'll be able to open it normally afterwards. ### Arch Linux Users **Install via paru (Recommended)** ```bash paru -S cc-switch-bin ``` ### Linux Users Download the latest Linux build from the [Releases](../../releases) page: - `CC-Switch-v{version}-Linux.deb` (Debian/Ubuntu) - `CC-Switch-v{version}-Linux.rpm` (Fedora/RHEL/openSUSE) - `CC-Switch-v{version}-Linux.AppImage` (Universal) - `CC-Switch-v{version}-Linux.flatpak` (Flatpak) Flatpak install & run: ```bash flatpak install --user ./CC-Switch-v{version}-Linux.flatpak flatpak run com.ccswitch.desktop ```

Architecture Overview

### Design Principles ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend (React + TS) │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Components │ │ Hooks │ │ TanStack Query │ │ │ │ (UI) │──│ (Bus. Logic) │──│ (Cache/Sync) │ │ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ └────────────────────────┬────────────────────────────────────┘ │ Tauri IPC ┌────────────────────────▼────────────────────────────────────┐ │ Backend (Tauri + Rust) │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Commands │ │ Services │ │ Models/Config │ │ │ │ (API Layer) │──│ (Bus. Layer) │──│ (Data) │ │ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **Core Design Patterns** - **SSOT** (Single Source of Truth): All data stored in `~/.cc-switch/cc-switch.db` (SQLite) - **Dual-layer Storage**: SQLite for syncable data, JSON for device-level settings - **Dual-way Sync**: Write to live files on switch, backfill from live when editing active provider - **Atomic Writes**: Temp file + rename pattern prevents config corruption - **Concurrency Safe**: Mutex-protected database connection avoids race conditions - **Layered Architecture**: Clear separation (Commands → Services → DAO → Database) **Key Components** - **ProviderService**: Provider CRUD, switching, backfill, sorting - **McpService**: MCP server management, import/export, live file sync - **ProxyService**: Local proxy mode with hot-switching and format conversion - **SessionManager**: Claude Code conversation history browsing - **ConfigService**: Config import/export, backup rotation - **SpeedtestService**: API endpoint latency measurement

Development Guide

### Environment Requirements - Node.js 18+ - pnpm 8+ - Rust 1.85+ - Tauri CLI 2.8+ ### Development Commands ```bash # Install dependencies pnpm install # Dev mode (hot reload) pnpm dev # Type check pnpm typecheck # Format code pnpm format # Check code format pnpm format:check # Run frontend unit tests pnpm test:unit # Run tests in watch mode (recommended for development) pnpm test:unit:watch # Build application pnpm build # Build debug version pnpm tauri build --debug ``` ### Rust Backend Development ```bash cd src-tauri # Format Rust code cargo fmt # Run clippy checks cargo clippy # Run backend tests cargo test # Run specific tests cargo test test_name # Run tests with test-hooks feature cargo test --features test-hooks ``` ### Testing Guide **Frontend Testing**: - Uses **vitest** as test framework - Uses **MSW (Mock Service Worker)** to mock Tauri API calls - Uses **@testing-library/react** for component testing **Running Tests**: ```bash # Run all tests pnpm test:unit # Watch mode (auto re-run) pnpm test:unit:watch # With coverage report pnpm test:unit --coverage ``` ### Tech Stack **Frontend**: React 18 · TypeScript · Vite · TailwindCSS 3.4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit **Backend**: Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-updater/process/dialog/store/log **Testing**: vitest · MSW · @testing-library/react

Project Structure

``` ├── src/ # Frontend (React + TypeScript) │ ├── components/ │ │ ├── providers/ # Provider management │ │ ├── mcp/ # MCP panel │ │ ├── prompts/ # Prompts management │ │ ├── skills/ # Skills management │ │ ├── sessions/ # Session Manager │ │ ├── proxy/ # Proxy mode panel │ │ ├── openclaw/ # OpenClaw config panels │ │ ├── settings/ # Settings (Terminal/Backup/About) │ │ ├── deeplink/ # Deep Link import │ │ ├── env/ # Environment variable management │ │ ├── universal/ # Cross-app configuration │ │ ├── usage/ # Usage statistics │ │ └── ui/ # shadcn/ui component library │ ├── hooks/ # Custom hooks (business logic) │ ├── lib/ │ │ ├── api/ # Tauri API wrapper (type-safe) │ │ └── query/ # TanStack Query config │ ├── locales/ # Translations (zh/en/ja) │ ├── config/ # Presets (providers/mcp) │ └── types/ # TypeScript definitions ├── src-tauri/ # Backend (Rust) │ └── src/ │ ├── commands/ # Tauri command layer (by domain) │ ├── services/ # Business logic layer │ ├── database/ # SQLite DAO layer │ ├── proxy/ # Proxy module │ ├── session_manager/ # Session management │ ├── deeplink/ # Deep Link handling │ └── mcp/ # MCP sync module ├── tests/ # Frontend tests └── assets/ # Screenshots & partner resources ```

## Contributing Issues and suggestions are welcome! Before submitting PRs, please ensure: - Pass type check: `pnpm typecheck` - Pass format check: `pnpm format:check` - Pass unit tests: `pnpm test:unit` For new features, please open an issue for discussion before submitting a PR. PRs for features that are not a good fit for the project may be closed. ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=farion1231/cc-switch&type=Date)](https://www.star-history.com/#farion1231/cc-switch&Date) ## License MIT © Jason Young