CC Switch

The All-in-One Manager for Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw & Hermes Agent

友链：学AI，上L站！

English | 中文 | 日本語 | Deutsch | Changelog

• Skills: Click "Skills" → Browse GitHub repos → One-click install to supported apps
• Sessions: Click "Sessions" → Browse, search, and restore conversation history across supported session sources

Note: On first launch, you can manually import existing CLI tool configs as the default provider.

WebUI (LAN Remote Access)

The built-in WebUI server starts automatically with the app, letting you manage providers from any browser on the same network.

1. Access: Open http://127.0.0.1:15722/ in your browser (runs on the same machine by default)
2. LAN mode: Go to Settings → WebUI → switch to "LAN" binding (0.0.0.0) and set a Bearer token
3. Remote access: Open http://<your-ip>:15722/?token=<your-token> from any device on the LAN
4. Disable: Set environment variable CC_SWITCH_WEBUI=0 or toggle off in Settings → WebUI

Environment Variable	Default	Description
CC_SWITCH_WEBUI	1 (enabled)	Set to 0 to disable auto-start
CC_SWITCH_WEBUI_HOST	127.0.0.1	Bind address (0.0.0.0 for LAN)
CC_SWITCH_WEBUI_PORT	15722	HTTP port
CC_SWITCH_WEBUI_TOKEN	(none)	Bearer token (required for non-loopback)

Security: When binding to 0.0.0.0, a strong token is enforced. The server will refuse to start without one.

Download & Installation

System Requirements

• Windows: Windows 10 and above
• macOS: macOS 12 (Monterey) 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 page.

macOS Users

Method 1: Install via Homebrew (Recommended)

brew install --cask cc-switch

Update:

brew upgrade --cask cc-switch

Method 2: Manual Download

Download CC-Switch-v{version}-macOS.dmg (recommended) or .zip from the Releases page.

Note: CC Switch for macOS is code-signed and notarized by Apple. You can install and open it directly.

Arch Linux Users

Install via paru (Recommended)

paru -S cc-switch-bin

Linux Users

Download the latest Linux build from the 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)

Flatpak: Not included in official releases. You can build it yourself from the .deb — see flatpak/README.md for instructions.

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: Conversation history browsing across supported session sources
• 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

# 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

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:

# 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/zh-TW/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

License

MIT © Jason Young