Claude Code Router: what the open-source project does, how to set it up, and the caveats

What is Claude Code Router?

Claude Code Router, usually shortened to CCR, is an open-source project at github.com/musistudio/claude-code-router. Its README describes it as a local model gateway and control plane for coding agents: one local endpoint that agents talk to, with the providers, models, accounts and routing rules managed in one place behind it.

The name is easy to misread. It is not an Anthropic product and it is not part of Claude Code. It is a separate project that Claude Code can be pointed at. The project is MIT-licensed and, according to the GitHub API on October 30, 2026, had roughly 38,000 stars and was created in February 2025.

It has also changed shape. Older tutorials describe a small tool driven by a hand-edited config.json. The current README presents a desktop app and a browser-based management UI, supports many agents beyond Claude Code (Codex, OpenCode, Kilo Code and others), and the project’s own docs say the legacy config.json is now only a migration source. If a tutorial and the README disagree, follow the README.

Is Claude Code Router official, and does Anthropic support it?

No. Anthropic’s documentation on other LLM gateways is direct about this category of tool:

That has three practical meanings. If you send Claude Code to Anthropic’s models through CCR, you are using a supported pattern with an unsupported product. If you send it to a non-Claude model, the setup is outside what Anthropic supports at all. And in both cases, a problem that appears is a problem to take to the CCR project, not to Anthropic.

For teams that want a gateway with official backing, Claude Code ships its own: Claude apps gateway, included in the claude binary, with single sign-on and OpenTelemetry usage metrics. The gateway overview explains how to choose between it and a product you already run.

How does Claude Code Router work?

Claude Code can send its API traffic somewhere other than Anthropic by setting the ANTHROPIC_BASE_URL environment variable. A gateway receives those requests, which use the Anthropic Messages format (/v1/messages), and forwards them to a provider. CCR is a gateway of that kind that can also translate between formats.

The README lists the protocols and providers CCR supports: OpenAI Chat and Responses, Anthropic Messages, Gemini, OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI, Bailian and custom compatible endpoints. It lists these capabilities:

• Routing: conditions on headers and bodies, prefixes, request rewrites, retries and ordered fallback models.
• Credentials: single keys and credential pools, with key rotation.
• Added capabilities: a Fusion feature for vision and web search on existing models, MCP tools and a ToolHub.
• Access limits: separate CCR client keys, with expiry and local request, token and image limits.
• Observability: request and response details, latency, token counts and estimated cost.

In short, CCR is a translator and a switchboard. The gateway also has a management side: a desktop app, or a browser UI that the CLI serves on http://127.0.0.1:3458 by default. The management token and the client keys are separate credentials: one protects the UI, the other authenticates model requests.

How do you install and set up Claude Code Router?

Follow the project’s own instructions, because they change. As of the README in October 2026, there are three ways to run it:

The README’s quick start is the same in every distribution:

1. Open Providers → Add Provider. Choose a preset or a custom endpoint, enter the provider’s API key, select the protocol and the models, and save.
2. Create a CCR client key on the API Keys page.
3. Open Server and click Start. The gateway listens on http://127.0.0.1:3456 by default.
4. Open Agent Config, choose Claude Code, select a model, and apply the profile.
5. Start Claude Code, then open Logs in CCR to confirm the resolved provider, model, status, tokens, latency and any errors.

With the npm CLI you can launch a configured profile from a terminal: ccr <profile-name-or-id> [cli|app] [-- <agent arguments>]. For example, ccr "Claude - Review" cli -- --model sonnet starts the profile with the agent’s own arguments after the double dash. Only enabled profiles can be launched, and most need the gateway running.

How does Claude Code connect to any gateway without a helper app?

Claude Code’s gateway connection page documents the manual route. You set the base URL and one credential variable. The docs use ANTHROPIC_AUTH_TOKEN for a bearer token, ANTHROPIC_API_KEY for an x-api-key header, and apiKeyHelper for credentials that rotate. Their advice is to start with shell exports, check that it works, and only then move the values into a settings file.

export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
export ANTHROPIC_AUTH_TOKEN=<your gateway client key>
claude

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:3456"
$env:ANTHROPIC_AUTH_TOKEN = "<your gateway client key>"
claude

Whether CCR expects a bearer token or an API key header is a question for its own docs. The Claude Code docs say that if you are not told which kind of credential a gateway wants, start with ANTHROPIC_AUTH_TOKEN and use the verification request to see whether you need to switch. The Claude Code docs also say that setting only the base URL, with no credential variable, does not replace your subscription: requests still route through the gateway, but a saved claude.ai login stays the active credential. Editors launched from a dock or Start menu do not see shell exports, so the VS Code extension needs its settings configured separately.

What are the caveats of using Claude Code Router?

One more point follows from how a gateway works. A prompt that leaves your machine goes to whichever provider CCR chose, so a routing rule that sends your code to a provider you have not vetted is a data decision, not just a cost decision.

When does a router make sense, and when not?

A simple order of operations: get comfortable with plain Claude Code and its plan limits, understand the usage limits and the models it offers, and only then decide that a gateway solves a problem you actually have.

What should you check before pointing Claude Code at a router?

1. Who runs the router? Is it only on 127.0.0.1, or reachable by others?
2. Which provider receives my prompts and code? Have I read its data terms?
3. Which credential does Claude Code send, and who gets billed?
4. Does /status show the base URL I expect?
5. Does one test prompt show up in the router’s logs with the right model?
6. Does a multi-file edit with tools work, not just a chat reply?
7. Do I need Remote Control, a subscription login or auto mode on this machine? (They may not work behind a custom base URL or with other models.)
8. How do I switch back? (Unset ANTHROPIC_BASE_URL and the credential variable, restart claude.)

The last item matters. Unsetting ANTHROPIC_BASE_URL returns Claude Code to its normal path. If you set the values in a settings file instead of your shell, remove them there too.

Whatever route you take, the tool is only a means. If you are looking for something to build with it, the board has ideas with ready build prompts, and Claude Code project ideas lists projects sized for a first session.