Claude Code Router: Use Any Model with Claude Code

Claude Code is powerful, but it's locked to Anthropic's models. What if you want to use DeepSeek for cheap background tasks? Or Gemini for long context? Or run a local model via Ollama? Claude Code Router makes all of that possible.

//What is Claude Code Router?

Claude Code Router is a proxy that intercepts Claude Code requests and routes them to any model provider you configure. It sits between Claude Code and the API, letting you use DeepSeek, Gemini, OpenRouter, Ollama, or any OpenAI-compatible endpoint while keeping the Claude Code interface you're used to.

Why would you want this?

Cost savings. Use cheaper models like DeepSeek for routine tasks. Reserve expensive models for when you actually need them.

Model selection. Different models excel at different things. Use Gemini for long context. Use reasoning models for complex planning. Use local models for privacy.

Local models. Run Ollama or other local inference and route background tasks there. No API costs. No data leaving your machine.

Provider flexibility. Not locked into any single provider. Switch models on the fly based on the task.

//Key Features

Smart routing. Route requests based on task type. Background tasks go to one model. Thinking/planning goes to another. Long context requests go to a model that handles it well.

Multi-provider support. Works with OpenRouter, DeepSeek, Gemini, Ollama, Volcengine, SiliconFlow, and any OpenAI-compatible API.

Request transformers. Different providers have different API formats. Transformers adapt requests automatically so you don't have to think about it.

Dynamic switching. Change models mid-session with the /model command. No restart needed.

CLI management. The ccr model command gives you an interactive interface to manage providers and models without editing JSON.

GitHub Actions support. Run Claude Code in CI/CD with your choice of models.

//Installation

First, make sure you have Claude Code installed:

npm install -g @anthropic-ai/claude-code

Then install Claude Code Router:

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

Verify it's installed:

ccr --version

//Configuration

Claude Code Router uses a JSON config file at ~/.claude-code-router/config.json. Create the directory and file:

mkdir -p ~/.claude-code-router
touch ~/.claude-code-router/config.json

Here's a minimal config to get started:

{
  "Providers": [
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-your-deepseek-key",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": {
        "use": ["deepseek"]
      }
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat"
  }
}

Then start Claude Code through the router:

ccr code

That's it. Claude Code now uses DeepSeek instead of Claude.

Providers

Each provider needs:

• name: A unique identifier
• api_base_url: The chat completions endpoint
• api_key: Your API key for that provider
• models: List of available model names
• transformer: Optional. Adapts requests/responses for that provider's API format

Here's a more complete example with multiple providers:

{
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-xxx",
      "models": [
        "google/gemini-2.5-pro-preview",
        "anthropic/claude-sonnet-4",
        "deepseek/deepseek-chat"
      ],
      "transformer": {
        "use": ["openrouter"]
      }
    },
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-xxx",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": {
        "use": ["deepseek"]
      }
    },
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:latest"]
    },
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "sk-xxx",
      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
      "transformer": {
        "use": ["gemini"]
      }
    }
  ]
}

Router Rules

The Router section defines which model handles which type of request:

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

default: General requests. This is your workhorse model.

background: Background tasks like exploration and code search. Use a cheap or local model here.

think: Plan mode and reasoning-heavy tasks. A reasoning model like DeepSeek Reasoner works well.

longContext: Requests that exceed the longContextThreshold (default 60k tokens). Gemini handles long context well.

webSearch: Web search queries. Needs a model that supports it.

The format is provider_name,model_name.

Transformers

Different providers have different API formats. Transformers handle the conversion automatically.

Built-in transformers:

• deepseek: For DeepSeek API
• gemini: For Google Gemini API
• openrouter: For OpenRouter (can also specify provider routing)
• groq: For Groq API
• maxtoken: Sets a specific max_tokens value
• tooluse: Optimizes tool calling
• reasoning: Processes reasoning_content fields
• enhancetool: Adds error tolerance to tool calls

Apply transformers at the provider level:

{
  "name": "deepseek",
  "transformer": {
    "use": ["deepseek"]
  }
}

Or per-model for specific overrides:

{
  "name": "deepseek",
  "transformer": {
    "use": ["deepseek"],
    "deepseek-chat": {
      "use": ["tooluse"]
    }
  }
}

Pass options to transformers with nested arrays:

{
  "transformer": {
    "use": [
      ["maxtoken", { "max_tokens": 16384 }]
    ]
  }
}

//Common Setups

Here are some configurations that work well in practice.

Budget setup. Use DeepSeek for everything, fall back to a stronger model for complex tasks:

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "think": "openrouter,anthropic/claude-sonnet-4"
  }
}

DeepSeek is extremely cheap. Most tasks work fine. When you hit plan mode or need serious reasoning, it upgrades to Sonnet.

Local-first setup. Run background tasks locally with Ollama, use cloud for main tasks:

{
  "Router": {
    "default": "openrouter,anthropic/claude-sonnet-4",
    "background": "ollama,qwen2.5-coder:latest"
  }
}

Background exploration hits your local model. No API costs. No data leaving your machine. Main coding tasks still get a capable cloud model.

Best-of-breed setup. Different models for different strengths:

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "gemini,gemini-2.5-pro",
    "background": "ollama,qwen2.5-coder:latest"
  }
}

DeepSeek for general coding. DeepSeek Reasoner for planning. Gemini for huge context. Local model for cheap background work.

//Advanced Features

Dynamic model switching. Change models mid-session without restarting:

/model openrouter,anthropic/claude-sonnet-4

Useful when you need a specific model for one task.

CLI model management. The interactive CLI makes configuration easier:

ccr model

View current config, switch models, add providers, all without editing JSON manually.

UI mode. For a visual configuration experience:

ccr ui

Opens a web interface for editing your config.

Presets. Save and share configurations:

# Export your config as a preset
ccr preset export my-setup

# Install a preset
ccr preset install /path/to/preset

# List presets
ccr preset list

Custom router scripts. For complex routing logic, write a custom router:

{
  "CUSTOM_ROUTER_PATH": "~/.claude-code-router/custom-router.js"
}

module.exports = async function router(req, config) {
  const userMessage = req.body.messages.find(m => m.role === 'user')?.content;

  if (userMessage && userMessage.includes('explain')) {
    return 'openrouter,anthropic/claude-sonnet-4';
  }

  return null; // Fall back to default router
};

GitHub Actions. Run Claude Code in CI with your choice of models:

- name: Start Claude Code Router
  run: |
    nohup bunx @musistudio/claude-code-router start &

- name: Run Claude Code
  uses: anthropics/claude-code-action@beta
  env:
    ANTHROPIC_BASE_URL: http://localhost:3456
  with:
    anthropic_api_key: "any-string"

Set NON_INTERACTIVE_MODE: true in your config for CI environments.

//Tips

Start simple. Begin with one provider and the default route. Add complexity as you understand what works.

DeepSeek is really good. For the price, DeepSeek Chat handles most coding tasks surprisingly well. Start there for cost savings.

Use reasoning models for plan mode. DeepSeek Reasoner or similar thinking models make a noticeable difference in plan mode quality.

Local models for background. Ollama with a decent coder model handles exploration and search well. Saves money and keeps data local.

Check the logs. Enable logging in config to debug routing issues:

{
  "LOG": true,
  "LOG_LEVEL": "debug"
}

Logs go to ~/.claude-code-router/logs/.

Restart after config changes. Modified the config? Run ccr restart for changes to take effect.

Environment variables for secrets. Don't hardcode API keys. Use environment variable interpolation:

{
  "api_key": "$DEEPSEEK_API_KEY"
}

//Verdict

Claude Code Router unlocks the full potential of Claude Code by letting you use any model you want. The cost savings alone are worth it. DeepSeek for routine tasks instead of Claude? That's a 10x reduction in API costs for most work.

But it's not just about cost. Different models are genuinely better at different things. Gemini handles long context better. Reasoning models think more carefully. Local models keep data private.

Should you use it? If you're using Claude Code seriously and care about costs or model flexibility, yes. The setup takes 10 minutes. The config is straightforward. The benefits are immediate.

The project is open source and actively maintained. Check it out at github.com/musistudio/claude-code-router.

Now go save some money.