ROUTE THE MODEL LAYER

TL;DR — npm install -g @musistudio/claude-code-router, write a minimal ~/.claude-code-router/config.json, launch with ccr code instead of claude. Five minutes from zero to first routed turn.

▸ Install

# global install
npm install -g @musistudio/claude-code-router

# verify
ccr --version

▸ Config location

The config lives at ~/.claude-code-router/config.json (note: not ~/.config/ — common typo). Create the directory if it doesn't exist.

▸ A minimal config — DeepSeek for everything

{
  "LOG": false,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/v1/chat/completions",
      "api_key": "sk-...your-deepseek-key...",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": { "use": ["deepseek"] }
    }
  ],
  "Router": {
    "default":     "deepseek,deepseek-chat",
    "background":  "deepseek,deepseek-chat",
    "think":       "deepseek,deepseek-reasoner",
    "longContext": "deepseek,deepseek-chat",
    "webSearch":   "deepseek,deepseek-chat"
  }
}

▸ Launch — three paths

• ccr code — starts the router AND launches Claude Code in one go. The simplest path.
• ccr start then claude — run the proxy as a separate process, use the normal claude binary. Useful when several CC instances share one router.
• eval "$(ccr activate)" — exports ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, NO_PROXY into your shell. After this, any claude invocation in that shell uses the router until you exit.

▸ Verify it's working

# in another terminal, with CCR running
curl -s http://127.0.0.1:3456/health
# → {"ok":true}

# in your CC session
/cost
# → look at the model field; if it says "deepseek-chat" instead of an
#   Anthropic model name, you're routed.

▸ Other useful CLI commands

• ccr ui — web config editor at http://127.0.0.1:3456/ui. Easier than hand-editing JSON.
• ccr model — interactive model picker for the current session (overrides Router.default).
• ccr stop — kill the proxy.

TL;DR — CCRouter classifies every incoming request into one of six routes and maps the route to a provider+model. default is the fallback; the other five trigger on observable request features.

▸ The six routes — when each fires

▸ A multi-provider Router block

"Router": {
  "default":     "anthropic,claude-sonnet-4-6",
  "background":  "deepseek,deepseek-chat",
  "think":       "deepseek,deepseek-reasoner",
  "longContext": "gemini,gemini-2.5-pro",
  "longContextThreshold": 60000,
  "webSearch":   "openrouter,perplexity/sonar-pro",
  "image":       "anthropic,claude-sonnet-4-6"
}

Read it as a cascade: anything heavy/reasoning stays on premium models; routine and bulk work goes to the cheap path; long-context goes to the model with the biggest window.

▸ The longContextThreshold field

A numeric field on the Router object — the token count above which the longContext route fires. Default 60000. Drop it lower (40000) if you want to bias toward the long-context model earlier, raise it higher if Gemini calls are eating your budget on borderline-size requests.

▸ Provider config — anatomy

{
  "name": "gemini",                                       // unique slug
  "api_base_url": "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
  "api_key": "AIza...your-key...",
  "models": ["gemini-2.5-pro", "gemini-2.5-flash"],       // models you'll route to
  "transformer": { "use": ["gemini"] }                    // request/response adapter
}

The name field is what you reference in the Router block (e.g. "longContext": "gemini,gemini-2.5-pro" — the comma separates provider name from model name).

▸ Eleven built-in transformers

deepseek, gemini, openrouter, groq, maxtoken (cap output tokens), tooluse (rewrite tool calls), reasoning (handle reasoning_content), sampling (alter temperature/top_p), enhancetool, cleancache, vertex-gemini. Apply at the provider level via transformer.use, or scope to specific models via transformer.<model-name>.use.