Chuzom — Route eligible prompts to local/free models before spending Claude quota.

A Chuzom is a confluence — the place where rivers meet.
Fast rapids and deep water, converging, each stream finding its natural path.
⭐ Star the repo if Chuzom saves your quota.

Chuzom is a smart LLM router for AI coding tools. On Claude Code a hook sees every prompt, sends the eligible ones to a free local or subscription model, and spends Claude quota only on work that truly needs it — so a day's quota stretches across a week of sessions. Context-dependent prompts (which a stateless local model can't answer) and provider outages fall back to Claude by design. Drop-in, zero workflow change, and independently audited — see Measured results.

pip install chuzom-router && chuzom install --host claude-code

Contents

Why — The Problem · The Solution · Why People Install This · 📊 Measured Results (audited)
Use — Get Started · How It Works · Supported IDEs · Routing at a Glance · Configuration
More — Agentic Router · /council · Session Dashboard · More docs · FAQ · Contributing · License

The Problem

You're on Claude Pro ($20/mo), Max ($100/mo), or Max ($200/mo) — a flat subscription, not pay-per-token. But Claude Code routes every request through your quota: file reads, quick questions, routine edits, and complex reasoning all burn the same limited budget. Claude throttles after roughly 40–50 messages in a 5-hour rolling window — your session hits the wall in under two hours, and you wait.

Simple questions and complex reasoning cost the same quota. That's the inefficiency Chuzom fixes.

The Solution

Chuzom routes each prompt to the cheapest capable model before spending Claude quota.

Your IDE (Claude Code, Cursor, etc)
    ↓
[Chuzom Smart Router]  ← analyzes complexity & task type
    ↓
├─ Simple tasks?   → Ollama (local, free) 🌳
├─ Moderate tasks? → Codex CLI / Gemini CLI (free via your subscriptions)
└─ Complex tasks?  → Claude (only when it truly needs it) 🔥
    ↓
Result + streaming progress + quota savings banner
    🎯 chuzom → gemini-2.5-flash · code/moderate · 342ms · saved Claude quota!

Why People Install This

AI coding tools send too many prompts to premium models by default — you waste paid tokens on simple questions, burn quota faster than necessary, and stop working when one provider is rate-limited. Chuzom sits between your coding tool and your model providers: it classifies each prompt, tries the cheapest capable model first, and falls back automatically when needed. You keep the same workflow. The router changes the model choice underneath.

Fewer walls. Longer flow. The same workflow — just calmer underneath.

📊 Measured Results (audited)

Since v1.0.0, the savings claim has been backed by a real, reproducible control-group benchmark — not an estimate — after a formal correctness reset that ended in an independently audited verdict. Chuzom vs. always-GPT-4o over a moderate+hard corpus, under strict full metering (every escalation is a real, priced API call — no free-tier confound):

All 20 release gates pass, including a positive-net-savings gate, a quality-non-inferiority gate, and a mutation-testing bar. Full evidence: Release Gates · Benchmark log · Audit runbook.

On the "3×" / "80%" headline numbers. Those are illustrative estimates for a heavy-Opus workload — real savings depend entirely on your prompt mix. The measured figures above are the honest, reproducible ones. Reproduce them yourself with python -m chuzom benchmark.

Estimated savings by workload

These are illustrative estimates — directional, not measured. They apply the audited ratio (Chuzom spent ~12% of the always-premium cost at non-inferior quality → ≈88% avoided) to typical volumes. On a Claude Pro/Max subscription the value is quota runway, not cash — the money column applies only if you'd otherwise pay per-token at GPT-4o rates.

Why agentic saves the most: a single llm_act task fans out into many execute/verify sub-steps, and Chuzom routes subagent spawns too — most of that never touches Claude quota.

Heavy-user week, expanded

Directional estimate — not statistically significant. Reproduce the audited figures with python -m chuzom benchmark.

Get Started (60 seconds)

1. Install and wire into your IDE

pip install chuzom-router            # or: uv pip install chuzom-router
chuzom install --host claude-code    # or: cursor, codex, gemini-cli, windsurf, all

2. Add API keys (optional)

# Bring your own keys — stored in ~/.chuzom/.env, never committed
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export PERPLEXITY_API_KEY=pplx-...        # for research routing

# Or: use Claude Code Pro/Max or Codex subscriptions (zero keys needed)
export CHUZOM_CLAUDE_SUBSCRIPTION=true

3. Verify & watch savings

chuzom doctor            # checks hooks, Ollama, API keys, provider health
chuzom summary --watch   # live savings dashboard

Done. Your IDE now routes intelligently. (Windows PATH tips → Troubleshooting.)

How It Works

Every prompt flows through the same pipeline — classify (task type · complexity · sensitivity), build a chain (ranked candidates, cheapest capable first), then dispatch and stream with automatic failover and a local decision log:

Local-first, no Chuzom telemetry. Chuzom runs on your workstation and phones home to no Chuzom servers — every routing decision is logged locally. Note: if you configure cloud providers (e.g. OPENAI_API_KEY, GEMINI_API_KEY), the classifier and the routing chain send prompt text to those providers' APIs when they are selected. With only a local provider (Ollama) configured, prompt text stays on your machine.

Supported IDEs

Chuzom works with every major AI-assisted IDE via two modes — push (a hook routes automatically, e.g. Claude Code) and pull (the model chooses to call Chuzom tools).

Claude Code gives the most consistent routing (a hook fires every turn). Per-IDE setup, the push/pull deep dive, and the 11-door MCP tool surface → IDE Setup guide.

Routing at a Glance

Chuzom tries each tier in order, falling back on failure or timeout:

Six one-line routing policies (balanced, local-first, cost, quality, quota-exhaustion, dynamic) tune the cost/quality tradeoff. Chuzom also routes subagent spawns, auto-detects 13 local inference servers (details), and never hardcodes model names (Ollama dynamic discovery).

Full chains, subagent routing, the REASONING profile, model pinning, and every policy → Routing guide.

Agentic Router

Status: real but maturing. Design + phased plan in Docs/agentic-router.md.

Beyond routing a single completion, Chuzom can delegate a whole task to the cheapest capable, tool-using agent and verify the result — via the llm_act MCP tool (Milestone-Gated Escalating Execution):

1. Plan — decompose into milestones, each with an objective, executable acceptance check (cmd / lint / diff / canary). "Done" means the check passed, not a self-report.
2. Delegate — each milestone runs on the cheapest capable tier (local agent → Codex → premium).
3. Escalate without rework — a failed check escalates to a stronger tier, carrying already-passed milestones forward as frozen context.
4. Flow, not stall — escalation is bounded; irreversible steps run in an isolated git worktree, merged only after they verify.

llm_act(task="…")   # → JSON: outcome, per-milestone status, events, savings

Prompts with a code-mutating verb and an objective-verification demand (e.g. "fix the failing test and make it pass") route to delegation automatically. Disable with CHUZOM_DELEGATE=off; any llm_* call clears the route, so you're never trapped.

🧠 Companion Skill: /council

Where Chuzom picks the cheapest capable model, /council is the quality-maximizing counterpart: it convenes a committee of the strongest available models for genuinely hard problems and runs propose → critique → synthesize across model families (Claude Opus, Codex/GPT-5.x, optional Gemini). The output includes a fused answer and an explicit dissent section — minority views are preserved, not averaged away.

/council Should we migrate this service to event sourcing?
/council --tier=max Evaluate this architecture decision thoroughly.

Use it when the cost of being wrong is higher than the cost of asking twice. It never auto-fires — the human always confirms before any multi-model run.

Session Summary Dashboard

At the end of every session, Chuzom prints a full-color Tokyo Night dashboard: routing method breakdown, per-window savings, live Claude quota bars, per-model costs, a 14-day activity chart, and a per-tier routing summary (Free local / Free subscription / Paid API).

  🧮 Routing Summary — this session
  Tier              | Calls | Tokens |   Actual |  Baseline |    Saved
  ──────────────────────────────────────────────────────────────────
  Free local        |    16 |    240 | $ 0.0000 | $  0.0013 | $ 0.0013
  Free subscription |     5 |   3516 | $ 0.0000 | $  0.0190 | $ 0.0190
  Paid API          |    27 |  13421 | $ 0.1735 | $  0.0725 | $ 0.0000
  ──────────────────────────────────────────────────────────────────
  TOTAL             |    48 |  17177 | $ 0.1735 | $  0.0928 | $ 0.0203

Long model calls also stream live progress (Codex JSONL events, Gemini lines, heartbeats) — no silent 80-second waits. Full walkthrough → Session Dashboard guide.

Configuration

Everything works out of the box. Common one-liners:

export CHUZOM_CLAUDE_SUBSCRIPTION=true          # enable Claude quota tracking
export CHUZOM_ROUTING_POLICY=local-first        # or: cost, quality, balanced, dynamic
export CHUZOM_OLLAMA_MODEL=qwen2.5-coder:7b     # pin a local model
export CHUZOM_ENFORCE=smart                     # default — see the enforcement ladder

All settings can live in ~/.chuzom/.env (loaded automatically). The full env-var matrix, enforcement modes (smart / soft / hard / strict / advise / off), and advanced options → Configuration reference.

More docs

Benchmarks

The audited control-group figures are in Measured Results — the numbers to trust. Chuzom also ships a smoke corpus of 77 prompts (easy × 20, hard × 16, moderate × 17, plus objective-heavy moderate2 × 12 and hard2 × 12) for quick local checks; the audited release benchmark uses the moderate + hard baseline (33 prompts). A production-scale corpus has not been published yet.

python -m chuzom benchmark   # run your own

FAQ

Do I need to bring API keys? No — not if you use Claude Code Pro/Max or Codex subscriptions. Optional for other providers.

What data does Chuzom collect? None. Everything stays on your machine — no telemetry, no cloud calls to Chuzom.

How much can I actually save? It depends entirely on your prompt mix. The honest, reproducible number is the audited +$0.027/run net at −0.21 quality control-group result above.

Which models does it support? 18 providers — OpenAI, Anthropic, Google, Ollama, DeepSeek, Groq, Mistral, xAI and more — plus 13 auto-detected local servers.

Does Chuzom work without Ollama? Yes — Ollama is optional. Without it, prompts route to Codex CLI, Gemini CLI, or API providers. Install Ollama for free local routing.

Can I use it on Windows? Yes. pip install chuzom-router then chuzom install. PATH and PowerShell tips → Troubleshooting.

How do I stop it blocking a tool call? Relax with CHUZOM_ENFORCE=soft (log only) or off. For a single turn, prefix your prompt with claude:. See enforcement modes.

More Q&A in the Troubleshooting guide.

Contributing

Full test suite runs on every push (Python 3.11–3.14). Contributions welcome!

• 🐛 Report bugs
• 💡 Start discussions
• 🔧 Read CONTRIBUTING.md

Chuzom also ships as a Codex plugin (category Developer Tools).

License

MIT © LLM Router Contributors