Claude Code Router: What It Is, How to Set It Up, and When You Need It

Claude Code Router (CCR) is an open-source local gateway that sits between Claude Code and the model providers you choose. Claude Code talks to one stable endpoint on your machine, and CCR forwards each request to DeepSeek, Gemini, OpenRouter, Moonshot, an OpenAI-compatible API or anything else you've configured, translating the format along the way.

The quick facts, checked against the GitHub repo on October 29, 2026:

• Licence: MIT
• Current version: 3.1.3, released October 9, 2026
• npm package: @musistudio/claude-code-router, command ccr, Node.js 22 or newer
• Default ports: model gateway on 127.0.0.1:3456, management UI on 127.0.0.1:3458
• Popularity: about 37,900 GitHub stars as of October 2026

One warning up front. Most Claude Code Router tutorials online describe v2, with a hand-edited config.json and a ccr code command. Version 3 is a desktop app and browser UI that stores configuration in SQLite, and ccr code is gone. This guide covers v3 and explains what changed.

What Claude Code Router does

Claude Code only speaks a few API formats. Anthropic's gateway protocol reference lists them: Anthropic Messages, Amazon Bedrock InvokeModel, and Google Cloud's Agent Platform rawPredict. Point Claude Code at an endpoint that speaks none of those, and it fails.

CCR closes that gap. It accepts Claude Code's Anthropic-format requests on a local port, picks a provider and model based on your rules, converts the request into whatever that provider expects, and converts the response back. The README lists OpenAI Chat and Responses, Anthropic Messages, Gemini, OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI, Bailian, and custom compatible providers.

Claude Code
     │
     ▼
Claude Code Router  127.0.0.1:3456
  profiles · routing rules · credentials · logs
     │
     ▼
the provider, model and account you selected

The project has also outgrown its name. CCR now manages profiles for Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode and other agents too. Its core features, per the README:

Do you need a router at all?

Often you don't. If your provider already exposes an Anthropic-compatible endpoint, Claude Code can talk to it directly with environment variables and no proxy. OpenRouter is the common example, and our guide to using OpenRouter in Claude Code walks through the three variables it takes.

A router earns its place when the direct route can't do the job:

If you only want one non-Anthropic model behind Claude Code and its provider speaks Anthropic's format, skip the router. If you're comparing hosted gateways instead of a local one, our roundup of OpenRouter alternatives covers the options.

How to set up Claude Code Router v3

Install Claude Code first. Then pick one of the two CCR distributions.

The desktop app is what the README recommends. Builds are on the GitHub releases page for Windows, Linux, macOS Apple Silicon and macOS Intel.

The npm CLI runs the same gateway with a browser-based UI and no Electron:

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

ccr ui starts a background service and opens the management UI. On a remote machine or over SSH, use ccr ui --no-open and open the printed URL yourself. The CLI reference warns that the URL contains a management token, so treat it like a password.

The setup flow

From there, the steps are the same in both versions:

1. Providers → Add Provider. Choose a preset or a custom endpoint, enter the API key, pick the protocol and the models.
2. API Keys. On the CLI, create a CCR client key. It authenticates model requests to the gateway and is separate from the management token.
3. Server → Start. The gateway listens on http://127.0.0.1:3456 by default.
4. Agent Config → Add profile → Claude Code. Name the profile, choose a default model, and optionally override the Fable, Opus, Sonnet and Haiku tiers.
5. Launch Claude Code through CCR, then open Logs to confirm which provider and model handled the request.

Step 5 is where v2 habits break. In v3 you launch a profile by name:

ccr "Claude Code - Work"
ccr "Claude Code - Work" cli -- --model sonnet

Arguments after -- go to Claude Code itself. Inside the session, /model lists the models CCR exposes.

Scope: only through CCR, or system-wide

Each Claude Code profile has an effect scope. "Only opened from CCR" leaves your normal claude command untouched. "System default" applies the profile to Claude Code everywhere, and CCR allows only one enabled system-default Claude Code profile.

The scope is the first thing to check when requests don't show up in the logs. CCR's Claude Code setup page says a Claude Code you open directly isn't affected unless the profile's scope is System default.

How routing works

Tier overrides

The simplest control is per tier. Claude Code picks a model per tier, and a CCR profile can map each one to a provider model. For example, you could run a strong model on Opus and a cheaper one on Haiku, which handles lighter background work. Leave a tier empty and Claude Code chooses it.

Subagent auto-routing

This is CCR's most distinctive feature. Per the routing docs, when you fill in a Description for models on the Models page, CCR injects that list into the descriptions of Claude Code's Agent and Task tools. When Claude Code spawns a subagent, it can pick a model from the list and tag the prompt. CCR strips the tag and routes that request to the tagged model.

The docs suggest writing descriptions around the work each model suits: one for fast code search and small edits, one for architecture analysis and risky reviews, one for reading long logs. If no model has a description, CCR doesn't inject anything. If you lean on Claude Code subagents, this is how you send each one to a model that fits its job.

Custom rules and fallbacks

The Routing page holds an ordered rule list. Each rule has a condition on a request header or body field, and one or more rewrites applied when it matches. Rules are checked in list order and the first enabled match wins, so order is priority. Fallback models and retries catch provider errors.

Coming from v2: config.json, ccr code and transformers

If you followed an older guide, here's what moved. The v2.0.0 README told you to write ~/.claude-code-router/config.json by hand. The two sections that mattered were Providers and Router:

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

Each provider named a transformer that adapted requests and responses to that provider's API. The Router block mapped scenarios such as default, background, think, longContext and webSearch to a provider,model pair. You then started Claude Code with ccr code.

In v3:

According to the configuration file docs, v3 reads a legacy config.json once, as a migration source, when no SQLite config exists. After that, editing config.json changes nothing. The docs also say not to edit config.sqlite directly while CCR is running. Use the UI, or export a backup from Settings.

What can go wrong with non-Claude models

A router makes other models reachable. It doesn't make them good at being Claude Code.

Anthropic doesn't support it. Its LLM gateway docs say Anthropic doesn't endorse, maintain or audit third-party gateways, and doesn't support routing Claude Code to non-Claude models through any gateway. When something breaks, the CCR issue tracker is your support channel.

Tool use is the weak point. Every file read, edit and shell command in Claude Code is a tool call. A model that writes good code in chat can still return malformed tool calls, loop, or stop early as an agent. Test a new model on a throwaway branch before trusting it with real work.

Some Claude Code features assume Claude. Features that depend on a Claude model or a claude.ai sign-in may be missing or degrade behind a gateway. Check the relevant Claude Code docs page when a feature disappears.

Billing moves too. Anthropic says that while a gateway credential is active, those requests don't count against a claude.ai subscription's usage limits. They're billed to whoever owns the credential the gateway forwards. With CCR, that's whichever account you configured behind each route.

Keep it local. The CLI docs say listening on 0.0.0.0 exposes the management UI to your network. If you need remote access, pair a fixed strong token with a firewall or private network and TLS from a trusted reverse proxy. Provider keys sit in CCR's local data directory, so protect that directory and its backups.

When the setup is the problem

A router is the right tool when you want fine control over which model does what. It's also several layers of configuration between you and the task. If you're spending more time on providers, profiles and logs than on the work itself, Taku takes a different approach: an AI-native desktop workspace where you mirror an AI setup someone already got working and run it, without reproducing their environment first. Taku is in Beta, and the Mac app is available now.

FAQ

What is Claude Code Router?

An open-source, MIT-licensed local gateway by musistudio. It gives Claude Code one local endpoint and routes each request to the provider and model you choose, converting between API formats so non-Anthropic providers work.

Is Claude Code Router free and open source?

The code is open source under the MIT licence. You still pay each model provider for the API usage you route to it.

How do I install Claude Code Router?

Download the desktop app from the GitHub releases page, or run npm install -g @musistudio/claude-code-router with Node.js 22 or newer, then ccr ui to open the management UI.

Does ccr code still work?

Not in v3. The CLI's help lists start, ui, serve, stop and ccr <profile-name-or-id>. Create a Claude Code profile under Agent Config and launch it by name.

Where is the Claude Code Router config file?

In v3 it's ~/.claude-code-router/config.sqlite on macOS and Linux, and %APPDATA%\claude-code-router\config.sqlite on Windows. A legacy config.json is only read once for migration.

Can I use any router with Claude Code?

Anthropic says any gateway that exposes a supported API format works, meaning Anthropic Messages, Bedrock or Google Cloud's Agent Platform format. Claude Code Router is one such gateway; hosted options like OpenRouter's Anthropic-compatible endpoint are another.

Does Anthropic support Claude Code Router?

No. Anthropic doesn't endorse or audit third-party gateways, and it doesn't support routing Claude Code to non-Claude models through any of them.