CC Switch

CC Switch is an all-in-one management desktop application for AI coding tools. It centralizes the configuration of multiple AI tools, allowing users to switch between different API providers (e.g., AWS Bedrock, NVIDIA NIM) without manually editing JSON, TOML, or .env files.

Supported AI Tools

CC Switch supports the following 8 tools:

• Claude Code
• Claude Desktop
• Codex
• Gemini CLI
• Grok Build
• OpenCode
• OpenClaw
• Hermes

Key Capabilities

• Provider Management: Import presets for 50+ providers and sync settings across multiple tools (e.g., one setting for Claude Code, Codex, and Gemini CLI).
• Unified MCP, Prompts & Skills: Manage MCP servers, Markdown-based prompts (supporting CLAUDE.md, AGENTS.md, GEMINI.md), and Skills (via GitHub or ZIP) in a single panel with bidirectional synchronization.
• Proxy & Failover: Hot-switch local proxies, implement automatic failover, circuit breakers, and provider health monitoring.
• Usage Tracking: Dashboard for tracking costs, request counts, and token usage across providers.
• Cloud Sync: Sync configuration via Dropbox, OneDrive, iCloud, or WebDAV.
• Deep Linking: Use ccswitch:// URLs to import providers, MCP servers, prompts, or skills with one click.

CC Switch is an all-in-one management desktop application for AI programming tools, including Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes.

It eliminates the need to manually edit JSON, TOML, or .env files by providing a visual interface to:

• Manage Providers: Switch between 50+ presets (including AWS Bedrock, NVIDIA NIM, and community proxies) with one click.
• Unified MCP, Prompts, and Skills: Manage Model Context Protocol (MCP) servers, Markdown-based prompts (syncing CLAUDE.md, AGENTS.md, GEMINI.md), and Skills (installing from GitHub or ZIP) across multiple tools.
• Proxy & Failover: Handle local proxy hot-swapping, automatic failover, and circuit breaking.
• Usage Tracking: Monitor costs, request counts, and token usage across different providers.
• Cloud Sync: Synchronize configuration via Dropbox, OneDrive, iCloud, or WebDAV.

Built with Tauri 2, it is a native desktop application supporting Windows, macOS, and Linux.

The Session Manager is designed to provide visual management for local session records from AI tools like Codex and Claude Code. Its primary purpose is to solve the problem of fragmented session history by allowing developers to discover, search, and quickly resume work in their preferred terminal environments.

Core Capabilities:

• Discovery & Indexing: Scans local data sources to generate a unified session list with metadata (ID, provider, last active time, project directory, and summary).
• Session Visualization: Provides a list view for browsing and a detailed view for inspecting message timelines (user, assistant, tool, etc.).
• Quick Recovery: Enables users to copy the exact CLI command needed to resume a session or copy the project directory for manual cd operations.
• Terminal Integration (macOS): Supports one-click resumption in macOS Terminal or kitty by automatically executing cd <projectDir> && <resumeCommand>.

Unified Codex session history is a feature in CC Switch (v3.16.x and later) that merges session history lists for Codex.

By default, Codex separates sessions into two distinct 'drawers' based on a model_provider tag:

• openai drawer: Contains sessions from your official subscription (ChatGPT login / OpenAI API key).
• custom drawer: Contains sessions from third-party providers managed by CC Switch.

Because the Codex resume/history list only shows sessions matching your currently active provider, switching between official and third-party providers makes sessions appear to 'disappear.'

Enabling this feature makes the official subscription run under the custom tag as well, merging both types of sessions into a single, unified history list. This does not change your authentication; you still use your official ChatGPT login, but the session's classification tag is changed to allow visibility in the shared list.

CC Switch operates in two distinct modes for Claude Desktop:

Direct Mode

• Requirement: The provider must expose a native Anthropic Messages API and accept Claude Desktop's three specific role IDs: claude-sonnet-*, claude-opus-*, and claude-haiku-*.
• Failure Condition: If the provider uses OpenAI, Gemini, or any model IDs outside these three specific roles (including legacy Claude IDs like claude-3-5-sonnet-...), Direct Mode will fail.
• Persistence: Once Claude Desktop restarts and loads the profile, CC Switch does not need to keep running.

Model Mapping Mode

• Requirement: Used when providers do not support the native Anthropic role IDs. You must enable Needs model mapping.
• Functionality: The Claude Desktop profile only stores safe Sonnet / Opus / Haiku role routes and display names. The actual upstream model names are kept in the CC Switch configuration and are mapped during request transit.
• Persistence: CC Switch must keep running, and Claude Desktop local routing must remain enabled.

Launch on Startup

Enable this to have CC Switch run automatically when your system starts. Implementation varies by OS:

• Windows: Uses the registry.
• macOS: Uses LaunchAgent.
• Linux: Uses XDG autostart.

Close Behavior

Determine what happens when you click the close button:

• Minimize to tray: Hides the window to the system tray (recommended for easy provider switching).
• Exit directly: Fully closes the application.

Lightweight Mode

Introduced in v3.13.0, Lightweight Mode is a tray-only state designed to minimize memory and CPU usage when the app is idle.

• How to enter: Right-click the tray icon and select Lightweight Mode. This destroys the main window to free up UI resources and memory.
• How to exit: Click Open Main Window from the tray menu, or trigger CC Switch via a deep link/relaunch. The window is rebuilt on demand.

CC Switch uses a layered architecture with a React frontend and a Tauri/Rust backend.

Core Design Patterns

• SSOT (Single Source of Truth): All data is centralized in ~/.cc-switch/cc-switch.db (SQLite).
• Two-Layer Storage: Synchronized data is stored in SQLite, while device-specific data is stored in JSON.
• Bidirectional Sync: When switching providers, settings are written to live files. When editing, changes are reverse-synced from the active provider.
• Atomic Writes: Uses a "temporary file + rename" pattern to prevent configuration corruption.
• Concurrency Safety: Database connections are protected by Mutex to prevent race conditions.

Key Backend Services

• ProviderService: CRUD, switching, backfilling, and sorting of providers.
• McpService: MCP server management, import/export, and live file synchronization.
• ProxyService: Hot-switching and format conversion for local Proxy mode.
• SessionManager: Browsing conversation histories across supported apps.
• ConfigService: Configuration import/export and backup rotation.
• SpeedtestService: Latency measurement for API endpoints.