GitHub - musistudio/claude-code-router: Use Claude Code as the foundation for coding infrastructure, allowing you to decide how to interact with the model while enjoying updates from Anthropic.

musistudio · article · 2026-07-11 source ↗ Reader 🖥️

Agent Harness AI Unit Economics Capability Provisioning (right-sizing to the task)Claude Code Frontier Model Convergence / Commoditization Local AI Model Routing Open-Weight Models

Claude Code's harness should be decoupled from Anthropic's models: by running a local proxy that intercepts its API requests and routes each sub-task — background, thinking, long-context, web-search — to the cheapest capable model across many providers, with per-provider transformers normalizing each vendor's API dialect into Claude Code's Anthropic-shaped protocol, you keep Anthropic's coding harness and its updates while freely choosing, mixing, and cost-optimizing the model behind it.

practical · mixed — A tool README: how-to exposition (installation, config.json walkthroughs, transformer tables, CI recipes) wrapped around an argumentative spine — you SHOULD run Claude Code through a router that swaps the model per task. Its propositions serve 'you can/should do X', so it reads as a practical text with an implicit thesis rather than a neutral manual.

Structure

Part	Role
Features list (Model Routing, Multi-Provider, Transformers, Dynamic Switching, GitHub Actions, Plugins)	States the capability surface up front — the six things the tool claims to let you do.
Getting Started: install + config.json anatomy (PROXY_URL, APIKEY, HOST, Providers, Router)	Operationalizes the claim — shows the proxy sits between Claude Code and the model endpoints and is driven by a single config file.
Providers + Transformers reference (built-in transformer catalog, options, custom transformers)	Explains how heterogeneous provider APIs are made compatible — the adaptation layer.
Router + Custom Router + Subagent Routing	Specifies the routing policy surface — scenario categories, arbitrary JS logic, and per-subagent pinning.
GitHub Actions integration + 'off-peak to reduce API costs' note	Extends the tool from interactive use into CI/automation and names the payoff.

Key terms

Router
The config object that maps task scenarios (default, background, think, longContext, webSearch) to a concrete 'provider,model' target; the policy layer deciding which model handles each request.
Provider
A configured model endpoint — name, api_base_url, api_key, a list of models, and an optional transformer — representing one upstream vendor or local server (OpenRouter, DeepSeek, Ollama, Gemini, etc.).
Transformer
A plugin that rewrites request/response payloads so a given provider's API dialect is compatible with Claude Code's Anthropic-shaped protocol (e.g. deepseek, gemini, openrouter, maxtoken, tooluse, reasoning, enhancetool); the per-provider adaptation layer.
Model Routing Model Routing
Directing each request to a different model based on the kind of task — background, reasoning, or long context — rather than sending everything to one model.
Dynamic Model Switching
Changing the active model mid-session on the fly via the '/model provider,model' command inside Claude Code.
background / think / longContext routing
The built-in scenario categories: 'background' for cheap/local bulk work, 'think' for reasoning-heavy tasks like Plan Mode, 'longContext' for requests past a token threshold (default 60000).
Subagent Routing
Pinning an individual subagent's task to a specific provider/model by placing a <CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL> tag at the start of the subagent's prompt.
Custom Router
A user-supplied JavaScript module (CUSTOM_ROUTER_PATH) that inspects the request and returns 'provider,model' (or null to fall back), enabling arbitrary content-based routing beyond the fixed scenarios.
ccr
The command-line wrapper that launches Claude Code through the router ('ccr code'), restarts the service after config changes ('ccr restart'), and opens the config UI ('ccr ui').

Propositions

explicitdevelopedClaude Code's API requests can be intercepted by a local proxy and routed to different models per built-in scenario — default, background, think, longContext, and webSearch.conf: high
extends ←NVIDIA Personal AI Router Distributes AI Tasks Across Local Compute · p4 — Both are transparent local intercepting proxies that redirect requests without the calling agent or harness noticing; PAIR moves the same pattern from routing-by-model-scenario to routing-by-hardware-node.
explicitA single coding session should split work across models — a small or local model for background tasks, a reasoning model for thinking/Plan Mode, and a long-context model for requests past a ~60k-token threshold.conf: high
explicitHeterogeneous provider APIs (OpenRouter, DeepSeek, Ollama, Gemini, Qwen, Volcengine, SiliconFlow, etc.) can be normalized to Claude Code's Anthropic-shaped protocol via per-provider and per-model transformers.conf: high
supportsHugging Face's Clem Delangue: Stop Comparing Engines to Cars · p3 — Transformers are the concrete adaptation layer that makes open models work behind a harness built for proprietary APIs — exactly Delangue's claim that open models look weaker only because tooling was optimized for closed APIs.
explicitThe active model can be switched on the fly mid-session with the '/model provider,model' command.conf: high
explicitArbitrary routing logic can override the built-in scenarios via a custom JavaScript router that inspects request content and returns a provider/model.conf: high
explicitAn individual subagent can be pinned to a specific provider/model via an inline <CCR-SUBAGENT-MODEL> tag at the start of its prompt.conf: high
explicitThe router runs headless in CI (GitHub Actions), which enables running tasks during off-peak hours to reduce API costs.conf: high
implicitAnthropic's Claude Code harness is valuable independently of Anthropic's models and can — and should — be decoupled from the model behind it, so you keep the harness and its updates while choosing the model.conf: high
supportsHugging Face's Clem Delangue: Stop Comparing Engines to Cars · p1 — ccr unbundles the API — takes Claude Code's harness and routes it to raw/open weights — demonstrating Delangue's point that APIs bundle model + harness + routing, and that the bundle is separable.
implicitThe right model differs per sub-task within one coding session — no single model is optimal across background, reasoning, and long-context work.conf: high
extendsCharlie Hills 🦩's Post · p5 — Generalizes and automates the manual 'Opus for planning, Sonnet for implementation' allocation into config-driven per-scenario routing across arbitrary providers, plus /model, custom router, and subagent pinning.
implicitdevelopedCost and capability are best optimized by routing each task to the cheapest capable model across many providers, not by committing to a single model.conf: high
supportsThe Pulse: a new trend, smart model routing · p6 — ccr is a concrete open-source instance of exactly the routing layer the Pulse piece predicts will become table stakes.
extends ←Microsoft Three-Layer LLM Routing Architecture for AI Agents on AKS · p2 — claude-code-router optimizes cost/capability along a single axis (route each task to the cheapest capable model); this architecture extends that to two more independent axes — request governance/policy and live GPU-state-aware placement — that a pure model-router never addresses.
implicit⚡ disputed & corroboratedThe model is a swappable, commoditized component; the durable value sits in the harness — the agent loop, tools, and UX — that wraps it.conf: medium
supportsAgents Over Bubbles · p5 — By treating the model as swappable behind Claude Code's harness, ccr embodies the claim that model-harness integration (the harness), not the model, is the locus of value.
contradictsAgents Over Bubbles · p7 — ccr runs Claude Code's harness across cheap/open models, treating the model as swappable — technical-feasibility evidence for model commoditization, cutting against the 'Copilot Cowork built on Claude proves commoditization has failed' claim.
supportsAgent Harness Engineering · p1 — 'A decent model with a great harness beats a great model with a bad harness' — ccr operationalizes this by pairing Claude Code's harness with cheaper/decent models.
supports ←AI Root Cause Analysis Shifts from Model Reasoning to Context Engineering · p1 — Both frame the model as a swappable, increasingly commoditized component while the durable engineering value sits in the harness that wraps it.
supports ←Portal by Spotify cut my Claude Code token usage by 90% · p11 — Another instance of the 'harness, not model, is the durable value' thesis: Portal's mode/hook/script/skill stack is reusable and shareable while the worker model itself is an interchangeable parameter ('pick whichever works for you').
implicitA local or open-weight model is good enough for a meaningful share of a coding session's work, background and bulk tasks especially.conf: medium
supportsThe Pulse: a new trend, smart model routing · p5 — Routing background/default work to a local or open model presupposes open models suffice for a large share of coding work — the Pulse '~60% by token spend' estimate.

Arguments

You should run Claude Code through a router that dispatches each request to the cheapest capable model per task type across many providers. strength: medium

Explicit premises:

Task categories within a session differ (background vs. reasoning vs. long-context vs. web-search).
Providers offer different price/capability points, and a smaller or local model suffices for background work.
Transformers make any provider's API compatible with Claude Code's protocol, so the choice of model is unconstrained.
The router runs headless in CI, letting you shift work to cheaper off-peak runs.

Implicit premises:

Anthropic's harness is decoupled from — and more durable than — the specific model it was built around.
No single model is optimal across all sub-tasks, so per-task routing dominates single-model selection.
Quality need only be 'good enough' per task, so downgrading cheaper tasks preserves acceptable output.
The value Anthropic delivers is the harness; the model is a swappable commodity.

Inferences:

If sub-tasks have heterogeneous requirements and models have heterogeneous price/capability, then routing each task to its cheapest adequate model lowers cost at equal quality versus using one model for everything.

Narratives

The comprehensive config.json example: default = deepseek-chat, background = a local Ollama qwen2.5-coder, think = deepseek-reasoner, longContext = Gemini 2.5 Pro via OpenRouter past a 60k threshold, webSearch = gemini-2.5-flash.
→ Concretely instantiates the 'different model per sub-task on a cost gradient' thesis — from free local to premium frontier.
The custom-router.js example that detects 'explain this code' in the user message and routes it to a powerful model (claude-3.5-sonnet via OpenRouter), else falls back.
→ Shows routing can key on request content, not just built-in scenarios — supporting per-task model selection driven by arbitrary rules.
The 'UI mode is 100% vibe coding' aside: the author built the entire web UI with ccr + qwen3-coder + gemini(webSearch), creating only a folder and a project.md.
→ A self-demonstration that a routed mix of open/cheaper models is capable of real project work — supports 'open/local models are good enough for a meaningful share of work'.
The GitHub Actions workflow pointing ANTHROPIC_BASE_URL at a locally-started router with NON_INTERACTIVE_MODE and a deepseek backend.
→ Extends routing into CI and names the payoff — off-peak runs to reduce API costs — supporting the cost-optimization motive.

Questions addressed

✅ How can I use a non-Anthropic (open, local, or cheaper) model behind Claude Code without giving up its harness?
Run ccr as a proxy, define Providers, and use transformers to adapt each provider's API to Claude Code's protocol.
✅ How do I cut Claude Code's model spend without switching tools?
Route background/bulk tasks to a small local or cheap model, reserve frontier models for think/longContext, and run heavy jobs off-peak in CI.
✅ How do I use the best-suited model for each kind of task within one session?
Configure the Router scenarios, switch with /model, add a custom router, or pin subagents with the CCR-SUBAGENT-MODEL tag.
⭕ How is a task's difficulty or output adequacy actually measured so that downgrading to a cheaper model preserves quality?
Not addressed — routing is by static scenario category (background/think/longContext by token count), never by measured difficulty or evaluated output quality.
⭕ What are the data-residency, IP-leakage, and compliance implications of routing proprietary code and prompts to third-party or local model endpoints?
Unaddressed; the README covers an APIKEY/HOST security note for the proxy itself but is silent on where routed code and prompts end up.

Gaps

incompleteThe tool's implicit promise is model-agnostic 'swap freely', yet the very existence of per-provider and per-model transformers (tooluse, enhancetool, maxtoken, reasoning, deepseek, gemini) proves the harness is NOT model-agnostic — different models need bespoke request/response rewriting and tool-call error tolerance just to work behind Claude Code. The README never reconciles 'any model' with 'each model needs its own adapter', so the residual model-harness coupling — and how much reliability you lose swapping to a model the harness wasn't tuned for — is unquantified.
Read next: Read against the harness-engineering thread on model-harness co-training and overfitting: extract-agent-harness-engineering (models get post-trained coupled to their harness) and its open gap on co-training risks; and extract-experiences-with-local-models-for-coding on how much viability is model vs. harness.
incompleteNo quality evaluation of routing. Routing decisions are made by static scenario (background/think/longContext by token count), never by measured task difficulty or output adequacy — but 'route the cheaper tasks to a cheaper model without hurting quality' is the load-bearing claim of any routing system, and the hard part (detecting 'good enough' per task) is treated as solved. No benchmarks show that a routed coding session preserves output quality.
Read next: Pair with extract-pragmatic-engineer-pulse-smart-model-routing (its open gaps on unexamined 'good enough' detection and vendor-only quality claims) and with eval discipline for measuring per-task adequacy.
closed byMicrosoft Three-Layer LLM Routing Architecture for AI Agents on AKS — claude-code-router's gap was the absence of any quality-aware routing mechanism — its routing is by static scenario/token-count, never by measured task difficulty or output adequacy. RouteLLM, as described here, is a concrete counter-example: a matrix-factorization router trained on human-preference data that predicts whether a cheaper model matches a stronger model's answer quality before routing. This partially closes the gap by showing quality-aware routing exists and has a published benchmark — but only partially, since the benchmark is general MT-Bench chat quality, not a coding session, and Microsoft explicitly warns it does not transfer to new model pairs without recalibration.
incompleteThe governance/security dimension is absent. Routing proprietary source and prompts to third-party-hosted or local model endpoints raises data-residency, IP-leakage, and compliance questions; the README addresses only proxy-level auth (APIKEY/HOST) and says nothing about where routed code lands or whether pointing Claude Code at non-Anthropic models respects the harness's terms of use.
Read next: Read alongside extract-pragmatic-engineer-pulse-smart-model-routing's governance gap (routing sensitive enterprise code to cheaper/open/third-party models) and enterprise agent-governance material on data classification and residency.
incompleteNo cost or capability data. The economic case (background to local, off-peak CI, cheaper defaults) is asserted with a config gradient but no numbers — no measured savings, no tokens/sec, no quality-at-price comparison versus running everything on a frontier model.
Read next: Compare with extract-ai-inference-unit-economics and extract-experiences-with-local-models-for-coding (which flags the missing cost/latency/throughput accounting for local setups).

Closes gaps elsewhere

Hugging Face's Clem Delangue: Stop Comparing Engines to Cars · g1 — Answers 'what should builders do when they genuinely need frontier capability' with a concrete hybrid-routing mechanism: route only the sub-tasks that need it (think, longContext) to a frontier model while sending background/bulk work to cheap or local open models — so needing frontier for some tasks doesn't force it for all.
Gemma 4 QAT models: Optimizing model compression for mobile and laptop efficiency · g6 — Operationalizes on-device-as-a-tier rather than a destination: ccr's Router sends background/default work to a local Ollama model and escalates to cloud models for think/longContext via an explicit token threshold — a concrete route/fallback/tiering scheme for hybrid local+cloud architecture.