claude-code-router

What you will run into

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.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

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).

Step by step

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.

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.

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.

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).

How to confirm it works

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

ccr --help

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

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".

Other environments

• Desktop: official releases provide AppImage/dmg/exe (not verified here — no display environment).
• Node version: >= 22 (verified requirement); older Node may warn about engines during npm install.
• Co-install with other env-setting tools: ruflo → judged possible-compatible (partially verified 2026-08-30: ruflo workspace settings.json env only sets CLAUDE_FLOW_*/CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, 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, not promoted to verified).
• With oh-my-claudecode / agent-governance-toolkit / deepcode: judged possible-compatible (write surfaces do not overlap).

Common scenarios (by user goal)

Scenarios are organized by "what you want to do", not by command surface; commands are the same verified ones from Step by step / How to confirm.

Scenario 1: Start the gateway + management UI

The base of multi-model routing: start the gateway (background process) first, then watch routing state in the management UI:

ccr start --no-open

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

Scenario 2: Launch a specific agent by profile (multi-model routing)

Run Codex or Claude Code with a chosen model/provider (the profile must be configured first):

ccr default-codex -- --model gpt-5-codex

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

Scenario 3: Stop the gateway / inspect the command surface

ccr stop

Expected output: gateway stopped

ccr --help

Expected output: ccr start / ccr ui / ccr serve / ccr stop / ccr <profile> [cli|app]

Data and directories

• Own config: ~/.claude-code-router/;
• Injected section: ~/.claude/settings.json (env: ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN etc.).

Uninstall & cleanup

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

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)

Dependency warnings

• 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).

FAQ

• 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.