UncommonRoute: a local LLM router that classifies each request before it leaves your machine
Automatic LLM router — 82% cost savings, 79.4% accuracy, 93.4% pass rate. Drop-in OpenAI proxy.
At a glance
- What is it?
- UncommonRoute is an MIT-licensed Python router that sits between your coding agent and the model providers, classifying each request as simple, medium, or complex and picking a model accordingly. The README's own benchmark shows a small accuracy gain over Opus-only at roughly half the cost, and the interesting part is the local feedback overlay, not the headline number.
- Who is it for?
- Adopt UncommonRoute if you already run Claude Code, Codex, Cursor or the OpenAI SDK against frontier models and want a local, inspectable layer that decides per request whether the expensive model is needed. Skip it if you route a single model anyway, if you cannot run a local process on developer machines, or if your workload is uniformly hard enough that every request escalates.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 82 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The spend problem UncommonRoute targets
Daily agent use mixes requests of wildly different difficulty. A typo fix, a short explanation, and a failing-test investigation all hit the same endpoint, and if that endpoint is a frontier model, all three are billed at frontier rates. The README frames the product around exactly this: most of the spend goes to work that does not need the most expensive model. UncommonRoute does not try to make cheaper models smarter, and it does not replace Claude Code, Cursor, or Codex. It answers one question per request, which model is the right fit, and the intended user is a team or individual already paying for frontier models through a coding agent. If your traffic is uniformly hard, there is nothing here for you, and the README is honest about that scoping.
Classification signals and the three-tier routing decision
The mechanism is a local classifier that reads the request and assigns it to one of three complexity tiers. The README lists the inputs as task difficulty, conversation structure, tool use, and provider availability, and its own examples map cleanly: a greeting or a README typo is simple, finding and fixing a failing test is medium, refactoring a 500-line module is medium or complex, and designing a distributed scheduler is complex. Simple requests go to lightweight models, medium to mid-tier, complex to the strongest model configured. Routing is per request, so a single conversation is not pinned to one tier, which matters for agents that emit many steps per task. The README also states that routing happens locally and independently for each agent step, with no extra hop through a cloud routing service. That is a real architectural difference from hosted routers: the classification decision never leaves the machine, only the chosen provider call does.
Installing it and pointing your client at the proxy
The documented install path is pipx install uncommon-route followed by uncommon-route init, which walks through connection setup, saves credentials, and configures Claude Code, Codex, Cursor, or the OpenAI SDK. uncommon-route doctor is the health check afterwards. The macOS note is worth reading before you start: brew install pipx libomp, because libomp is required by the trained classifier runtime. Ubuntu and Fedora use their package managers for pipx. Inside an existing virtualenv the README offers python3 -m pip install uncommon-route instead. Client wiring is environment variables. Claude Code takes ANTHROPIC_BASE_URL="http://localhost:8403" plus ANTHROPIC_AUTH_TOKEN="not-needed" as a placeholder. The OpenAI SDK, Codex, and Cursor all take OPENAI_BASE_URL="http://localhost:8403/v1", and OpenAI SDK callers use uncommon-route/auto as the model ID. The README's Python example is a standard client.chat.completions.create call against that base URL. The dashboard runs from uncommon-route serve at http://localhost:8403/dashboard/.
The dashboard, the feedback overlay, and why that part matters
A router that silently picks models is hard to trust, so the dashboard is doing more than decoration. It previews how a prompt will be classified before you send it, records each routed request per session with model, latency, cost, and signal readout, and shows which complexity classes and models are driving spend. Policy, fallbacks, budgets, provider keys, and model pools are tunable there. The part with real consequences is the rating loop: you label decisions as too strong, just right, or too weak, and those labels train a thin local overlay on top of the base classifier. The README states the base model is never overwritten and the overlay can be rolled back. That is a sensible design. It also means the tool's usefulness after the first week depends on someone actually labelling decisions, which is a human process cost the README does not quantify.
What the benchmark does and does not tell you
The headline table comes from a held-out 100-case SWE-bench Verified split in TwinRouterBench: 74 of 100 tasks solved with Opus-only at $54.73, versus 75 of 100 with the trained router at $25.66, a 53 percent cost reduction. Note the framing carefully. This is a 100-case split, so a single task is one percentage point, and the accuracy difference of one task is inside that granularity. The claim worth taking seriously is cost at matched accuracy, not the one-task edge. The repository description also advertises 82 percent cost savings, 79.4 percent accuracy, and a 93.4 percent pass rate, which do not appear in the README benchmark table and are not explained there. Treat the 53 percent figure as the documented one and the 82 percent figure as unverified until you find its conditions. The benchmark also covers coding tasks on SWE-bench, so it says nothing about routing quality for other workloads.
Spend caps, policy modes, and the wrong-tool cases
Policy can be set to auto, fast, or best, or you can override the simple, medium, and complex tiers with primary and fallback models. Spend caps exist at per-request, hourly, and daily granularity. The failure mode to think about is a classifier that under-rates a hard request: the cheap model returns a plausible but wrong answer, the agent proceeds, and you pay for the mistake in debugging time rather than tokens. The rating loop exists to correct this, but it corrects after the fact. The other limitation is operational. This is a local process on port 8403 that every client points at, so if it is not running, your agent calls fail unless the client is reconfigured. The macOS libomp dependency hints that the trained classifier runtime is not pure Python, which adds a platform-specific install step. And if your requests are mostly complex, the router adds a local hop and a classification step while escalating everything anyway.
How it differs from a static model alias or a hosted gateway
The obvious alternative is a static setup: point your agent at one mid-tier model and accept the quality ceiling, or point it at one frontier model and accept the bill. That is a single decision made once, not per request, and it requires no local process. A hosted routing gateway is the other comparison, and the README draws the line itself: UncommonRoute runs locally with no extra hop through a cloud routing service, and decisions are inspectable in the dashboard rather than trusted as a black box. The trade is that you own the runtime, the port, and the classifier dependency, where a hosted gateway owns them for you. Whether local classification is worth that ownership depends on how much you care about request content leaving your machine, which the README treats as a design property rather than arguing it explicitly.
Licence, release cadence, and upgrade cost
The project is MIT licensed, which permits commercial use and modification, but this is not legal advice and you should read the LICENSE file and your providers' terms yourself. The release history in the supplied material shows three releases on 2026-05-07 (v0.7.19, v0.7.20, v0.7.21) within about two hours, and the last push to main is 2026-06-26. That pattern suggests active iteration on a sub-1.0 line, which cuts both ways: fixes arrive quickly, and pinning a version is prudent because the config surface (model pools, fallbacks, budgets, provider keys) is the kind of thing that shifts between minor releases. There is no documented migration guide in the material provided, so an upgrade path from one v0.7.x to the next cannot be confirmed from what is here. The local overlay is the one piece of state you would want to back up before upgrading, since it represents accumulated feedback rather than anything reproducible from the base model.
Editorial conclusion
Adopt UncommonRoute if you already run Claude Code, Codex, Cursor or the OpenAI SDK against frontier models and want a local, inspectable layer that decides per request whether the expensive model is needed. Skip it if you route a single model anyway, if you cannot run a local process on developer machines, or if your workload is uniformly hard enough that every request escalates. Before rolling it out, run uncommon-route doctor, then open the dashboard at http://localhost:8403/dashboard/ and preview how your own prompts classify, because the value of the tool depends entirely on whether your traffic contains a large simple tier.
Community notes