Metadata-Version: 2.4
Name: chuzom-router
Version: 1.1.0
Summary: LLM cost router. On Claude Code a UserPromptSubmit hook intercepts every prompt and can run eligible ones on local/free providers (Ollama, Codex CLI, Gemini CLI) before using Claude quota; on Cursor/Copilot/Windsurf a rules file asks the host model to route (best-effort, not guaranteed). Savings depend on a configured local provider and workload.
Project-URL: Homepage, https://github.com/Chuzom/Chuzom
Project-URL: Repository, https://github.com/Chuzom/Chuzom
Project-URL: Documentation, https://github.com/Chuzom/Chuzom#readme
Project-URL: Bug Tracker, https://github.com/Chuzom/Chuzom/issues
Project-URL: Changelog, https://github.com/Chuzom/Chuzom/blob/main/CHANGELOG.md
Author-email: ypollak2 <ypollak2@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,ai-routing,anthropic,chuzom,claude,claude-code,codex,copilot,cost-saving,cursor,gemini,gemini-cli,llm,llm-proxy,mcp,mcp-server,model-routing,ollama,quota-saver,router,semantic-cache,signal-router,token-optimization,windsurf
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: litellm>=1.50.0
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: textual>=8.2.6
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: code-context
Requires-Dist: tree-sitter-languages>=1.10.0; extra == 'code-context'
Requires-Dist: tree-sitter>=0.23.0; extra == 'code-context'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mutmut>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
Provides-Extra: postgres-test
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres-test'
Requires-Dist: testcontainers[postgres]>=4.0; extra == 'postgres-test'
Provides-Extra: scripts
Requires-Dist: httpx>=0.27; extra == 'scripts'
Requires-Dist: pyyaml>=6.0; extra == 'scripts'
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=5.6.0; extra == 'semantic'
Requires-Dist: sqlite-vec>=0.1.0; extra == 'semantic'
Provides-Extra: sso
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'sso'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Provides-Extra: tokenizers
Requires-Dist: tokenizers>=0.20; extra == 'tokenizers'
Provides-Extra: tracing
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'tracing'
Provides-Extra: tui
Requires-Dist: plotext>=5.2.0; extra == 'tui'
Requires-Dist: textual>=0.80.0; extra == 'tui'
Description-Content-Type: text/markdown

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

<!-- Package -->
[![PyPI version](https://img.shields.io/pypi/v/chuzom-router?style=flat-square&color=4F46E5)](https://pypi.org/project/chuzom-router/)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/chuzom-router?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=ORANGE&left_text=downloads)](https://pepy.tech/projects/chuzom-router)
[![Python](https://img.shields.io/pypi/pyversions/chuzom-router?style=flat-square&color=3572A5)](https://pypi.org/project/chuzom-router/)
[![License: MIT](https://img.shields.io/badge/license-MIT-10B981?style=flat-square)](https://github.com/Chuzom/Chuzom/blob/main/LICENSE)

<!-- Health -->
[![CI](https://img.shields.io/github/actions/workflow/status/Chuzom/Chuzom/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Chuzom/Chuzom/actions/workflows/ci.yml)
[![Last commit](https://img.shields.io/github/last-commit/Chuzom/Chuzom?style=flat-square&color=8B5CF6)](https://github.com/Chuzom/Chuzom/commits/main)
[![Commit activity](https://img.shields.io/github/commit-activity/m/Chuzom/Chuzom?style=flat-square&color=06B6D4)](https://github.com/Chuzom/Chuzom/pulse)
[![Open issues](https://img.shields.io/github/issues/Chuzom/Chuzom?style=flat-square&color=F59E0B)](https://github.com/Chuzom/Chuzom/issues)
[![Code size](https://img.shields.io/github/languages/code-size/Chuzom/Chuzom?style=flat-square&color=64748B)](https://github.com/Chuzom/Chuzom)

<!-- Community -->
[![GitHub Stars](https://img.shields.io/github/stars/Chuzom/Chuzom?style=flat-square&color=F59E0B)](https://github.com/Chuzom/Chuzom/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/Chuzom/Chuzom?style=flat-square&color=64748B)](https://github.com/Chuzom/Chuzom/network/members)
[![Contributors](https://img.shields.io/github/contributors/Chuzom/Chuzom?style=flat-square&color=EC4899)](https://github.com/Chuzom/Chuzom/graphs/contributors)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](./CONTRIBUTING.md)

<!-- Compatibility & flair -->
[![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-D97757?style=flat-square)](https://claude.com/claude-code)
[![MCP](https://img.shields.io/badge/MCP-server-111827?style=flat-square)](https://modelcontextprotocol.io)
[![Code style: Ruff](https://img.shields.io/badge/code_style-ruff-261230?style=flat-square)](https://github.com/astral-sh/ruff)
[![Audited](https://img.shields.io/badge/audit-RELEASE_QUALIFIED-10B981?style=flat-square)](Docs/correctness-reset/03_RELEASE_GATES.md)

---

<p align="center">
  <img src="assets/hero-confluence.webp" alt="A marmot at a river confluence — rushing rapids on one side, deep calm water on the other — where fast and slow streams meet and each finds its path" width="92%"/>
</p>

<p align="center">
  <em>A <strong>Chuzom</strong> is a <strong>confluence</strong> — the place where rivers meet.<br/>
  Fast rapids and deep water, converging, each stream finding its natural path.<br/>
  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.</em>
</p>

<p align="center">
  <strong>⭐ Star on GitHub if Chuzom saves your quota ⭐</strong><br/>
  <em>Help other developers discover automatic LLM routing</em>
</p>

---

**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](#-measured-results-audited)).

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

## Contents

- [The Problem](#the-problem)
- [The Solution](#the-solution)
- [Why People Install This](#why-people-install-this)
- [📊 Measured Results (audited)](#-measured-results-audited)
- [Get Started (60 seconds)](#get-started-60-seconds)
- [How It Works](#how-it-works)
- [Supported IDEs](#supported-ides)
- [Routing at a Glance](#routing-at-a-glance)
- [Agentic Router](#agentic-router)
- [Companion Skill: `/council`](#-companion-skill-council)
- [Session Summary Dashboard](#session-summary-dashboard)
- [Configuration](#configuration)
- [More docs](#more-docs) · [FAQ](#faq) · [Contributing](#contributing) · [License](#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.**

| Prompt | Quota burned | Actually needs Claude? |
|---|---|---|
| *"What does this function return?"* | ✗ Yes | No |
| *"List files matching \*.test.ts"* | ✗ Yes | No |
| *"Write a test for this function"* | ✗ Yes | Probably not |
| *"Re-architect this auth system"* | ✓ Yes | **Yes** |

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!
```

<p align="center">
  <sub><em>🌊 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.</em></sub>
</p>

| Tool | Cost | Best for |
|---|---|---|
| **Ollama** (local) | Free | Simple questions, syntax lookups, file ops |
| **Codex CLI** | Free (via GitHub Copilot) | Code generation, refactors, test writing |
| **Gemini CLI** | Free (via Google account) | Moderate reasoning, explanations, summaries |
| **Claude** | Your subscription quota | Complex reasoning, long context, architecture |

---

## 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.**

<table align="center">
<tr>
<td align="center" width="25%">
  <h3>⏱️ Fewer Quota Walls</h3>
  <p>Route most prompts to free/local models — hit quota limits far less often</p>
</td>
<td align="center" width="25%">
  <h3>✅ Quality Preserved</h3>
  <p>Premium models only when the task truly needs it — measured, not assumed</p>
</td>
<td align="center" width="25%">
  <h3>🛡️ Quota Protected</h3>
  <p>Auto-downgrade near limits. No more rate-limit walls</p>
</td>
<td align="center" width="25%">
  <h3>⚙️ Quick Setup</h3>
  <p>Two commands (<code>pip install</code> + <code>chuzom install</code>); a local provider (e.g. Ollama) unlocks the free-routing savings</p>
</td>
</tr>
</table>

<p align="center">
  <img src="assets/flow-animated.webp" alt="Animated: a marmot resting on a lily pad in calm, gently rippling water at golden hour — the unhurried flow of a session that never hits the wall" width="92%"/>
</p>

<p align="center">
  <em>Fewer walls. Longer flow. The same workflow — just calmer underneath.</em>
</p>

---

## 📊 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):

| Metric | Result |
|---|---|
| **Net cash savings** | **+$0.027** per run (Chuzom ≈ $0.0036 vs GPT-4o ≈ $0.030) |
| **Quality delta** | **−0.21** on a 0–5 judge scale — **within** the 0.5 non-inferiority margin |
| **Exhaustions** (dropped answers) | **0** |
| **Robustness** | held across **4 independent runs** (−0.18 / −0.21 / −0.21 / +0.00) |
| **Verdict** | **RELEASE QUALIFIED** — two consecutive clean audit passes on a frozen commit |

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](Docs/correctness-reset/03_RELEASE_GATES.md) ·
[Benchmark log](Docs/correctness-reset/10_CODEX_QUOTA_BENCHMARK.md) ·
[Audit runbook](Docs/correctness-reset/11_AUDIT_RUNBOOK.md).

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

| Workload | Typical volume | Claude quota preserved | Session runway | Est. cash (pay-per-token only) |
|---|---|---|---|---|
| **Individual developer** — mixed Q&A, edits, small refactors | ~100 prompts/day | ~60–70% | ~2–3× more sessions/day | ~$20–35 / month |
| **Agentic workloads** — `llm_act` tool loops, many execute/verify sub-steps | high (each task fans out) | ~80–90% | ~4–5× | ~$50–150 / month |
| **Heavy Claude Code user** — ~1,000 prompts/week | ~1,000 / week | ~76% | ~4× (1–2 → 6–8 / day) | ~$16–34 / week (~$70–150 / mo) |

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

<details>
<summary>Heavy-user week, expanded</summary>

| Metric | Without Chuzom | With Chuzom |
|---|---|---|
| Prompts to Claude (quota) | ~1,000 / week | ~240 / week |
| Prompts to Ollama (local, free) | 0 | ~520 / week |
| Prompts to Codex / Gemini CLI (prepaid) | 0 | ~240 / week |
| Claude quota consumed | 100% | ~24% |
| Sessions before "usage limit" | 1–2 / day | 6–8 / day |

Directional estimate — not statistically significant. Reproduce the audited figures with
`python -m chuzom benchmark`.
</details>

---

## Get Started (60 seconds)

**1. Install**

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

**2. Wire into your IDE**

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

**3. Add API keys (optional)**

```bash
# 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**

```bash
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](Docs/troubleshooting.md#windows-specific-setup).)

---

## 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).

| Tool | Routing | Status |
|---|---|---|
| 🔵 Claude Code / Desktop | **Push** (automatic) | ✅ Production |
| 🟠 Codex CLI | **Push** (plugin) | ✅ Production |
| 🟣 Cursor | **Pull** + rule nudge | ✅ Production |
| 🔴 Gemini CLI | **Pull** (tool call) | ✅ Production |
| 🟤 GitHub Copilot (VS Code) | **Pull** (agent mode) | ✅ Beta |
| 🌊 Windsurf / Cascade | **Pull** (agent mode) | ✅ Beta |
| 🌙 Kimi Code | **Pull** (MCP tools) | ✅ Beta |

> 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](Docs/ide-setup.md)**.

---

## Routing at a Glance

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

| Complexity | Profile | Tier 1 (cheapest) | → | Fallback |
|---|---|---|---|---|
| **simple** | BUDGET | Ollama (local/free) | Codex · Gemini Flash | Haiku |
| **moderate** | BALANCED | Ollama (local/free) | Codex · GPT-4o | Sonnet |
| **complex** | PREMIUM | Codex CLI | OpenAI o3 · Claude Opus | Gemini 2.5 Pro |
| **deep_reasoning** 🧠 | REASONING | Ollama qwen3 | DeepSeek-R1 · o3 | Claude Opus + thinking |

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](Docs/local-inference.md)), and never hardcodes model names (Ollama dynamic
discovery).

> Full chains, subagent routing, the REASONING profile, model pinning, and every policy →
> **[Routing guide](Docs/routing.md)**.

---

## Agentic Router

> Status: real but maturing. Design + phased plan in [`Docs/agentic-router.md`](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.

```bash
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.

```bash
/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](Docs/session-dashboard.md)**.

---

## Configuration

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

```bash
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](Docs/configuration.md)**.

---

## More docs

| Guide | What's in it |
|---|---|
| [IDE Setup](Docs/ide-setup.md) | Per-IDE setup, push vs pull, the 11-door MCP tool surface |
| [Routing](Docs/routing.md) | Chains, subagent routing, REASONING profile, policies, model pinning |
| [Local Inference](Docs/local-inference.md) | 13+ auto-detected local LLM servers + port overrides |
| [Configuration](Docs/configuration.md) | Full env matrix, enforcement modes, advanced config, CLI |
| [Session Dashboard](Docs/session-dashboard.md) | Dashboard panels + live streaming progress |
| [OKF Integration](Docs/okf.md) | Self-building local knowledge bundle that compounds savings |
| [Agentic Router](Docs/agentic-router.md) | Milestone-Gated Escalating Execution design |
| [Troubleshooting](Docs/troubleshooting.md) | Command-not-found, hooks, Ollama, Windows setup |
| [Correctness Reset](Docs/correctness-reset/03_RELEASE_GATES.md) | The audit: gates, benchmark, verdict |

---

## Benchmarks

The **audited** control-group figures are in [Measured Results](#-measured-results-audited)
(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.

```bash
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](Docs/troubleshooting.md#windows-specific-setup).

**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](Docs/configuration.md#enforcement-modes).

More Q&A in the [Troubleshooting guide](Docs/troubleshooting.md).

---

## Contributing

Full test suite runs on every push (Python 3.10+). Contributions welcome!

- 🐛 [Report bugs](https://github.com/Chuzom/Chuzom/issues)
- 💡 [Start discussions](https://github.com/Chuzom/Chuzom/discussions)
- 🔧 [Read `CONTRIBUTING.md`](./CONTRIBUTING.md)

Chuzom also ships as a [Codex plugin](.codex-plugin/plugin.json) (category *Developer
Tools*).

---

## License

MIT © [The Chuzom Contributors](https://github.com/Chuzom/Chuzom/graphs/contributors)
