https://github.com/huangbogeng/cc-switch-ui
Using CC Switch on systems without a desktop environment, like Linux servers or cloud servers.
https://github.com/huangbogeng/cc-switch-ui
cc-switch claude-code web-ui
Last synced: 24 days ago
JSON representation
Using CC Switch on systems without a desktop environment, like Linux servers or cloud servers.
- Host: GitHub
- URL: https://github.com/huangbogeng/cc-switch-ui
- Owner: huangbogeng
- License: mit
- Created: 2026-04-28T07:18:48.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-07T03:09:02.000Z (28 days ago)
- Last Synced: 2026-05-07T04:19:15.879Z (28 days ago)
- Topics: cc-switch, claude-code, web-ui
- Language: Rust
- Homepage: https://github.com/huangbogeng/cc-switch-ui
- Size: 341 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# CC Switch UI
**Managing Claude Code Provider configurations has never been easier.**
[](https://github.com/huangbogeng/cc-switch-ui)
[](https://github.com/huangbogeng/cc-switch-ui)
[](LICENSE)
[**δΈζζζ‘£**](README_zh.md)
---
## π― What It Solves
Configuring API Providers for Claude Code traditionally requires manually editing JSON files, memorizing various API endpoints, and handling complex OAuth authorization flows.
**CC Switch Web allows you to manage all of this effortlessly within your browser:**
- **One-click Provider Switching:** Instantly switch between different model providers without ever touching a config file.
- **Built-in Presets:** Comes with 6 pre-configured popular providers (MiniMax, SiliconFlow, DeepSeek, OpenRouter, Gemini Native, Codex).
- **Dual Authentication Support:** Supports both API Key and OAuth authentication flows.
- **Real-time Live Sync:** Changes are immediately synchronized with your local Claude Code configuration and take effect instantly.
---
## π Project Status (2026-05-08)
- Backend crate rename completed: `cc-switch-web` -> `cc-switch-server`.
- Backend modularization Phase 0 and Phase 1 completed.
- Proxy streaming pipeline is now modularized under `cc-switch-server/src/proxy/streaming/`:
- `openai_chat.rs`
- `responses.rs`
- `common.rs`
- `tool_blocks.rs`
- `finalization.rs`
- Current focus: Phase 2 (`forwarder.rs` decomposition) while avoiding over-fragmented files.
---
## π Supported Providers
| Provider | Type | Auth Method | Description |
|----------|------|-------------|-------------|
| **MiniMax** | Official | API Key | MiniMax M2.7 Model |
| **SiliconFlow** | Aggregator | API Key | Supports various models |
| **DeepSeek** | Official | API Key | DeepSeek V4 Model |
| **OpenRouter** | Aggregator | API Key | 100+ Models available |
| **Gemini Native**| Google | API Key | Native Gemini API |
| **Codex** | OpenAI | OAuth | Proxied via local server |
---
## π Quick Start
### Easy Installation (Linux & macOS)
The easiest way to install CC Switch UI is using our installation script:
```bash
curl -fsSL https://raw.githubusercontent.com/huangbogeng/cc-switch-ui/main/install.sh | bash
```
After installation, simply run:
```bash
cc-switch-ui
```
The installer places the application under `~/.local/share/cc-switch-ui` by default. User data stays in `~/.cc-switch`, including the SQLite database.
### CLI Commands
`cc-switch-ui start` launches the backend server and serves frontend static assets (`/ui`) in one process (production mode).
```bash
# Start with defaults: 0.0.0.0:5007, proxy 15721
cc-switch-ui start
# Custom bind/proxy ports
cc-switch-ui start --host 127.0.0.1 --port 5007 --proxy-port 15721
# Health check
cc-switch-ui status
# Show version
cc-switch-ui version
# Diagnose installation/path/permission issues
cc-switch-ui doctor
```
### Build from Source
If you prefer to build from source:
```bash
# Build frontend assets first (required for /ui in production mode)
cd cc-switch-ui && npm ci && npm run build && cd ..
# Build and run CLI entrypoint
cargo build --release
cargo run -p cc-switch-cli -- start
```
### 2. Access the Web UI
Open your browser and navigate to: **http://localhost:5007/ui**
*(Note: An admin token is required for the first login, which can be found printed in your terminal startup logs.)*
### 3. Add a Provider
1. Go to the **Providers** page in the dashboard.
2. Select a preset or configure a custom endpoint.
3. Enter your API Key.
4. Click **Save** and switch to it.
Claude Code will immediately start using the new Provider you selected.
---
## β¨ Features
### π Provider Management
- 6 built-in Provider presets for quick setup.
- Support for custom Provider configurations.
- One-click switching with real-time configuration sync.
### π OAuth Authentication
- **Codex**: Forward OAuth requests securely via the local proxy.
- **GitHub Copilot**: OAuth authentication *(Currently in development)*.
### π Local Proxy Server
- Built-in local proxy service to handle Codex requests.
- Supports both HTTP and SOCKS5 proxy configurations.
- Handles streaming response format conversions seamlessly.
### β‘ Live Config
- Automatically writes configurations directly to Claude Code when switching Providers.
- Completely eliminates the need to manually edit config files.
---
## π Architecture
CC Switch UI is a pure Web architecture variant, separating the React frontend and Rust backend:
```mermaid
graph TD
%% Define Styles
classDef frontend fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#f8fafc
classDef backend fill:#1e1e1e,stroke:#f97316,stroke-width:2px,color:#f8fafc
classDef library fill:#27272a,stroke:#10b981,stroke-width:2px,color:#f8fafc
classDef ext fill:#172554,stroke:#6366f1,stroke-width:1px,color:#cbd5e1
%% Nodes
UI["π» Browser (React UI)
http://localhost:5007/ui"]:::frontend
subgraph CC_Switch_Web ["cc-switch-server (Rust + Axum)"]
API["π REST API
/api/*"]:::backend
OAuth["π OAuth Handler
codex / copilot"]:::backend
Proxy["π Local Proxy
:15721"]:::backend
end
subgraph CC_Switch_Lib ["cc-switch-lib (Rust Core)"]
DB[("ποΈ SQLite DB
rusqlite")]:::library
LiveConfig["β‘ Live Config
File Watcher"]:::library
OAuthCore["π OAuth Core
Token Mgt"]:::library
end
ClaudeCode["π€ Claude Code
CLI Tool"]:::ext
ProviderAPI["βοΈ Provider API
Anthropic/OpenAI/etc."]:::ext
%% Connections
UI -- "HTTP /api/*" --> API
UI -- "OAuth Redirects" --> OAuth
API -.-> DB
API -.-> LiveConfig
OAuth -.-> OAuthCore
Proxy -.-> OAuthCore
LiveConfig -- "Writes config.json" --> ClaudeCode
ClaudeCode -- "Sends Prompts" --> Proxy
Proxy -- "Forwards Requests" --> ProviderAPI
```
---
## βοΈ Configuration
| Environment Variable | Default Value | Description |
|----------------------|---------------|-------------|
| `CC_SWITCH_ADMIN_TOKEN` | *Auto-generated* | Admin password for Web UI |
| `CC_SWITCH_PROXY_PORT` | `15721` | Port for the local proxy server |
| `CC_SWITCH_TEST_HOME` | `-` | Home directory for testing purposes |
---
## π Development
### Frontend (React + TypeScript + Vite)
```bash
cd cc-switch-ui
pnpm install
pnpm dev # Start dev server on http://localhost:5173
pnpm build # Production build
pnpm lint # Run ESLint checks
```
### Backend (Rust + Axum)
```bash
cargo run -p cc-switch-server # Run backend server directly
cargo fmt && cargo clippy # Formatting and linting
cargo test # Run tests
```
### Project Structure
```text
cc-switch-ui/ # React frontend workspace
cc-switch-server/ # Axum HTTP server (Rust)
cc-switch-lib/ # Shared core library (Rust)
βββ src/
βββ database/ # SQLite persistence via rusqlite
βββ oauth/ # OAuth handling (Codex + Copilot)
βββ config.rs # Configuration management
βββ live.rs # Live Config synchronization
```
---
## π Differences from the Original cc-switch
This project is a fork of the excellent [cc-switch](https://github.com/farion1231/cc-switch). Here are the main differences:
| Feature | cc-switch (Original) | CC Switch UI (This Project) |
|---------|----------------------|------------------------------|
| **Deployment** | Tauri Desktop App | Pure Web Service |
| **System Tray** | Supported | Not Supported |
| **MCP Management**| Supported | *Planned* |
| **Cloud Sync** | Supported | Not Supported |
| **Core Focus** | Full feature set | Focused on Provider Management |
---
## π Acknowledgements
Built upon the excellent open-source project [cc-switch](https://github.com/farion1231/cc-switch).
---
## π License
This project is licensed under the [MIT License](LICENSE).