ccs-switch — Summary

One-liner: Multi-runtime CLI bridge and account manager that routes Claude Code tasks to the optimal AI coding agent (Claude, Codex, Factory Droid, Gemini, Ollama, and more) based on intelligent profile matching, with a web dashboard for usage analytics.

Identity

What It Does

CCS (Claude Code Switch) is a multi-provider AI coding agent router. Starting from a Docker Compose quickstart (dashboard on port 3000, CLIProxy on port 8317), it allows developers to route Claude Code tasks to different AI runtimes based on cost, capability, and workload type. A Claude Code skill (ccs-delegation) and command (ccs.md) are bundled to enable in-session routing from within a Claude Code conversation.

Key capabilities include:

• Multi-provider routing: Claude, Codex, Factory Droid, GLM, Ollama, OpenRouter, Kimi, Qwen, Kiro, local models
• CLIProxy: OAuth proxy with round-robin or fill-first account load balancing across multiple Claude accounts
• Web dashboard: Usage analytics, live auth monitor, session history on port 3000
• OpenAI-compatible proxy: ccs proxy start exposes a local Anthropic-compatible API endpoint
• Multiple binaries: ccs, ccs-droid/ccsd, ccs-codex/ccsx, ccsxp
• Browser automation: Built-in WebSearch fallback and browser automation capabilities

Scope

Mid-complexity platform tool. Includes CLI, web UI, Docker infrastructure, Claude Code plugin (1 command + 1 skill), and community integrations (OpenCode sync plugin by third party).

ccs-switch — Purpose & Workflow

Problem Solved

Developers using multiple AI coding agents (Claude Code, Codex, Factory Droid, Ollama) face three problems:

1. Context switching cost: Different CLIs, different configurations, different command syntax
2. Account management: Claude Pro accounts have rate limits; multiple accounts need round-robin load balancing
3. Cost optimization: Different tasks warrant different models (haiku for simple tasks, opus for complex reasoning)

CCS solves all three: a single CLI entry point, account pool management via CLIProxy, and intelligent profile-based task routing.

Deployment Model

# Quickstart via Docker Compose
docker compose up -d
# → Dashboard: http://localhost:3000
# → CLIProxy: http://localhost:8317

Or install the CLI directly:

npm install -g @kaitranntt/ccs

Workflow: Task Delegation from Claude Code

When a developer is in a Claude Code session and wants to delegate a task to a different agent:

Developer: /project:ccs <task description>
        ↓
ccs.md command invokes ccs-delegation skill
        ↓
ccs-delegation parses task + reads ~/.ccs/config.json
        ↓
Profile matching: cost/capability/workload type
        ↓
ccs CLI called with optimal profile + enhanced prompt
        ↓
Target agent (Codex, Droid, Ollama, etc.) executes task
        ↓
Result returned to Claude Code conversation

Workflow: CLIProxy Account Load Balancing

Claude Code session → CLIProxy (port 8317)
        ↓
Round-robin or fill-first across account pool
        ↓
Route to next available Claude account
        ↓
Response proxied back to Claude Code

Workflow: OpenAI-Compatible API Proxy

ccs proxy start                    # Start local proxy
eval "$(ccs proxy activate)"       # Set env vars
# Any OpenAI-compatible SDK now routes through CCS → Claude

Supported Providers

ccs-switch — Commands & Skills

Claude Code Commands

1 command shipped: ccs.md

Located at .claude/commands/ccs.md. This is a Claude Code slash command that delegates a task to the optimal AI agent via the ccs-delegation skill.

/project:ccs <task description>

Behavior: reads the task description, invokes the ccs-delegation skill to select the appropriate profile from ~/.ccs/config.json, enhances the prompt, and dispatches via the ccs CLI binary.

Claude Code Skills

1 skill shipped: ccs-delegation

Located at .claude/skills/ccs-delegation.md. This is a behavioral guidance skill that teaches Claude Code how to intelligently route tasks to the optimal CCS profile.

Key behaviors encoded in the skill:

• Parse task description for complexity signals (simple/complex/specialized)
• Read available profiles from ~/.ccs/config.json
• Select profile based on cost efficiency, capability match, and current workload
• Enhance the prompt with context appropriate for the target agent
• Execute via ccs --profile <name> "<enhanced prompt>"
• Return results to the Claude Code conversation

Configuration File

~/.ccs/config.json — defines the profile registry:

{
  "profiles": {
    "cheap": {
      "provider": "codex",
      "model": "gpt-4o-mini",
      "use_for": "simple tasks, formatting, documentation"
    },
    "powerful": {
      "provider": "claude",
      "model": "claude-opus-4",
      "use_for": "complex reasoning, architecture decisions"
    },
    "local": {
      "provider": "ollama",
      "model": "llama3",
      "use_for": "offline tasks, sensitive codebases"
    }
  }
}

CCS CLI Commands

# Core routing
ccs "<task>"                          # Route with default profile
ccs --profile <name> "<task>"         # Route with specific profile
ccs --agent codex "<task>"            # Route to specific agent type

# Binary aliases
ccsx "<task>"                         # Codex shorthand
ccsd "<task>"                         # Factory Droid shorthand

# Proxy management
ccs proxy start                       # Start OpenAI-compatible proxy
ccs proxy stop                        # Stop proxy
ccs proxy activate                    # Print env var export commands
eval "$(ccs proxy activate)"          # Activate proxy in current shell

# Account management
ccs accounts list                     # List configured accounts
ccs accounts add                      # Add new account
ccs accounts remove <id>              # Remove account

# Analytics
ccs usage                             # Usage summary
ccs usage --by-profile                # Usage by profile
ccs usage --by-day                    # Daily breakdown

ccs-switch — MCP & Tools

MCP Server

None shipped as a bundled MCP server. CCS integrates with Claude Code via the plugin system (command + skill), not MCP protocol.

CLIProxy (Port 8317)

The CLIProxy is not an MCP server — it is an OAuth proxy that:

• Manages a pool of Claude accounts
• Intercepts Claude Code's outbound API calls
• Routes to the next available account via round-robin or fill-first strategy
• Proxies responses back to Claude Code transparently

This is similar in concept to claude-overlay's multi-provider routing, but CCS's CLIProxy specifically manages multiple accounts of the same provider (multiple Claude accounts) for rate limit distribution.

OpenAI-Compatible Proxy

ccs proxy start exposes a local API endpoint that:

• Accepts OpenAI-format API calls
• Translates to Anthropic/Claude format
• Routes through CCS profile selection
• Returns OpenAI-format responses

This allows any OpenAI SDK-compatible tool to use Claude via CCS:

import openai
client = openai.OpenAI(base_url="http://localhost:8317/v1", api_key="any")
response = client.chat.completions.create(...)

Browser Automation

CCS ships WebSearch fallback and browser automation capabilities (details in the web UI context). These are accessible as features within routed agent sessions, not as standalone MCP tools.

Community Integration: OpenCode Sync

A third-party community plugin (JasonLandbridge/opencode-ccs-sync) synchronizes CCS configuration with OpenCode, allowing OpenCode users to benefit from CCS's account management and routing.

Related Project Credit

The README credits claude-code-router by musistudio as a related project. CCS and claude-code-router address similar routing problems from different angles.

Web Dashboard (Port 3000)

• Usage analytics: Token consumption by profile, provider, and day
• Live auth monitor: Real-time status of account pool health
• Session history: Past sessions with provider/model/token breakdown
• Tech stack: Vite + React + TypeScript (in ui/ directory)
• Deploy: Via Docker Compose (ghcr.io/kaitranntt/ccs:latest)

ccs-switch — Uniqueness

differs_from_seeds

CCS has no direct analog among the 11 seeds. Seeds focus on enhancing a single agent (Claude Code) with better prompts, skills, and workflows. CCS treats Claude Code as one agent in a portfolio and optimizes which agent handles each task.

Specifically:

• superpowers, BMAD-METHOD, spec-driver: enhance Claude Code from within — more skills, better prompts, structured workflows. All assume Claude Code is the only agent.
• taskmaster-ai: structured task management for Claude Code sessions, but all tasks run on Claude
• No seed includes multi-provider routing, account pool management, or cross-agent task delegation

The closest batch peer is claude-overlay (also routes model selection for Claude Code), but claude-overlay configures Claude Code's model provider while CCS routes entire tasks to external agent runtimes with their own CLIs. Claude-overlay is an infrastructure modifier; CCS is an orchestrator.

Positioning

• Primary differentiator: Multi-runtime task delegation. The only tool in the catalog that uses a Claude Code skill to intelligently route tasks to external agent runtimes (Codex, Factory Droid, Ollama, Kiro) based on cost/capability/sensitivity profiles.
• Secondary differentiator: Account pool management via CLIProxy. The only tool that explicitly addresses Claude rate limits by maintaining an OAuth-managed pool of multiple Claude accounts with round-robin/fill-first load balancing.
• Tertiary differentiator: OpenAI-compatible proxy shim. Any OpenAI SDK client routes through CCS, enabling legacy OpenAI-integrated tools to use Claude without code changes.
• Target user: Teams running sustained AI coding sessions who encounter rate limits, have cost optimization needs (cheap tasks don't need Claude Opus), or operate in environments with data residency requirements (local Ollama for sensitive repos).

Observable Failure Modes

1. Conversation context loss on delegation: When Claude Code delegates a task via /project:ccs, the target agent starts with a fresh context. If the task requires knowledge from earlier in the Claude Code conversation, the enhanced prompt must carry it — which depends on the skill's context-packing logic.
2. Docker dependency for full feature set: The web dashboard and CLIProxy require Docker Compose. Developers who prefer CLI-only setup get reduced functionality (no usage analytics UI, no OAuth pool).
3. Profile drift: As ~/.ccs/config.json accumulates profiles, the routing heuristics in ccs-delegation may become stale. There's no mechanism to validate that profile descriptions still reflect actual capability differences between providers.
4. OAuth token rotation: The CLIProxy holds OAuth tokens for multiple accounts. Token expiry handling and the security of the token storage are not documented.
5. 2,410 stars but v8.1.0: The high version number suggests rapid iteration. Breaking changes between versions may affect teams who pin to specific versions.

Most Surprising Finding

A community member independently built JasonLandbridge/opencode-ccs-sync to integrate CCS with OpenCode — a signal that CCS has ecosystem gravity beyond its own repository despite being primarily a TypeScript CLI package. This organic third-party integration suggests the account management and routing patterns are genuinely useful to developers working across multiple AI tool platforms.