⠀⠀⠀⠀⠀⠀⠀⠀⣀⣠⣴⣶⣾⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⣀⣤⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⣠⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⢾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠿⠗⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠘⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⣰⣿⡿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠐⠛⠁⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣤⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠈⠛⢉⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣶⣶⣦⣤⣤⣀⣀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠐⠋⠁⠀⢹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣄⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠛⠛⠛⠉⠉⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷

Your whole setup lives in Claude Code, not in the model: MCP servers, skills, CLAUDE.md, hooks, memories, plugins. But Claude Code speaks one protocol, the Anthropic Messages API, so trying another model means changing tool and starting over.

Lupin changes the model. Nothing else moves.

Sixty seconds

npx lupin-code@latest init            # wizard: provider, key, a real connectivity test
npx lupin-code@latest run -- claude   # Claude Code, already routed

If you keep it, install it once and drop the npx. Every example below uses the short command:

npm i -g lupin-code
lupin --version

Switch model with the session open, no restart:

lupin use glm                # you are on GLM-5.2 from the next request
lupin use gpt --bg kimi      # main on GPT, haiku-tier traffic on Kimi
lupin go kimi-sub -- claude  # switch and launch, one gesture

Mix subagents, each agent type on its own model or provider:

lupin agents set subagents --profile ollama-qwen   # every subagent on the local model
lupin agents set explore --profile kimi --wire     # a named agent, frontmatter written for you
lupin agents                                       # the table, plus the id each agent uses

lupin agents prints an id per route (claude-lupin-agent:<name>). Put it in an agent's frontmatter model:, or let Lupin do even that: --wire writes the line into the agent's definition file (the one deliberate exception to "never touch your harness", on an explicit flag, old value printed, ADR-48), and the blanket subagents route travels through CLAUDE_CODE_SUBAGENT_MODEL, which lupin run sets for you. After that one-time aim, the agent is yours, live, from the CLI, the TUI (a) or the control API. There is no other honest way: Claude Code sends no header or metadata that identifies a subagent, so the model id is the one channel a proxy can route on, and the routing stays visible per request in the log (agent:<name> in lupin top).

Use a subscription instead of an API key:

lupin login kimi      # device flow
lupin login openai    # Sign in with ChatGPT
lupin login gemini --i-accept-the-risk
lupin login copilot --i-accept-the-risk

Or without leaving Claude Code at all: open /model and pick a row that reads switch Lupin profile: <name>. Lupin publishes one per profile, and picking one moves the active profile from inside the session, with the conversation intact. That is the answer to running out of quota mid-task, and it is exactly how this was verified: Kimi answered usage limit for this billing cycle, the picker moved the session to ChatGPT, and the next request was served.

Not one more router: the honest one

Everybody translates formats. Nobody tells you whether the model survives the harness.

That is the hard part. A model can speak the protocol perfectly and still fail every task, because Claude Code demands exact-match edits, a tool loop that closes, and roughly 46,000 tokens of prompt before the first word. So Lupin ships the question as a command:

lupin doctor kimi-sub

_{A real run against the ChatGPT subscription. Only the waiting is edited: the session took 116 seconds and is held for two.}

lupin doctor runs a real headless Claude Code session against a dedicated server on an ephemeral port, and scores it from artefacts on disk (files really edited, scripts that really run), never from what the model claims it did. Six checks, threshold 7, no hidden retries.

Three things it refuses to do, each of them learned the hard way:

• It will not grade a session that never reached the model. Claude Code reports success when its own loop ends cleanly, even when every request died on a protocol error. Where another tool would print 1/10 and blame the model, the doctor prints notRun and the cause (ADR-23).
• It will not hide its own help. A 10/10 earned because the proxy repaired a broken tool call is different information from a clean 10/10, and the verdict says which one you got.
• It will not invent a number. No score is reported for a provider nobody has run.

Providers

Four lanes, picked by Lupin, never by you. Passthrough first: when a provider already speaks Anthropic, nothing is translated at all.

344 models on OpenRouter, and Claude Code can natively use zero of them, because OpenRouter's Anthropic-compatible endpoint only accepts Anthropic models. Through Lupin the 255 with tool calling become usable. The other 74 connect and stay a chat, which the wizard says out loud instead of letting you find out mid-task.

Claude Code ──ANTHROPIC_BASE_URL──▶ Lupin (127.0.0.1)
                                      │
            ┌───────────────┬─────────┴─────────┬────────────────┐
            ▼               ▼                   ▼                ▼
      [passthrough]    [translate]        [responses]      [codeassist]
      Kimi, DeepSeek   OpenAI, Gemini,    ChatGPT          Gemini Code
      Z.AI, Ollama     llama.cpp,         subscription     Assist
      LM Studio, ds4   OpenRouter,        (WHAM)           subscription
                       Copilot

Where routers really break

A provider can honour the protocol to the letter and still hand you garbage inside the content: reasoning wrapped in <think>, a tool call the server never turned into tool_calls[], special tokens leaking into the text. The model "calls" the tool, nobody runs it, and the agentic loop dies quietly.

In a sample of 382 claude-code-router issues, over 29% land here, re-fixed provider by provider instead of once. Lupin treats it as one problem, with one engine.

The terminal, done properly

A bare lupin opens the hub. With the optional Rust sidecar on your PATH it is a live dashboard; without it, a status summary and the next step.

The sidecar is not on npm and never will be: it stays out of the JavaScript runtime by design. Build it from a clone, once, then launch it with the bare command:

cargo build --release --manifest-path tui/Cargo.toml
cp tui/target/release/lupin-tui ~/.cargo/bin/      # anywhere on PATH will do

lupin        # the hub finds the sidecar and opens the dashboard
lupin-tui    # or run it directly

That build is a one-time cost: from then on lupin update rebuilds the sidecar to the matching version on every package update, from the sources the package itself ships (it needs the Rust toolchain; without one it prints the manual command instead).

Keys: 1-9 switch profile, arrows and Enter do the same on the highlighted row, d runs the doctor on the highlighted profile, : opens the command palette, o edits the failover order, a opens agents mode, r refreshes now, q quits.

Agents mode is the subagent mixer on screen: it lists every agent route plus the conventional subagents row (shown even before it exists, so the first gesture is obvious), and on the selected row 1-9 aims it at that profile, x clears it, Enter applies the whole table atomically through the control API, Esc throws the edit away. The daemon writes the config and hot-reloads it, so a live Claude Code session picks the new routing up on its next request. Model-string targets and brand-new route names are one command away in lupin agents set, and the overlay says so rather than hiding the limit.

The doctor takes minutes, so it runs as a child process and its output streams into a panel while the dashboard keeps refreshing underneath. The palette lists init, login and run too, and says plainly that they need a shell: the first reads hidden input, the second waits on a browser, and the third hands the terminal to Claude Code.

Give it 32 rows or more and it draws the portrait full size; below that it keeps every fact and shrinks the art. It needs a real terminal: it takes over the screen, so it will not do anything useful inside another tool's output pane.

⣀⣤⣶⣾⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀  L U P I N  v0.2.3   the gentleman router
⠈⢿⣿⣿⣿⣿⣿⣷⣖⠀⠀⠀⠀⠀⠀⠀  daemon up   127.0.0.1:3456
⠀⠴⢿⣿⣿⣿⣿⣿⣿⣀⠀⠀⠀⠀⠀⠀  active: kimi-sub  ->  k3
⠀⠀⠈⠛⢿⠿⣿⣿⣿⣿⣿⣶⣶⣶⣤⣄

Profiles with 1-9 hotkeys, the routing truth per slot, the request tail with every marker (routed, agent, failedOver, tierDowngrade, dialect), and a status line that says in words what just happened. lupin top gives the same truths with no sidecar at all. Details in docs/TUI.md.

There is also a statusline for Claude Code itself, because through a proxy the model introduces itself as the Claude of the system prompt (the UI knows nothing about the mapping, ADR-3), so asking it who it is proves nothing. The truth lives in GET /health, and the statusline shows it as ⇄ profile→model.

"statusLine": { "type": "command", "command": "powershell -ExecutionPolicy Bypass -File \"C:\\Users\\<you>\\.claude\\statusline.ps1\"" }

Questions people actually ask

What you lose with any proxy

Claude Code ties some features to the claude.ai login and to api.anthropic.com. Point ANTHROPIC_BASE_URL anywhere else (Lupin, claude-code-router, LiteLLM, any gateway) and Claude Code itself disables them. There is no hybrid mode.

• Remote Control (driving the session from claude.ai or your phone), since v2.1.196.
• MCP connectors hosted on claude.ai, voice dictation, and the cloud surfaces (web, mobile, Slack, routines, ultrareview).

One cosmetic quirk to expect: resuming a session may print Session model k3 could not be restored. Claude Code persisted the provider's own model name and fails to find it in its catalogue. The routing stays correct, you only lose the persistence of the /model selection across restarts. Lupin does not rewrite the response to hide this, because byte-faithful passthrough is the entire point of passthrough (ADR-7).

Local models, zero keys

Pick ollama, lmstudio, llamacpp or ds4 in the wizard: no key to paste, the models are read from your own server with their real context windows, and you get a warning about the ones that do not declare tool support, since Claude Code cannot take a single step without them.

That distinction is not pedantry. gemma-4-12b declares a 262,144 token window and runs with 8,192: a factor of 32. Lupin always prefers the loaded window over the declared maximum, and marks which one it got.

Everything else

Principles

1. Fixture first. The fixture, recorded from real provider output, comes before the code. Real dialects are stranger than you would guess: keep-alive SSE comments, repeated finish_reason, usage arriving after the stream ended, errors delivered as a data frame.
2. Centralized quirks. Never if (provider === x) scattered around. Flags in one registry, one implementation each.
3. Privacy. Prompts and responses are never persisted. Keys live in the OS keychain or a 600 file, never in the config and never in the logs. It binds to 127.0.0.1 only.
4. Zero side effects. Lupin never touches ~/.claude/settings.json. Uninstalling means stopping using it.
5. No invented numbers. A context window enters the defaults only when the vendor publishes the exact figure. DeepSeek and Gemini write "1M" without saying whether that is 1000 or 1024, so they stay without one: a route that never fires beats a route that fires on the wrong number.
6. Disciplined scope. Lupin stays a proxy. No Electron app, no web dashboard, no relay bot. The biggest competitor accumulated 853 open issues while adding surface; the answer here is not to add it.