What Claude Code Router is and how to use it

The short answer: Claude Code Router (CCR) sits between Claude Code (or a similar coding agent) and the model APIs, and routes each request to the provider and model you configured. With CCR, you keep Claude Code’s workflow as-is while the model answering behind it can be OpenRouter, DeepSeek, Gemini, a local model, or a different model per task type. In other words, it keeps you from being stuck on a single backend.

This post explains what CCR is, when you need it, how to think about its configuration, and how to verify that routing actually works. Options and commands change over time, so treat the CCR GitHub repository README and the official Claude Code docs as the source of truth for exact values.

What exactly is Claude Code Router?

In one line: a local proxy between Claude Code and model APIs that decides which provider and model should handle each request, and translates the request format when needed.

Claude Code normally sends requests in the Anthropic API format. CCR runs a local server and connects Claude Code to it instead of to Anthropic directly. CCR then does two things with each request:

  • Routing: it decides which provider and model should receive the request. You can assign different models for default work, background tasks, long contexts, and reasoning-heavy (“think”) requests.
  • Transformation: providers differ in API format and supported parameters, so transformers convert the Anthropic-style request into something each provider accepts.

That way Claude Code still reads files, runs commands, and edits code the same way, while a different model generates the responses. Keep in mind that CCR is an open-source community project, not an official Anthropic product.

When do you need CCR?

In one line: when one model or one billing path is not enough.

CCR is worth considering if any of these apply:

  • You want to mix models: routine edits go to a cheap, fast model, while hard design or debugging work goes to a strong reasoning model.
  • You want OpenRouter or other providers: you already have OpenRouter, DeepSeek, or Gemini keys and want to drive Claude Code’s agent loop with those models.
  • You want to tune cost and latency: sending background requests, where speed and price matter more than quality, to a lighter model reduces overall cost and wait time.
  • Some tasks need long context: requests beyond a certain context length can be sent to a model that supports it.
  • You want to include local models: a local server such as Ollama can be registered as a provider for a subset of requests.

If you only use Claude models through a single Anthropic subscription or API key and it works fine, you do not need CCR. Adding a layer in the middle also adds more places to check when something breaks.

How should you think about the basic setup?

In one line: register providers, list models, define routing rules, run Claude Code through CCR, and confirm with logs.

Installation and run commands are in the README. Typically you install CCR globally via npm and launch Claude Code through it with ccr code. After changing settings, run ccr restart so the service picks them up; depending on the version, ccr ui also lets you edit the config in a browser. Install commands and flags can change between versions, so copy them from the README rather than from memory.

The config file (~/.claude-code-router/config.json per the README) is easiest to understand in two parts.

1. Providers: which backends are available

Each provider entry has a name, the API endpoint URL, an API key, the list of model IDs you want to use from that provider, and any transformer it needs. For OpenRouter, for example, you would set OpenRouter’s API URL and key, list OpenRouter model IDs, and specify the OpenRouter transformer.

The key point is to write model IDs exactly as the provider uses them. A human-friendly model name, or an ID from a different provider, will make requests fail.

2. Router: which requests go where

The Router section assigns a “provider name, model ID” pair to each request type. The README lists entries such as default, background, think, and longContext. Conceptually:

  • default: the model most requests go to
  • background: a cheap model for light, repetitive helper requests
  • think: a model for planning- or reasoning-heavy requests
  • longContext: a model for requests whose context has grown large

You do not have to fill everything in on day one. Start with only default, confirm it works, and split out other routes as you need them. That makes problems much easier to isolate.

How should you pick models?

Claude Code constantly uses tool calls to read files, run commands, and edit code. So the first thing to check is not benchmark scores but whether the model reliably supports tool use. Plenty of models chat fine and then stall once agent steps begin.

After that, weigh context length, price, and speed to decide what goes on default versus background. If you route through OpenRouter, the same model may be served by several provider endpoints, so check tool support on the model page as well.

How do you confirm the route actually works?

Saving the config is not the finish line. Check the following:

  1. Run ccr restart after changing the config.
  2. Enable logging in the config, launch Claude Code with ccr code, and send a short request.
  3. In the CCR logs, confirm which provider and model the request went to.
  4. If possible, cross-check the provider’s dashboard (for example, OpenRouter’s activity log) for the same request.

Getting a response does not tell you which model produced it. The real check is that the CCR logs and the provider’s usage records agree.

What are the common mistakes?

Wrong model ID mapping

This is the most common one. If the model ID in Router does not match the Providers model list, or differs from the provider’s actual ID in spelling, version, or prefix, you get a 404 or a “model not found” error. OpenRouter uses the provider/model format, so the prefix must match too. Copy model IDs from the provider’s model page instead of typing them from memory.

Auth environment variables not reaching CCR

You may have exported an API key in one shell while the CCR service runs in another shell or in the background and cannot see it. Check whether the key is written directly in the config or referenced from an environment variable, and whether that variable actually exists in the environment where CCR runs. Also make sure leftover Anthropic-related environment variables on the Claude Code side do not conflict with the CCR connection. After changing keys, run ccr restart again.

Assuming the IDE model picker is enough

Changing the model name in an editor or IDE extension’s model menu may not change CCR’s routing at all. Which model actually answers depends on CCR’s Router config and on whether Claude Code is running through CCR in the first place. If you launch Claude Code directly without CCR, no CCR config change will have any effect. The README also describes switching provider and model inside Claude Code with the /model command, but that only matters when Claude Code is running through CCR.

Editing the config without restarting

The file is updated, but the running CCR still holds the old config. If results look wrong, try ccr restart first.

Splitting too many routes at once

If default, background, think, and longContext all point to different providers from the start, it is hard to tell which path is failing. Add one route at a time.

For a concrete case where switching OpenRouter models causes stalls or empty responses, see this troubleshooting post on OpenRouter provider.only (in Korean).

Start here: a checklist

  • Decide whether you really need multiple models or another provider.
  • Install CCR following the CCR README.
  • Register just one provider in Providers, copying the API URL, key, and model IDs from the provider’s docs.
  • Confirm the chosen model supports tool use.
  • Set only default in Router.
  • Run ccr restart, then launch Claude Code with ccr code.
  • Use the logs and the provider’s usage records to confirm requests reach the intended model.
  • Only after that works, add background, think, and longContext one at a time.

If you are looking into a subscription path for Cursor or Claude Code, the Gamsgo hub (in Korean) is also available.