NadirClaw: a self-hosted OpenAI-compatible proxy that routes prompts by predicted difficulty

The prompt-difficulty gap NadirClaw is built to exploit

The README makes a specific claim about workload composition: in typical coding sessions, 60-70% of prompts are simple, covering file reads, short questions and formatting. Requests like those do not need a frontier model, and the price difference between a flash-tier model and a premium one is large. NadirClaw exists to make that observation operational rather than aspirational. It is aimed at developers running agentic coding tools such as Claude Code, Cursor, Aider, Codex and OpenClaw, plus anyone pointing an OpenAI-compatible client at a base URL they control. The target user is not someone experimenting with a single model. It is someone with a per-token bill and a workload that is mostly routine with occasional spikes. The README's own sample session shows five prompts, three routed cheaper, and a stated total of $0.549 against $1.37 for an all-premium baseline. That is an illustration from the documentation, not an independently reproduced measurement, and the pricing behind it is not given.

Route, verify, escalate: the three-stage cascade

Every request passes through three moves, and the middle one is what separates this from a plain load balancer. Route sends the prompt to the smallest model predicted likely to answer, using what the README describes as a roughly 10ms embedding classifier. Routing modifiers can override that prediction: agentic tool loops, reasoning markers, vision content and long context each force a stronger tier regardless of the classifier score. Verify then scores the cheap answer against quality heuristics before it is returned to the caller. The README names the failure classes those heuristics look for: refusals, truncation and JSON-format failures. Escalate fires when the score falls below an acceptance threshold the README gives as tau = 0.80, at which point the request steps up to the next-best model. The cost model follows from that ordering. You pay premium prices only when the cheap answer was demonstrably inadequate, and the cascade rule engine lives in nadirclaw/cascade_rules/ according to the README. The design has an obvious asymmetry worth naming: verification happens after the cheap model has already been paid for, so a request that escalates costs more than it would have if it had been routed correctly the first time. The README reports a catastrophic-downgrade rate of 1.7% for the composed system, which is the share of cases where the cheap answer shipped and should not have.

The benchmark numbers belong to Pro, not to this package

This is the part of the README that deserves the most scrutiny. The headline figures (AUROC 0.961, expected calibration error 0.016, 98.3% quality preserved versus always-Opus, -60% composed cost) are attributed in the README itself to the trained classifier plus DeBERTa verifier in Nadir Pro. The OSS classifier, by the README's own wording, uses a simpler binary centroid that trades some accuracy for zero training cost. Both share the same cascade rule engine, so the routing logic is comparable, but the component that decides where a prompt goes is not the component the benchmark table describes. The RouterBench figures come from a held-out set of n=11,420 and the RouterArena sub_10 figures from n=809, with the README listing a projected leaderboard rank of #5. A contamination audit is included, run on three dates in May 2026, reporting zero overlap across 36,481 and 809 and 8,399 prompts respectively, with a hash recipe of sha256(NFC(prompt).strip().casefold().utf8) and a script at verifier/contamination_audit.py. The audit is a genuine methodological detail and the README says it is reproducible from the repository. None of that changes the classifier substitution. If you install the pip package, do not expect the AUROC in the table.

Getting it running: install, setup, serve

Installation is a single pip command, pip install nadirclaw, or a curl-to-shell script from the repository's raw GitHub URL if you prefer source. The interactive wizard is invoked as nadirclaw setup, and the README says it walks through provider selection, API key entry, and model choice per routing tier. The server starts with nadirclaw serve --verbose and listens on http://localhost:8856. Defaults are given as Gemini 3 Flash for simple prompts and OpenAI Codex for complex ones, and if you skip setup the serve command offers to run it on first launch. Two configuration details appear in the release history rather than the README body. Version v0.23.0 introduced NADIRCLAW_PREFER_ENV_KEYS, which by its name governs whether environment variables take precedence over stored keys, and also added a headless serve mode. Version v0.23.1 is titled prompt cache key correctness, which suggests cache key handling was wrong in an earlier build. Anyone running this behind a shared cache or with multiple providers configured should treat v0.23.1 as the floor. Because the proxy is OpenAI-compatible, client configuration is a base URL change rather than a code change, which is the practical reason the tool is easy to trial and equally easy to remove.

Where the cascade model breaks down

The failure mode is structural, not incidental. A router that optimises for the cheapest sufficient model will underperform on workloads where difficulty is uniform and high. If every prompt in your session is a multi-file refactor or a subtle concurrency bug, the classifier will keep predicting cheap, the verifier will keep rejecting, and you will pay for both the failed cheap attempt and the escalation. The README's own example session shows this shape: one COMPLEX prompt routed to gpt-5.2 cost $0.450, which is more than the other four prompts combined. Escalation is not free, and a workload that triggers it often will erode the savings the tool is sold on. The verification heuristics are also narrow. Refusals, truncation and malformed JSON are detectable. A confidently wrong answer that happens to be well-formed and complete is not, and the README does not claim otherwise. That is the gap between the 1.7% catastrophic-downgrade figure and whatever your own domain produces. Finally, the roughly 10ms classification overhead is stated for the classifier alone; the README does not break out the verifier's cost, and the Pro verifier is a cross-encoder, which is a different class of model from a heuristic check.

The alternative: a fixed model per client, or a hosted gateway

The most direct alternative is no router at all. Point each client at one model, chosen by hand, and accept the cost. That approach is trivially debuggable, has no classification latency, and cannot misroute. Its weakness is exactly NadirClaw's strength: a session that is 70% file reads pays premium rates for all of it. The second alternative is a hosted routing service, and the README positions Nadir Pro against its own OSS build rather than against an outside competitor. The difference in approach is where the routing decision and the provider credentials live. NadirClaw runs locally and routes directly to providers, which the README frames as your keys, your models, no middleman. A hosted gateway moves that decision to someone else's infrastructure, which buys you a trained classifier and operational dashboards without running anything, and costs you the property that your API keys never leave your machine. The README also links a comparison document at docs/comparison.md and a page at docs/vs-clawrouter.md, so the project has published its own positioning; those files are the place to check the claims rather than the marketing line.

Licence status and the cost of staying current

The repository metadata reports the licence as NOASSERTION. That is not a licence. It means the automated classifier could not map the LICENSE file to a known identifier, and it is a real obstacle if you need to know your obligations before shipping. Read the LICENSE file in the repository directly and decide from the text, not from the badge. On maintenance, the release cadence visible in the supplied material is three releases across roughly six weeks in mid-2026, with the most recent two landing two days apart and both addressing correctness rather than features. That pattern suggests active work on the routing core, and it also means the surface you depend on can shift. Upgrading is a pip install away, but the v0.23.1 prompt cache key fix is a reminder that a proxy in the request path can change what your provider sees. Pin a version in any environment where cost accounting matters, and re-read the release notes before moving. The README also points to a companion GitHub Action repository, which implies a CI path exists, though the supplied material does not describe what it does.

Editorial conclusion

Adopt NadirClaw if you already pay per-token for a mix of trivial and heavy prompts and you want the routing decision to stay on your machine, with your provider keys never leaving it. Do not adopt it if your workload is uniformly hard, or if you need the accuracy numbers in the README, because those come from the Pro classifier and the OSS build substitutes a simpler binary centroid. Before committing, verify three things: that your client speaks the OpenAI chat completions shape, that the escalation path reaches a model you have credentials for, and that the repository's licence file actually states terms you can accept, since the GitHub API reports NOASSERTION rather than a recognised identifier.

Official sources

1. Issues
2. NadirRouter/NadirClaw on GitHub
3. Project website
4. README
5. Releases