The Three Pillars

Quick Start

1. Install

npm install -g @kaitranntt/ccs

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

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
• Language Switcher: Toggle dashboard locale between English, Simplified Chinese, and Vietnamese

Analytics Dashboard

Live Auth Monitor

CLI Proxy API & Copilot Integration

WebSearch Fallback

Built-in Providers

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.

Alibaba Coding Plan Integration: Configure via ccs api create --preset alibaba-coding-plan (or preset alias alibaba) with Coding Plan keys (sk-sp-...) and endpoint https://coding-intl.dashscope.aliyuncs.com/apps/anthropic.

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+ 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.

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

Powered by:

• CLIProxyAPIPlus - Extended OAuth proxy with Kiro (@fuko2935, @Ravens2121) and Copilot (@em4go) support
• CLIProxyAPI - Core OAuth proxy for Gemini, Codex, Antigravity
• 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.

Usage

Basic Commands

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 qwen      # Qwen Code (OAuth via CLIProxy)
ccs ollama    # Local Ollama (no API key needed)
ccs glm       # GLM (API key)
ccs km        # Kimi API profile (API key)
ccs api create --preset alibaba-coding-plan  # Alibaba Coding Plan profile

Droid Alias (argv[0] pattern)

By default, invoking CCS as ccsd auto-selects the Droid target:

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:<alias>). This avoids passing -m argv in interactive mode, which Droid treats as queued prompt text.

CCS supports structural Droid command passthrough after profile selection:

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:

# 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:

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).

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

ccs cursor enable
ccs cursor auth
ccs cursor start
ccs cursor status

If auto-detect is unavailable:

ccs cursor auth --manual --token <token> --machine-id <machine-id>

Defaults:

• Port: 20129
• Ghost mode: enabled
• Dashboard page: ccs config -> Cursor IDE

Detailed guide: 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+.

# 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:

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.

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:

# 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:

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.

Cross-Profile Continuity Inheritance (Claude Target)

You can map non-account profiles (API, CLIProxy, Copilot, or default) to reuse continuity artifacts from an account profile:

continuity:
  inherit_from_account:
    glm: pro
    gemini: pro
    copilot: pro

With this config, ccs glm, ccs gemini, and ccs copilot run with pro's CLAUDE_CONFIG_DIR continuity context while keeping each profile's own provider credentials/settings.

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

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

CI Parity Gate (for contributors)

Before opening or updating a PR, run:

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

ccs sync

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

Quota Management

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

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

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

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

CLI Tool Fallback Chain

CCS intercepts WebSearch requests and routes them through available CLI tools:

Configuration

Configure via dashboard (Settings page) or ~/.ccs/config.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 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:

ccs gemini --proxy-host 192.168.1.100 --proxy-port 8317
ccs codex --proxy-host proxy.example.com --proxy-protocol https

CLI Flags

See Remote Proxy documentation for detailed setup.

Documentation

Uninstall

npm uninstall -g @kaitranntt/ccs

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.