CC Switch UI

A browser-first provider manager and local routing service for Claude Code.

中文文档

CC Switch UI manages Claude Code providers, OAuth accounts, MCP servers, Skills, usage data, and a local protocol-converting proxy from one web interface. It is a Web/Rust fork of cc-switch, designed for headless machines and browser-based administration.

The admin API listens on 127.0.0.1 by default. Only use --host 0.0.0.0 on a trusted network and protect the admin token.

Contents

• How it works
• Features
• Supported providers
• Quick start
• Configuration and data
• Architecture
• Development
• Project scope

How it works

CC Switch UI keeps direct provider selection and local routing as two separate controls:

Changing the route target does not overwrite the selected direct provider. Stopping the local route restores a consistent direct configuration.

Features

• Provider management: maintained presets, custom compatible endpoints, endpoint detection, model discovery, and one-click switching.
• Local routing: Anthropic, OpenAI Chat, OpenAI Responses, and Gemini adapters; streaming conversion; circuit breaker; and failover queue.
• OAuth accounts: device-code flows and multi-account management for Codex and GitHub Copilot, including GHES support.
• MCP servers: CRUD, import, per-server enable/disable, and merge-safe synchronization to ~/.claude.json.
• Claude Code Skills: CRUD, collections, import, and synchronization from ~/.cc-switch/skills/ to ~/.claude/skills/.
• Usage monitoring: proxy request logs plus optional import of Claude Code session JSONL files, with source breakdown and trend charts.
• Live configuration: merge-only updates preserve unrelated fields in Claude Code configuration files.

Supported providers

The UI includes seven maintained presets and also accepts custom compatible endpoints.

To use OrcaRouter, create an account or obtain an API key through the project link, then select the built-in OrcaRouter preset. The preset can fetch the current model list from the service.

Custom providers can use anthropic, openai_chat, openai_responses, or Gemini-compatible protocols. For an unknown endpoint, use Detect endpoint type and Fetch models in the provider editor.

Quick start

1. Install on Linux or macOS

curl -fsSL https://raw.githubusercontent.com/huangbogeng/cc-switch-ui/main/install.sh | bash

The installer places the application under ~/.local/share/cc-switch-ui and keeps user data in ~/.cc-switch.

For other platforms, download a build from GitHub Releases or build from source.

2. Start the service

# Defaults: admin UI on 127.0.0.1:5007, local proxy on 15721
cc-switch-ui start

Open http://localhost:5007/ui and sign in with the admin token printed in the startup log.

Useful CLI commands:

cc-switch-ui status   # Check service health
cc-switch-ui doctor   # Diagnose installation, PATH, and permission issues
cc-switch-ui version  # Print the installed version
cc-switch-ui stop     # Stop the managed service

To listen beyond the local machine, opt in explicitly:

cc-switch-ui start --host 0.0.0.0 --port 5007 --proxy-port 15721

3. Add and switch a provider

1. Open Providers.
2. Choose a preset or create a custom provider.
3. Enter the required API key or complete OAuth authorization.
4. Save the provider and select Switch.

Claude Code immediately uses the selected direct provider.

4. Optional: enable the local route

1. In Providers, choose a Route Target in the Local Route panel.
2. Start the local route.

Claude Code now sends requests to the local proxy, which adapts and forwards them to the route target. Stop the route to return to direct configuration.

Configuration and data

Environment variables

The admin host and port can be changed with cc-switch-ui start --host ... --port .... CLI settings are persisted in ~/.cc-switch/cli.json.

Managed paths

Back up ~/.cc-switch before migrating or removing an installation. API keys and OAuth credentials are sensitive data.

Architecture

flowchart LR
    Browser[React Web UI] -->|REST /api| Server[Axum server]
    Server --> Core[cc-switch-lib]
    Core --> DB[(SQLite)]
    Core --> Config[Claude config files]
    Claude[Claude Code] -->|direct mode| Provider[Provider API]
    Claude -->|local route mode| Proxy[Local proxy]
    Proxy -->|adapt, stream, fail over| Provider

The Rust workspace contains three crates:

• cc-switch-cli: installation-facing command-line entry point and service lifecycle.
• cc-switch-server: REST API, OAuth callbacks, static UI hosting, and local proxy.
• cc-switch-lib: persistence, live configuration, MCP/Skills synchronization, and OAuth core logic.

The frontend lives in cc-switch-ui/ and is built with React, TypeScript, and Vite.

Development

Requirements: Node.js 24.15+, npm, and Rust 1.85+ (rust-toolchain.toml pins the project toolchain).

Run from source

# Terminal 1: backend API
cargo run -p cc-switch-server

# Terminal 2: frontend development server
cd cc-switch-ui
npm ci
npm run dev

For a production-style build served by the CLI:

cd cc-switch-ui
npm ci
npm run build
cd ..
cargo run -p cc-switch-cli -- start

Quality checks

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

cd cc-switch-ui
npm test
npm run lint
npm run build

Repository layout

cc-switch-cli/       CLI and service lifecycle
cc-switch-lib/       Shared domain logic and SQLite persistence
cc-switch-server/    REST API, OAuth handlers, and local proxy
cc-switch-ui/        React frontend
install.sh           Linux/macOS installer

Provider and proxy changes should keep protocol-specific behavior inside adapter boundaries, preserve switch/start/stop live-config consistency, and include tests for request, response, streaming, usage, and failure behavior where applicable.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting a change.

Project scope

Acknowledgements

CC Switch UI is built from the open-source cc-switch project. Thanks to its maintainers and contributors.

License

Licensed under the MIT License.

MCP and Skills sync safety

Saving or toggling a managed MCP server or skill applies the desired state to Claude Code. If the record is saved but syncing fails, the API reports saved: true; correct the reported cause and retry Sync. A sync can apply earlier skills before a later skill fails; retrying applies the remaining desired state.

Sync preserves MCP entries and skill directories that have not been imported or added to CC Switch. Disabling or deleting a managed skill moves its live directory into ~/.claude/skills/.cc-switch-backups/; replacements also preserve the previous installation there. Backups remain until manually removed. To restore one, disable the managed record, then copy its backup to the original skill directory. The source in ~/.cc-switch/skills/ is retained on deletion. Skill directories must be single directory names; symlinked managed directories or source contents are rejected rather than followed.

The Skills page can load and restore backups, including deleted skills. Existing disabled records stay disabled; deleted records are recreated and enabled. Recovery preserves both the selected history and the previous source files. Unchanged syncs no longer create duplicate backups, and detected external edits abort publication. See configuration protection and recovery for first-write snapshots and conflict-detection limits.