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.
That's the router: on Claude Code a hook sees every prompt and routes the eligible ones to a local/free model, so Claude quota is spent where it counts. Context-dependent prompts (which a stateless local model can't answer) and provider outages fall back to Claude by design.

⭐ Star on GitHub if Chuzom saves your quota ⭐
Help other developers discover automatic LLM routing

Chuzom is a smart LLM router for AI coding tools. It reads each prompt, sends the easy ones to free local or subscription models, and spends your Claude quota only on the work that truly needs it — so a day's quota stretches across a full week of sessions. Drop-in, zero workflow change, and now independently audited (see Measured results).

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

Contents

• The Problem
• The Solution
• Why People Install This
• 📊 Measured Results (audited)
• Get Started (60 seconds)
• How It Works
• Supported IDEs
• Routing at a Glance
• Agentic Router
• Companion Skill: /council
• Session Summary Dashboard
• Configuration
• 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.

The result: your session hits the wall in under 2 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!

_{🌊 Simple prompts take the fast rapids (local, free). Deep reasoning takes the slow, deep water (Claude). The router reads the current and picks the channel — you never think about it.}

Why People Install This

AI coding tools send too many prompts to premium models by default. That means 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)

Chuzom v1.0.0 is the first release where the savings claim is backed by a real, reproducible control-group benchmark, not just estimated. The router went through a formal correctness reset that ended in an independently audited verdict.

Control-group benchmark — Chuzom vs. always-GPT-4o over a moderate+hard prompt 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% of the routed-workload cost avoided) to typical volumes. Your prompt mix and volume decide the real figure. On a Claude Pro/Max subscription the value is quota runway (more sessions before the wall), 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 also routes subagent spawns — most of that work is offloadable to local/free tiers, so a larger share of the run never touches Claude quota.

Get Started (60 seconds)

1. Install

pip install chuzom-router          # or: uv pip install chuzom-router

2. Wire into your IDE

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

3. 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

4. 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 a smart classification pipeline:

┌──────────────────────────────┐
│ Your prompt in Claude Code    │
└──────────────┬───────────────┘
               ↓
        1️⃣  CLASSIFY            task type · complexity · sensitivity (PII/secrets)
               ↓
        2️⃣  BUILD CHAIN         ranked candidates — cheapest capable first, with fallbacks
               ↓
        3️⃣  DISPATCH + STREAM   first qualified model · live progress · auto-failover · local log
               ↓
        ✅  Result              🎯 chuzom → <model> · <task> · <latency> · saved $<amount>

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, e.g. Cursor/Copilot/Windsurf).

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 the task into milestones, each with an objective, executable acceptance check (cmd / lint / diff / canary). "Done" means the check passed, not the model's 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 small 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: the 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 dashboard 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 (direct execution, session context, subscription mode) → Configuration reference.

More docs

Benchmarks

The audited control-group figures are in Measured Results (the numbers to trust). Chuzom also ships a built-in 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); the extension sharpens the estimate. A production-scale corpus (thousands of prompts) 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.

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. Heavy-Opus workloads see the largest gains; light users see less.

Which models does it support? 20+ providers: OpenAI, Anthropic, Google, Ollama, 13+ local servers, and more.

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.10+). Contributions welcome!

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

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

License

MIT © The Chuzom Contributors