Claude Code Router (by musistudio, MIT, ~3.7k stars) is a local control plane: it routes requests from Claude Code / Codex and other agents to different models and providers, with unified management of API keys, model selection and request logs. It has two forms: a desktop app (GUI) and an npm CLI (ccr, only needs Node 22+, no Electron).

In one sentence: "dial-up" between multiple models/providers — one control panel manages model access for all agents.

Claude Code locks you into a single model. You want to switch models by scenario (one for coding, one for questions), or you have multiple providers to manage centrally — that is what claude-code-router (CCR) does: a local agent control plane with cross-model routing + provider management, launching different agents by profile (e.g. ccr default-codex -- --model gpt-5-codex). But it is not a blind install: after install it injects an env section into ~/.claude/settings.json (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN etc.), and uninstall needs manual cleanup; the first run shows No available models (do not panic — configure a provider).

When to use it:

• Routing across multiple models/providers instead of locking a single model;
• Managing per-scenario startup parameters with profiles;
• Wanting a local management UI (the gateway started by ccr ui / ccr start).

When not to use it: single model, single provider, no routing layer needed — the control plane itself injects env into ~/.claude/settings.json and may start background processes.

note: Verified path on this machine; use the npmmirror registry prefix on mainland networks

# Source: Trove detailed guide · verified 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g @musistudio/claude-code-router --no-audit --no-fund
ccr --help

Expected output: ccr usage (start/ui/serve/stop/profile routing)

One command confirms install, one confirms the gateway is manageable:

# Source: Trove detailed guide · verified 2026-08-28
ccr --help

Expected output: ccr start / ccr ui / ccr serve / ccr stop / ccr <profile> [cli|app] (full subcommand set)

# Source: Trove detailed guide · verified 2026-08-28
ccr stop

Expected output: gateway stopped (stopping cleanly = the gateway process is manageable)

• After starting the gateway: ccr start log shows the management UI address;
• After configuring a provider: launching an agent by profile no longer says "No available models".

It is a global npm CLI ccr. Subcommands: start (starts the gateway + management UI, a background process), ui, serve, stop, <profile> [cli|app] (launch a given agent with a profile). How routing works: it injects env pointing Claude Code's API at a local gateway, and the gateway forwards to the target model/provider by profile. So the injected section is the core mechanism — and also the residue you must clean manually on uninstall.

Key concepts:

• profile: a set of startup parameters/model routing config;
• injected section: the env written to ~/.claude/settings.json at install (ANTHROPIC_*);
• gateway: the local process started by ccr start (management UI address).

Where it writes: ~/.claude-code-router/ (own config) + ~/.claude/settings.json (injected env section, manually cleaned on uninstall).

• ~/.claude-code-router/: its own config (config.sqlite, generated and measured)
• ~/.claude/settings.json: routing env injection segment (confirmed by source audit: sets ANTHROPIC_* etc. env vars to implement routing)
• Runtime: ccr start/serve launches a gateway process (port binding)

Step 1: Install the CLI

Why: a global npm package, usable right after install. Mainland npm direct is slow, so use the npmmirror registry prefix. After install, ccr --help should show start/ui/serve/stop/profile routing.

# Source: Trove detailed guide · verified 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g @musistudio/claude-code-router --no-audit --no-fund
ccr --help

Expected output: ccr usage (start/ui/serve/stop/profile routing)

After install, confirm:

• ccr --help lists the full subcommand set;
• "No available models" on first run is normal (configure a provider first).

Stuck? How to recover:

• npm slow/timeout → make sure the command has the npm_config_registry=https://registry.npmmirror.com prefix;
• No available models → normal; configure at least one provider before use.

Step 2: Configure a provider + start the gateway

Why: configure a provider first (CLI or management UI), then ccr start --no-open starts the gateway (a background process; --no-open does not open the browser). The management UI address appears in the startup log.

# Source: Trove detailed guide · verified 2026-08-28
ccr start --no-open

Expected output: gateway startup status; browser management UI address (--no-open does not open the browser)

After install, confirm:

• the startup log shows the management UI address;
• ccr stop stops the gateway cleanly.

Stuck? How to recover:

• startup failed → confirm a provider is configured; check logs under ~/.claude-code-router/;
• port taken → stop first, then start, or check the occupying process.

Step 3: Launch a specific agent by profile

Why: a profile is a bundle of startup parameters — ccr default-codex -- --model gpt-5-codex starts Codex with the given profile (that profile must be configured first). This is the core cross-model routing usage.

# Source: Trove detailed guide · verified 2026-08-28
ccr default-codex -- --model gpt-5-codex

Expected output: launches Codex with the given profile (profile must be configured first)

After install, confirm:

• the target agent starts with the profile's model.

Stuck? How to recover:

• profile does not exist → configure the profile first (management UI or config file).

Same source as the tool-page matrix — 19 pairs total (2 measured compatible / 15 inferred possibly compatible / 2 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• Symptom: EBADENGINE: Node version does not satisfy engines
• Symptom: node: not found in WSL (npm comes from the Windows side)
• Symptom: first run No available models / gateway won't start
• Symptom: local model api_base_url misconfigured (Ollama etc.)
• Symptom: Docker deployment: port / volume / permissions
• Symptom: JSON / API config errors prevent the service from starting

Full four-part write-up (symptom → cause → fix → verification evidence): site docs

# Source: Trove detailed guide · verified 2026-08-28
npm rm -g @musistudio/claude-code-router || true; rm -rf ~/.claude-code-router

note: npm package uninstall + own config dir removed automatically; the settings.json injected section needs manual cleanup

# Source: Trove detailed guide · verified 2026-08-28
npm rm -g @musistudio/claude-code-router || true
rm -rf ~/.claude-code-router
command -v ccr >/dev/null 2>&1 && echo "残留: ccr 仍存在" || echo "claude-code-router removed: OK"

Expected output: claude-code-router removed: OK

Manual checklist (shared files, not auto-deleted):

• ~/.claude/settings.json: remove the env section injected by CCR (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN etc.) — keep the rest of the file
• Desktop installs: system uninstall (AppImage/dmg/exe)

• Runtime precheck (needs Node >= 22)
• Official npm CLI path (measured in this environment); China uses npmmirror prefix
• First run prompts No available models — configure at least one provider first; desktop build (release binary) not measured in this environment (no display)
• Each operation = one command block + expected output
• Control-plane tool: writes ~/.claude/settings.json (env injection); the injected segment must be removed manually on uninstall (uninstall section in guide.md has the checklist)

• Q: ccr --version has no version output? A: ccr's first run shows "No available models"; after configuring a provider it works; version info is in ccr --help or npm ls -g.
• Q: Conflict with ruflo if installed together? A: judged possible-compatible (partially verified 2026-08-30) — ruflo workspace settings.json env only sets CLAUDE_FLOW_* (no ANTHROPIC_*), this tool injects HOME settings.json env ANTHROPIC_* (after provider config); ccr gateway start/stop + ruflo doctor coexist fine. Injection chain not fully verified: after configuring a provider, confirm the injected section coexists with the workspace config.
• Q: Settings in ~/.claude/settings.json remain after uninstall? A: CCR's injected section must be deleted manually (see the uninstall checklist); it does not affect other config.
• Q: How to stop the gateway process? A: ccr stop; or kill the process.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.

• Version: [3.0.22, 3.0.22] locked (verified at collection).
• Environment: Node >= 22 (verified requirement); desktop release binaries need a display environment (not verified here).
• Network: npm via npmmirror prefix (verified mainland path).
• Write surface: ~/.claude-code-router/ + ~/.claude/settings.json (env injected section, manually cleaned on uninstall).
• Background process: ccr start starts a gateway process (ccr stop stops it).
• Co-install: with oh-my-claudecode / agent-governance-toolkit / deepcode judged possible-compatible; with ruflo judged possible-compatible (partially verified 2026-08-30: env fields/levels do not overlap — ruflo workspace CLAUDE_FLOW_* vs this tool HOME ANTHROPIC_*; injection chain not fully verified).

• Verified: local repro log (2026-08-28, npm install + ccr --help smoke).
• Not tested: provider configuration and gateway startup (first run needs a configured provider); desktop release binaries (no display environment).

Third-party tutorials are not individually verified; check against this page and official docs.

• 使用 claude code router + cc switch，在 claude code 中接入官方大模型以及第三方平台提供的聚合大模型 API ⚠ 与实测冲突，以 Trove 实测为准 [博客园 · 沄卿 · 2026-02-27]
  用 ccr 做本地代理，把聚合大模型 API（文中例：白山智算）接入 claude code；含 node 环境检查、安装、路由配置、与 cc-switch 配合切换
• Windows 中安装 claude-code + claude-code-router 接入英伟达模型（minimax-m2.5/glm4.7） [博客园 · 二月雪 · 2026-03-22]
  Windows 下 winget/npm 安装 ccr、配置 provider 接入英伟达模型；5 章节含安装方式对比与配置步骤