Skip to content

Claude Code Router

What it is

Claude Code Router (CCR) is a proxy and routing layer for the Claude Code CLI. It intercepts API requests from Claude Code and redirects them to various LLM providers (OpenRouter, DeepSeek, Gemini, Ollama, etc.) based on user-defined rules.

What problem it solves

  • Cost Optimization: Redirects expensive Claude 3.5 Sonnet requests to cheaper alternatives like DeepSeek-V3 or local models for background tasks.
  • Regional Access: Enables users in regions where Anthropic is restricted to use Claude Code by proxying through other providers.
  • Model Flexibility: Allows mixing and matching models for different tasks (e.g., reasoning vs. coding) within the same Claude Code session.
  • Compatibility Smoothing: Uses a "Transformer" system to fix subtle differences between provider APIs (e.g., forcing tool usage or reasoning tags).

Where it fits in the stack

Router / Gateway. It sits between the agent (Claude Code) and the inference provider, acting as a programmable middleware.

Typical use cases

  • DeepSeek Integration: Using DeepSeek-V3 for coding and DeepSeek-R1 for "Plan Mode" at a fraction of the cost of Claude 3.5.
  • Local Dev Loop: Routing background tasks to a local Ollama instance (e.g., qwen2.5-coder) to save tokens.
  • Enterprise Proxying: Centralizing API key management and logging for teams using Claude Code via OpenRouter.

Strengths

  • Dynamic Switching: Change models on-the-fly using the /model command within Claude Code.
  • Transformer System: Built-in logic to enhance tool usage for models that struggle with instruction following (like DeepSeek).
  • Ease of Use: Includes a web UI (ccr ui) and an interactive CLI (ccr model) for configuration.
  • GitHub Actions Support: Built-in NON_INTERACTIVE_MODE for CI/CD workflows.
  • MCP Discovery: Integrated discovery of Model Context Protocol (MCP) tools and routing patterns.

Limitations

  • Latency: Adding a proxy layer introduces minor network overhead.
  • Complexity: Requires managing a configuration file and a local service.
  • Instruction Adherence: While transformers help, non-Claude models may still struggle with Claude Code's complex multi-step prompts.

When to use it

  • Use when you want to use Claude Code with cheaper models (e.g., DeepSeek) to save costs.
  • Use if you are in a region where direct access to Anthropic's API is restricted.
  • Use when you need to route different types of tasks (background vs. planning) to different LLM providers.

When not to use it

  • Not necessary if you have a Claude Code Max plan and don't mind the cost.
  • Not for users who prefer a zero-configuration setup, as it requires managing a proxy service.

Getting started

Installation

# Ensure Claude Code is installed
npm install -g @anthropic-ai/claude-code

# Install Claude Code Router
npm install -g @musistudio/claude-code-router

Basic Configuration

Start the service to generate the default config at ~/.claude-code-router/config.json: 

ccr start

Usage

To run Claude Code through the router: 

ccr code
Alternatively, use eval "$(ccr activate)" to set environment variables globally in your shell session, allowing you to use the standard claude command.

Advanced Routing Patterns

Agent-Native LLM Routing (YAML)

CCR supports advanced routing rules defined in rules.yaml that can trigger based on query intent or tool-use requirements.

rules:
  - name: "heavy-coding"
    if: "query.matches(/refactor|implement/)"
    then: "deepseek/deepseek-chat"
    transformer: "deepseek_v3_coding"
  - name: "mcp-routing"
    if: "tools.include('brave_search')"
    then: "google/gemini-2.0-flash-exp"

Fallback and Retry Strategies

Configure automatic fallback to a frontier model if the cheaper model fails or times out:

{
  "fallback_policy": {
    "enabled": true,
    "strategy": "ordered",
    "targets": ["deepseek/deepseek-chat", "anthropic/claude-3.5-sonnet"],
    "retry_on": [429, 503]
  }
}

Troubleshooting: Fixing Tool Usage

Many non-Claude models (like DeepSeek) may struggle with the complex tool-calling format expected by Claude Code.

Using the tooluse Transformer

If a model fails to call tools or returns malformed JSON, enable the tooluse transformer in your config: 

{
  "models": {
    "deepseek/deepseek-chat": {
      "transformers": ["tooluse", "inject_reasoning_reminder"]
    }
  }
}

Roadmap

The project maintains an active list of features and bug fixes on GitHub: - GitHub Issues - GitHub Discussions

Licensing and cost

  • Open Source: Yes (MIT)
  • Cost: Free (but you pay for the underlying LLM providers)
  • Self-hostable: Yes

Sources / References

Contribution Metadata

  • Last reviewed: 2026-05-17
  • Confidence: high