Claude Code Router: Route Requests to Any Model

Claude Code Router is an open-source local proxy (musistudio/claude-code-router) that sits between Claude Code and any model provider. Claude Code sends each request to 127.0.0.1:3456 believing it's talking to Anthropic's API; the router rewrites and forwards it to whichever model you configured — DeepSeek, Gemini, OpenRouter's catalog, or a local Ollama model.

The pitch is obvious: keep the agent you like, swap the models underneath it, pay a fraction of the price. We run this site with Claude Code daily and spent two weeks pushing everything through it before settling on a hybrid setup. Below we cover how the proxy works, the five-minute setup, the routing rules that produce the real savings, and the trade-offs that sent our important work back to Anthropic models. New to the agent itself? Start with our pillar guide, What Is Claude Code?, then come back.

What is Claude Code Router and how does it work?

Claude Code doesn't hard-wire Anthropic's servers — it reads its API endpoint from the environment. That single design decision is the whole trick. When you launch a session with ccr code instead of claude, the router starts a small server on 127.0.0.1:3456 and boots Claude Code with its base URL pointed at that address. The agent behaves exactly as it always has; it just never notices the API on the other end isn't Anthropic.

From there, the router project does three jobs on every request:

1. Translation. Claude Code speaks Anthropic's Messages API. The router converts each call into the target provider's format — usually an OpenAI-compatible endpoint — and converts the response back, tool calls and streaming included.
2. Routing. A config file maps request types to models, so a cheap model can absorb the busywork while a strong one handles reasoning.
3. Switching. Inside a running session, /model provider,model-name swaps the active model without a restart — useful when a budget model paints itself into a corner.

That's the architecture. One binary, one config file, no cloud service in the middle.

Why route Claude Code to other models?

Two motives dominate, and they're both rational. The first is cost. Claude Code is a free download, but running it requires a paid Claude plan or API credits — Is Claude Code Free? breaks that down. On the API, Anthropic's current per-million-token rates look like this (full detail in our Claude API pricing guide):

Heavy agentic sessions burn tokens fast at those rates. DeepSeek costs a fraction of frontier pricing, OpenRouter rotates genuinely free models, and a local Ollama model has zero marginal cost. Published guides report cost cuts anywhere from 50% to 99% depending on routing strategy. Our own bill dropped by more than half in week one — hold that thought, because something else dropped with it.

The second motive is model choice. People hunting for Claude Code custom models usually want one specific thing: Gemini's context handling for giant files, DeepSeek's reasoning at commodity prices, or a fully offline model for code that can't leave the machine. The router is why Claude Code took off as a universal agent shell — you route Claude Code to other models without giving up the harness, the permissions system, or the workflow you've already built.

Claude Code Router setup in five minutes

Setup takes four commands and one config file. Here's the sequence we use:

Step 1: install both CLIs.

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

Step 2: create ~/.claude-code-router/config.json. Two blocks matter: Providers (where models come from) and Router (which model handles which request type). A minimal local-only example:

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:14b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen2.5-coder:14b",
    "background": "ollama,qwen2.5-coder:14b"
  }
}

Note that api_base_url is the full endpoint path, not just the host — the number-one setup mistake we see. Cloud providers follow the same shape: add DeepSeek, Gemini, or OpenRouter as entries with their OpenAI-compatible endpoints and real API keys. Recent releases import this JSON into an internal store on first run and add ccr ui, a web panel for editing it.

Step 3: launch with ccr code instead of claude. Everything else about the session — slash commands, permissions, hooks — works as documented in our Claude Code CLI documentation guide.

Step 4: after config edits, run ccr restart. The proxy loads configuration at startup, so a running router won't see new providers.

Routing rules: where the savings actually live

Here's the insight that separates a real cost strategy from blind model-swapping: Claude Code doesn't send one kind of request. It fires a constant stream of low-stakes calls — summarizing context, compacting history, titling sessions — alongside the occasional high-stakes reasoning request. Claude Code Router lets you split that traffic with five rules, plus an experimental image route:

The background rule is the single biggest lever. Those housekeeping calls don't need a frontier model, yet on a direct Anthropic connection they bill like everything else. Routing background traffic to a free or local model while keeping think on a serious model captures most of the savings with the least quality damage.

One clarification on longContext: below the 60,000-token threshold, requests keep flowing to whatever default names; only when a conversation crosses that line does traffic jump to the big-window model. If your budget default starts degrading on long sessions, tune longContextThreshold downward rather than swapping the model.

The trade-offs nobody puts in the README

We promised the other half of the story. Our bill fell, and so did first-try success on hard refactors — multi-file changes that Claude Opus 4.8 handled in one pass took a budget model three attempts and a manual cleanup. Claude Code Router moves cost around; it doesn't repeal the quality difference between models. Weigh both columns:

Three of those deserve plain words. First, this is a community project — Anthropic doesn't build, endorse, or support it, and if a routed session misbehaves you're debugging alone. Second, Claude Code leans heavily on tool and function calling, and that's exactly where cheaper models fail first; a model that can't emit clean tool calls turns an agent into a chatbot. Third, terms of service: Anthropic officially documents third-party access paths like Amazon Bedrock, Google Vertex AI, and enterprise LLM gateways, but a community proxy impersonating its API endpoint isn't one of them — and piping consumer-subscription credentials through any third-party proxy is explicitly off-limits. The router avoids that by using your own provider API keys, but read the current terms yourself before betting a business workflow on it.

A quieter cost also showed up in our testing: free OpenRouter models carry aggressive rate limits and queueing, which turns a snappy agent sluggish exactly when you're mid-flow. Free rarely means fast.

Where we landed: background traffic and throwaway experiments go through the router; anything we'd be embarrassed to ship goes to Anthropic models directly.

Safer alternatives before you install a proxy

If your real problem is cost rather than model curiosity, quieter fixes exist — and they keep you inside supported territory:

Claude Code's built-in switching is more flexible than most people realize — Anthropic's model configuration docs cover per-session models, environment variables, and fallback behavior, no proxy required. Dropping routine sessions from Opus to Sonnet or Haiku alone cuts spend several-fold at zero risk. Claude Haiku 4.5 in particular gets overlooked: at $1/$5 per million tokens it's official, fully supported, and cheaper than plenty of the third-party models people route to. And if you're weighing subscriptions against API billing, our Claude pricing guide runs the numbers across every tier.

The honest summary: Claude Code Router is a sharp tool for developers who understand what they're trading. It's the best answer we've found for free-tier experimentation and local-model privacy, a reasonable answer for slashing background-request costs, and the wrong answer for teams that need supported, predictable, frontier-quality output.

Claude pricing at a glance

For the full breakdown of every plan, see our how much Claude costs guide.