https://github.com/kaitranntt/ccs
Switch between Claude accounts, Gemini, Copilot, OpenRouter (300+ models) via CLIProxyAPI OAuth proxy. Visual dashboard, remote proxy support, WebSearch fallback. Zero-config to production-ready.
https://github.com/kaitranntt/ccs
ai-gateway anthropic-api claude claude-code cli-tool cliproxyapi developer-productivity gemini github-copilot multi-account nodejs oauth openrouter profile-switching react-dashboard typescript websearch
Last synced: 4 days ago
JSON representation
Switch between Claude accounts, Gemini, Copilot, OpenRouter (300+ models) via CLIProxyAPI OAuth proxy. Visual dashboard, remote proxy support, WebSearch fallback. Zero-config to production-ready.
- Host: GitHub
- URL: https://github.com/kaitranntt/ccs
- Owner: kaitranntt
- License: mit
- Created: 2025-11-01T21:01:53.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-26T15:39:50.000Z (12 days ago)
- Last Synced: 2026-02-26T15:40:06.879Z (12 days ago)
- Topics: ai-gateway, anthropic-api, claude, claude-code, cli-tool, cliproxyapi, developer-productivity, gemini, github-copilot, multi-account, nodejs, oauth, openrouter, profile-switching, react-dashboard, typescript, websearch
- Language: TypeScript
- Homepage: https://ccs.kaitran.ca/
- Size: 13.6 MB
- Stars: 1,182
- Watchers: 7
- Forks: 99
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-AI-driven-development - CCS - Claude Code Switch - Switch between Claude Sonnet 4.5, GLM 4.6, and Kimi for Coding instantly. Stop hitting rate limits. Start optimizing costs. (Frameworks & Libraries / Copilot Extensions & Alternatives)
README
# CCS - Claude Code Switch
### The universal AI profile manager for Claude Code.
Run Claude, Gemini, GLM, and any Anthropic-compatible API - concurrently, without conflicts.
[](LICENSE)
[](https://www.npmjs.com/package/@kaitranntt/ccs)
[](https://claudekit.cc?ref=HMNKXOHN)
**[Features & Pricing](https://ccs.kaitran.ca)** | **[Documentation](https://docs.ccs.kaitran.ca)**
## The Three Pillars
| Capability | What It Does | Manage Via |
|------------|--------------|------------|
| **Multiple Claude Accounts** | Run work + personal Claude subs simultaneously | Dashboard |
| **OAuth Providers** | Gemini, Codex, Antigravity - zero API keys needed | Dashboard |
| **API Profiles** | GLM, Kimi, or any Anthropic-compatible API | Dashboard |
## Quick Start
### 1. Install
```bash
npm install -g @kaitranntt/ccs
```
Alternative package managers
```bash
yarn global add @kaitranntt/ccs # yarn
pnpm add -g @kaitranntt/ccs # pnpm (70% less disk space)
bun add -g @kaitranntt/ccs # bun (30x faster)
```
### 2. Open Dashboard
```bash
ccs config
# Opens http://localhost:3000
```
Dashboard updates hub: `http://localhost:3000/updates`
Want to run the dashboard in Docker? See `docker/README.md`.
### 3. Configure Your Accounts
The dashboard provides visual management for all account types:
- **Claude Accounts**: Isolation-first by default (work, personal, client), with explicit shared context opt-in
- **OAuth Providers**: One-click auth for Gemini, Codex, Antigravity, Kiro, Copilot
- **API Profiles**: Configure GLM, Kimi with your keys
- **Factory Droid**: Track Droid install location and BYOK settings health
- **Updates Center**: Track support rollouts (Droid target, CLIProxy provider changes, WebSearch integrations)
- **Health Monitor**: Real-time status across all profiles
**Analytics Dashboard**
**Live Auth Monitor**
**CLI Proxy API & Copilot Integration**
**WebSearch Fallback**
## Built-in Providers
| Provider | Auth Type | Command | Best For |
|----------|-----------|---------|----------|
| **Claude** | Subscription | `ccs` | Default, strategic planning |
| **Gemini** | OAuth | `ccs gemini` | Zero-config, fast iteration |
| **Codex** | OAuth | `ccs codex` | Code generation |
| **Copilot** | OAuth | `ccs copilot` or `ccs ghcp` | GitHub Copilot models |
| **Cursor IDE** | Local Token | `ccs cursor` | Cursor subscription models via local daemon |
| **Kiro** | OAuth (AWS default) | `ccs kiro` | AWS CodeWhisperer (Claude-powered) |
| **Antigravity** | OAuth | `ccs agy` | Alternative routing |
| **OpenRouter** | API Key | `ccs openrouter` | 300+ models, unified API |
| **Ollama** | Local | `ccs ollama` | Local open-source models, privacy |
| **Ollama Cloud** | API Key | `ccs ollama-cloud` | Cloud-hosted open-source models |
| **GLM** | API Key | `ccs glm` | Cost-optimized execution |
| **KM (Kimi API)** | API Key | `ccs km` | Long-context, thinking mode |
| **Kimi (OAuth)** | OAuth | `ccs kimi` | Device-code OAuth via CLIProxy |
| **Azure Foundry** | API Key | `ccs foundry` | Claude via Microsoft Azure |
| **Minimax** | API Key | `ccs mm` | M2 series, 1M context |
| **DeepSeek** | API Key | `ccs deepseek` | V3.2 and R1 reasoning |
| **Qwen** | API Key | `ccs qwen` | Alibaba Cloud, qwen3-coder |
**OpenRouter Integration** (v7.0.0): CCS v7.0.0 adds OpenRouter with interactive model picker, dynamic discovery, and tier mapping (opus/sonnet/haiku). Create via `ccs api create --preset openrouter` or dashboard.
**Ollama Integration**: Run local open-source models (qwen3-coder, gpt-oss:20b) with full privacy. Use `ccs api create --preset ollama` - requires [Ollama v0.14.0+](https://ollama.com) installed. For cloud models, use `ccs api create --preset ollama-cloud`.
**Azure Foundry**: Use `ccs api create --preset foundry` to set up Claude via Microsoft Azure AI Foundry. Requires Azure resource and API key from [ai.azure.com](https://ai.azure.com).
> **OAuth providers** authenticate via browser on first run. Tokens are cached in `~/.ccs/cliproxy/auth/`.
**Powered by:**
- [CLIProxyAPIPlus](https://github.com/router-for-me/CLIProxyAPIPlus) - Extended OAuth proxy with Kiro ([@fuko2935](https://github.com/fuko2935), [@Ravens2121](https://github.com/Ravens2121)) and Copilot ([@em4go](https://github.com/em4go)) support
- [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) - Core OAuth proxy for Gemini, Codex, Antigravity
- [copilot-api](https://github.com/ericc-ch/copilot-api) - GitHub Copilot API integration
> [!TIP]
> **Need more?** CCS supports **any Anthropic-compatible API**. Create custom profiles for self-hosted LLMs, enterprise gateways, or alternative providers. See [API Profiles documentation](https://docs.ccs.kaitran.ca/providers/api-profiles).
## Usage
### Basic Commands
```bash
ccs # Default Claude session
ccs gemini # Gemini (OAuth)
ccs codex # OpenAI Codex (OAuth)
ccs cursor # Cursor IDE integration (token import + local daemon)
ccs kiro # Kiro/AWS CodeWhisperer (OAuth)
ccs ghcp # GitHub Copilot (OAuth device flow)
ccs agy # Antigravity (OAuth)
ccs ollama # Local Ollama (no API key needed)
ccs glm # GLM (API key)
ccs km # Kimi API profile (API key)
```
### Droid Alias (`argv[0]` pattern)
By default, invoking CCS as `ccsd` auto-selects the Droid target:
```bash
ln -s "$(command -v ccs)" /usr/local/bin/ccsd
ccsd glm
```
Need additional alias names? Set `CCS_DROID_ALIASES` as a comma-separated list (for example: `CCS_DROID_ALIASES=ccs-droid,mydroid`).
For Factory BYOK compatibility, CCS also stores a per-profile Droid provider hint
(`CCS_DROID_PROVIDER`) using one of:
`anthropic`, `openai`, or `generic-chat-completion-api`.
If the hint is missing, CCS resolves provider from base URL/model at runtime.
CCS also persists Droid's active model selector in `~/.factory/settings.json`
(`model: custom:`). This avoids passing `-m` argv in interactive mode,
which Droid treats as queued prompt text.
CCS supports structural Droid command passthrough after profile selection:
```bash
ccsd codex exec --skip-permissions-unsafe "fix failing tests"
ccsd codex --skip-permissions-unsafe "fix failing tests" # auto-routed to: droid exec ...
ccsd codex -m custom:gpt-5.3-codex "fix failing tests" # short exec flags auto-routed too
```
If you pass exec-only flags without a prompt (for example `--skip-permissions-unsafe`),
Droid `exec` will return its native "No prompt provided" usage guidance.
If multiple reasoning flags are provided in Droid exec mode, CCS keeps the first
flag and warns about duplicates.
Dashboard parity: `ccs config` -> `Factory Droid`
### Per-Profile Target Defaults
You can pin a default target (`claude` or `droid`) per profile:
```bash
# API profile defaults to Droid
ccs api create myglm --preset glm --target droid
# CLIProxy variant defaults to Droid
ccs cliproxy create mycodex --provider codex --target droid
```
Built-in CLIProxy providers also work with Droid alias/target override:
```bash
ccsd codex
ccsd agy
ccs codex --target droid
ccsd codex exec --auto high "triage this bug report"
```
Dashboard parity:
- `ccs config` -> `API Profiles` -> set **Default Target**
- `ccs config` -> `CLIProxy` -> create/edit variant -> set **Default Target**
### Kiro Auth Methods
`ccs kiro --auth` defaults to AWS Builder ID Device OAuth (best support for AWS org accounts).
```bash
ccs kiro --auth --kiro-auth-method aws # AWS Builder ID device code (default)
ccs kiro --auth --kiro-auth-method aws-authcode # AWS Builder ID auth code
ccs kiro --auth --kiro-auth-method google # Google OAuth
ccs kiro --auth --kiro-auth-method github # Dashboard management OAuth flow
```
Dashboard parity: `ccs config` -> Accounts -> Add Kiro account -> choose `Auth Method`.
### Cursor IDE Quick Start
```bash
ccs cursor enable
ccs cursor auth
ccs cursor start
ccs cursor status
```
If auto-detect is unavailable:
```bash
ccs cursor auth --manual --token --machine-id
```
Defaults:
- Port: `20129`
- Ghost mode: enabled
- Dashboard page: `ccs config` -> `Cursor IDE`
Detailed guide: [`docs/cursor-integration.md`](./docs/cursor-integration.md)
### Parallel Workflows
Run multiple terminals with different providers:
> Delegation compatibility: when CCS spawns child Claude sessions, it strips the `CLAUDECODE` guard variable to avoid nested-session blocking in Claude Code v2.1.39+.
```bash
# Terminal 1: Planning (Claude Pro)
ccs work "design the authentication system"
# Terminal 2: Execution (GLM - cost optimized)
ccs glm "implement the user service from the plan"
# Terminal 3: Local testing (Ollama - offline, privacy)
ccs ollama "run tests and generate coverage report"
# Terminal 4: Review (Gemini)
ccs gemini "review the implementation for security issues"
```
### Multi-Account Claude
Create isolated Claude instances for work/personal separation:
```bash
ccs auth create work
# Run concurrently in separate terminals
ccs work "implement feature" # Terminal 1
ccs "review code" # Terminal 2 (personal account)
```
#### Account Context Modes (Isolation-First)
Account profiles are isolated by default.
| Mode | Default | Requirements |
|------|---------|--------------|
| `isolated` | Yes | No `context_group` required |
| `shared` | No (explicit opt-in) | Valid non-empty `context_group` |
Shared mode continuity depth:
- `standard` (default): shares project workspace context only
- `deeper` (advanced opt-in): additionally syncs `session-env`, `file-history`, `shell-snapshots`, `todos`
Opt in to shared context when needed:
```bash
# Share context with default group
ccs auth create backup --share-context
# Share context only within named group
ccs auth create backup2 --context-group sprint-a
# Advanced deeper continuity mode (requires shared mode)
ccs auth create backup3 --context-group sprint-a --deeper-continuity
```
Update existing accounts without recreating login:
1. Run `ccs config`
2. Open `Accounts`
3. Click the pencil icon in Actions and set `isolated` or `shared` mode + continuity depth
Shared mode metadata in `~/.ccs/config.yaml`:
```yaml
accounts:
work:
created: "2026-02-24T00:00:00.000Z"
last_used: null
context_mode: "shared"
context_group: "team-alpha"
continuity_mode: "standard"
```
`context_group` rules:
- lowercase letters, numbers, `_`, `-`
- must start with a letter
- max length `64`
- non-empty after normalization
- normalized by trim + lowercase + whitespace collapse (`" Team Alpha "` -> `"team-alpha"`)
Shared context with `standard` depth links project workspace data. `deeper` depth links additional continuity artifacts. Credentials remain isolated per account.
Alternative path for lower manual switching:
- Use CLIProxy Claude pool (`ccs cliproxy auth claude`) and manage pool behavior in `ccs config` -> `CLIProxy Plus`.
Technical details: [`docs/session-sharing-technical-analysis.md`](docs/session-sharing-technical-analysis.md)
## Maintenance
### Health Check
```bash
ccs doctor
```
Verifies: Claude CLI, config files, symlinks, permissions.
### Update
```bash
ccs update # Update to latest
ccs update --force # Force reinstall
ccs update --beta # Install dev channel
```
### CI Parity Gate (for contributors)
Before opening or updating a PR, run:
```bash
bun run validate:ci-parity
```
This mirrors CI behavior (build + validate + base-branch freshness check) and is also enforced by the local `pre-push` hook.
### Sync Shared Items
```bash
ccs sync
```
Re-creates symlinks for shared commands, skills, and settings.
### Quota Management
```bash
ccs cliproxy doctor # Check quota status for all agy accounts
ccs cliproxy quota # Show agy/claude/codex/gemini/ghcp quotas (Claude/Codex: 5h + weekly reset schedule)
```
**Auto-Failover**: When a managed account runs out of quota, CCS automatically switches to another account with remaining capacity. Shared GCP project accounts are excluded (pooled quota).
### CLIProxy Lifecycle
```bash
ccs cliproxy start # Start CLIProxy background service
ccs cliproxy status # Check running status
ccs cliproxy restart # Restart CLIProxy service
ccs cliproxy stop # Stop running CLIProxy service
```
## Configuration
CCS auto-creates config on install. Dashboard is the recommended way to manage settings.
**Config location**: `~/.ccs/config.yaml`
Custom Claude CLI path
If Claude CLI is installed in a non-standard location:
```bash
export CCS_CLAUDE_PATH="/path/to/claude" # Unix
$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows
```
CCS sanitizes child Claude spawn environments by stripping `CLAUDECODE` (case-insensitive) to prevent nested-session guard failures during delegation. `CCS_CLAUDE_PATH` is still respected after this sanitization step.
Windows symlink support
Enable Developer Mode for true symlinks:
1. **Settings** → **Privacy & Security** → **For developers**
2. Enable **Developer Mode**
3. Reinstall: `npm install -g @kaitranntt/ccs`
Without Developer Mode, CCS falls back to copying directories.
## WebSearch
Third-party profiles (Gemini, Codex, GLM, etc.) cannot use Anthropic's native WebSearch. CCS automatically provides web search via CLI tools with automatic fallback.
### How It Works
| Profile Type | WebSearch Method |
|--------------|------------------|
| Claude (native) | Anthropic WebSearch API |
| Third-party profiles | CLI Tool Fallback Chain |
### CLI Tool Fallback Chain
CCS intercepts WebSearch requests and routes them through available CLI tools:
| Priority | Tool | Auth | Install |
|----------|------|------|---------|
| 1st | Gemini CLI | OAuth (free) | `npm install -g @google/gemini-cli` |
| 2nd | OpenCode | OAuth (free) | `curl -fsSL https://opencode.ai/install \| bash` |
| 3rd | Grok CLI | API Key | `npm install -g @vibe-kit/grok-cli` |
### Configuration
Configure via dashboard (**Settings** page) or `~/.ccs/config.yaml`:
```yaml
websearch:
enabled: true # Enable/disable (default: true)
gemini:
enabled: true # Use Gemini CLI (default: true)
model: gemini-2.5-flash # Model to use
opencode:
enabled: true # Use OpenCode as fallback
grok:
enabled: false # Requires XAI_API_KEY
```
> [!TIP]
> **Gemini CLI** is recommended - free OAuth authentication with 1000 requests/day. Just run `gemini` once to authenticate via browser.
See [docs/websearch.md](./docs/websearch.md) for detailed configuration and troubleshooting.
## Remote CLIProxy
CCS v7.x supports connecting to remote CLIProxyAPI instances, enabling:
- **Team sharing**: One CLIProxyAPI server for multiple developers
- **Cost optimization**: Centralized API key management
- **Network isolation**: Keep API credentials on a secure server
### Quick Setup
Configure via dashboard (**Settings > CLIProxy Server**) or CLI flags:
```bash
ccs gemini --proxy-host 192.168.1.100 --proxy-port 8317
ccs codex --proxy-host proxy.example.com --proxy-protocol https
```
### CLI Flags
| Flag | Description |
|------|-------------|
| `--proxy-host` | Remote proxy hostname or IP |
| `--proxy-port` | Remote proxy port (default: 8317 for HTTP, 443 for HTTPS) |
| `--proxy-protocol` | `http` or `https` (default: http) |
| `--proxy-auth-token` | Bearer token for authentication |
| `--local-proxy` | Force local mode, ignore remote config |
| `--remote-only` | Fail if remote unreachable (no fallback) |
See [Remote Proxy documentation](https://docs.ccs.kaitran.ca/features/remote-proxy) for detailed setup.
## Documentation
| Topic | Link |
|-------|------|
| Installation | [docs.ccs.kaitran.ca/getting-started/installation](https://docs.ccs.kaitran.ca/getting-started/installation) |
| Configuration | [docs.ccs.kaitran.ca/getting-started/configuration](https://docs.ccs.kaitran.ca/getting-started/configuration) |
| OAuth Providers | [docs.ccs.kaitran.ca/providers/oauth-providers](https://docs.ccs.kaitran.ca/providers/oauth-providers) |
| Multi-Account Claude | [docs.ccs.kaitran.ca/providers/claude-accounts](https://docs.ccs.kaitran.ca/providers/claude-accounts) |
| API Profiles | [docs.ccs.kaitran.ca/providers/api-profiles](https://docs.ccs.kaitran.ca/providers/api-profiles) |
| Remote Proxy | [docs.ccs.kaitran.ca/features/remote-proxy](https://docs.ccs.kaitran.ca/features/remote-proxy) |
| Cursor IDE (local guide) | [./docs/cursor-integration.md](./docs/cursor-integration.md) |
| CLI Reference | [docs.ccs.kaitran.ca/reference/cli-commands](https://docs.ccs.kaitran.ca/reference/cli-commands) |
| Architecture | [docs.ccs.kaitran.ca/reference/architecture](https://docs.ccs.kaitran.ca/reference/architecture) |
| Troubleshooting | [docs.ccs.kaitran.ca/reference/troubleshooting](https://docs.ccs.kaitran.ca/reference/troubleshooting) |
## Uninstall
```bash
npm uninstall -g @kaitranntt/ccs
```
Alternative package managers
```bash
yarn global remove @kaitranntt/ccs
pnpm remove -g @kaitranntt/ccs
bun remove -g @kaitranntt/ccs
```
## Philosophy
- **YAGNI**: No features "just in case"
- **KISS**: Simple, focused implementation
- **DRY**: One source of truth (config)
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
MIT License - see [LICENSE](LICENSE).
## Star History
[](https://www.star-history.com/#kaitranntt/ccs&type=date&legend=top-left)
---
**[ccs.kaitran.ca](https://ccs.kaitran.ca)** | [Report Issues](https://github.com/kaitranntt/ccs/issues) | [Star on GitHub](https://github.com/kaitranntt/ccs)