CCS - Claude Code Switch

The universal AI profile manager for Claude Code.

Run Claude, Gemini, GLM, and any Anthropic-compatible API - concurrently, without conflicts.

Features & Pricing | Documentation

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

npm install -g @kaitranntt/ccs

Alternative package managers

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

ccs config
# Opens http://localhost:3000

3. Configure Your Accounts

The dashboard provides visual management for all account types:

• Claude Accounts: Create isolated instances (work, personal, client)
• OAuth Providers: One-click auth for Gemini, Codex, Antigravity
• API Profiles: Configure GLM, Kimi with your keys
• Health Monitor: Real-time status across all profiles

Analytics (Light/Dark Theme)

API Profiles & OAuth Providers

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
Antigravity	OAuth	ccs agy	Alternative routing
GLM	API Key	ccs glm	Cost-optimized execution
Kimi	API Key	ccs kimi	Long-context, thinking mode

OAuth providers authenticate via browser on first run. Tokens are cached in ~/.ccs/cliproxy/auth/.

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.

Usage

Basic Commands

ccs           # Default Claude session
ccs agy       # Antigravity (OAuth)
ccs gemini    # Gemini (OAuth)
ccs glm       # GLM (API key)

Parallel Workflows

Run multiple terminals with different providers:

# 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: Review (Gemini)
ccs gemini "review the implementation for security issues"

Multi-Account Claude

Create isolated Claude instances for work/personal separation:

ccs auth create work

# Run concurrently in separate terminals
ccs work "implement feature"    # Terminal 1
ccs  "review code"              # Terminal 2 (personal account)

Maintenance

Health Check

ccs doctor

Verifies: Claude CLI, config files, symlinks, permissions.

Update

ccs update              # Update to latest
ccs update --force      # Force reinstall
ccs update --beta       # Install dev channel

Sync Shared Items

ccs sync

Re-creates symlinks for shared commands, skills, and settings.

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:

export CCS_CLAUDE_PATH="/path/to/claude"              # Unix
$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe"   # Windows

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.

Remote Proxy

Connect to a remote CLIProxyAPI server (Docker, Kubernetes, or another machine) instead of using the local binary.

Configuration

Configure via dashboard (Settings → Proxy tab) or ~/.ccs/config.yaml:

proxy:
  remote:
    enabled: true
    host: "192.168.1.100"        # Remote server hostname/IP
    port: 8317                    # Default CLIProxy port
    protocol: http                # http or https
    auth-token: ""                # Optional auth token
  fallback:
    enabled: true                 # Fallback to local if remote unreachable
    auto-start: true              # Auto-start local proxy on fallback
  local:
    port: 8317
    auto-start: true

CLI Flags

Override config for one-time use:

Flag	Description
--proxy-host <host>	Remote proxy hostname/IP
--proxy-port <port>	Proxy port (default: 8317)
--proxy-protocol <proto>	Protocol: http or https
--proxy-auth-token <token>	Auth token for remote proxy
--local-proxy	Force local mode, ignore remote config
--remote-only	Fail if remote unreachable (no fallback)

# One-time remote connection
ccs gemini --proxy-host 192.168.1.100 --proxy-port 8317

# Force local mode
ccs gemini --local-proxy

# Strict remote mode (no fallback)
ccs gemini --proxy-host remote.example.com --remote-only

Environment Variables

For CI/CD and automation:

Variable	Description
CCS_PROXY_HOST	Remote proxy hostname
CCS_PROXY_PORT	Proxy port
CCS_PROXY_PROTOCOL	Protocol (http/https)
CCS_PROXY_AUTH_TOKEN	Auth token
CCS_PROXY_FALLBACK_ENABLED	Enable local fallback (1/0)

# Docker example
export CCS_PROXY_HOST="cliproxy-container"
export CCS_PROXY_PORT="8317"
ccs gemini "implement feature"

Priority Resolution

Configuration sources are merged with this priority (highest first):

1. CLI flags — One-time overrides
2. Environment variables — CI/CD automation
3. config.yaml — Persistent settings
4. Defaults — Local mode, port 8317

WebSearch

Third-party profiles (Gemini, Codex, GLM, etc.) cannot use Anthropic's native WebSearch. CCS automatically configures MCP-based web search as a fallback.

How It Works

Profile Type	WebSearch Method
Claude (native)	Anthropic WebSearch API
OAuth providers	MCP web-search-prime (auto-configured)
API profiles	MCP web-search-prime (auto-configured)

Configuration

Configure via dashboard (Settings page) or ~/.ccs/config.yaml:

websearch:
  enabled: true                    # Enable/disable auto-config
  provider: auto                   # auto | web-search-prime | brave | tavily
  fallback: true                   # Enable fallback chain

Optional API Keys

For additional search providers, set environment variables:

export BRAVE_API_KEY="your-key"    # Free tier: 15k queries/month
export TAVILY_API_KEY="your-key"   # AI-optimized search (paid)

Note

web-search-prime works without API keys. Brave/Tavily are optional fallbacks.

See docs/websearch.md for detailed configuration and troubleshooting.

Documentation

Topic	Link
Installation	docs.ccs.kaitran.ca/getting-started/installation
Configuration	docs.ccs.kaitran.ca/getting-started/configuration
OAuth Providers	docs.ccs.kaitran.ca/providers/oauth-providers
Multi-Account Claude	docs.ccs.kaitran.ca/providers/claude-accounts
API Profiles	docs.ccs.kaitran.ca/providers/api-profiles
CLI Reference	docs.ccs.kaitran.ca/reference/cli-commands
Architecture	docs.ccs.kaitran.ca/reference/architecture
Troubleshooting	docs.ccs.kaitran.ca/reference/troubleshooting

Uninstall

npm uninstall -g @kaitranntt/ccs

Alternative package managers

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.

License

MIT License - see LICENSE.

---

ccs.kaitran.ca | Report Issues | Star on GitHub