{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/hero-banner.png\" alt=\"Cheaplane — keep your premium model on the main thread, offload the grunt work to cheap models with billing that can't cross\" width=\"880\">\n</p>\n\n# Cheaplane 🛣️\n\n> **Keep your premium subscription on the main thread. Offload the grunt work to cheap models — Cheaplane even picks the right one for you. Stop burning premium tokens on boilerplate.**\n\n[![PyPI](https://img.shields.io/pypi/v/cheaplane)](https://pypi.org/project/cheaplane/)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue)\n![MCP](https://img.shields.io/badge/MCP-compatible-purple)\n![Deps](https://img.shields.io/badge/deps-just%20mcp-lightgrey)\n![PRs](https://img.shields.io/badge/PRs-welcome-brightgreen)\n\n<!-- mcp-name: io.github.millennialdreamer/cheaplane -->\n\nCheaplane is a tiny single-file MCP server (~250 lines, stdlib + `mcp` only) that gives your main agent — e.g. **Claude Code on a Max subscription** — one extra tool: **`delegate`**. Your agent keeps doing the thinking (planning, architecture, final review) and hands *replaceable grunt work* — boilerplate code, formatting, translation, summarizing long docs — to cheap models behind a local [LiteLLM](https://github.com/BerriAI/litellm) proxy (DeepSeek, Kimi, Qwen, …). Think of it as **a cheap intern for your premium agent** — it churns out the boring parts while you keep thinking.\n\nThe trick that makes it *safe*: **the delegated calls and your subscription live in physically separate processes and never share credentials.** ([why that matters ⬇️](#billing-isolation-the-whole-point))\n\nThe trick that makes it *effortless*: **auto-routing.** `delegate(task)` picks the right cheap model from the task itself — code → DeepSeek, long docs → Kimi, Chinese → Qwen. ([how ⬇️](#using-delegate))\n\nThe trick that makes it *stick*: **a per-turn reminder hook so your agent doesn't forget the tool exists** — [the part most \"delegate\" tools skip](#make-your-agent-actually-use-it). And a **savings ledger** shows you [what it kept off your quota](#see-what-you-saved).\n\n**See it in action** — your agent hands a chore over; auto-routing sends it to the cheap code model:\n\n```text\ndelegate(\"convert to a TypeScript interface: {id, name, email, isAdmin, roles[]}\")\n```\n\n```ts\ninterface User {\n  id: number;\n  name: string;\n  email: string;\n  isAdmin: boolean;\n  roles: string[];\n}\n```\n\n<sub>↑ a real call's output — not a mockup, and no model picked by hand. That token cost **~90× less** than your premium model, and your subscription quota never moved.</sub>\n\n## The problem\n\nPremium models earn their price on hard problems — but every token counts against your plan, and you burn through quota on *churn*: reformatting JSON, translating UI strings, summarizing a doc you'll read once. The usual \"just use a cheap model\" setups force an ugly choice:\n\n- **Downgrade the whole agent** → you lose main-thread quality on the work that actually matters.\n- **Route everything through an API key** → you stop using the subscription you're already paying for.\n\nCheaplane keeps the sweet spot: **premium main thread for judgment + cheap models for the churn + billing that physically can't cross.**\n\n## How Cheaplane compares\n\nThe popular 2026 move is to swap your *whole* agent onto a cheap model (DeepClaude-style). Great for raw cost — but it downgrades the thread you actually think with, **breaks your other MCP tools**, and doesn't even apply if you're on a Pro/Max subscription. Cheaplane takes the opposite bet:\n\n| | Swap whole agent → cheap model *(DeepClaude-style)* | Everything via one API key | **Cheaplane** |\n|---|:---:|:---:|:---:|\n| Main thread | ⬇️ downgraded | ⬇️ no more subscription | ✅ stays premium |\n| Your other MCP tools | ❌ break | ✅ | ✅ *(it **is** an MCP server)* |\n| Works on a Pro/Max subscription | ❌ API-key only | ❌ replaces it | ✅ built for it |\n| Picks the cheap model for you | ❌ one model for everything | ❌ | ✅ `auto` routing |\n| Shows what you saved | ❌ | ❌ | ✅ `savings` ledger |\n| Billing | merged into one | one per-token bill | 🔒 subscription + cheap, **isolated** |\n\n<sub>Comparison reflects how backend-swap setups (DeepClaude-style) behaved per public reports in mid-2026; specifics vary by tool and can change.</sub>\n\n## How cheap is \"cheap\"?\n\nThe grunt work is the *easy* part — paying premium rates for it is pure waste. Per **million tokens** (public list prices, mid-2026):\n\n| Model | Input | Output | Best for |\n|---|--:|--:|---|\n| Claude Opus *(API, for reference)* | $5.00 | **$25.00** | the judgment work you keep |\n| DeepSeek V4 Flash | $0.14 | **$0.28** | code / formatting |\n| Kimi K2 | $0.60–0.95 | $2.50–4.00 | long docs (very large context) |\n| Qwen | $0.05–0.40 | $0.20–1.20 | Chinese copy |\n\nThat's an output token costing **~$25 on Opus vs ~$0.28 on DeepSeek — about 90× more for work that doesn't need the smarts.** You're on a *subscription*, so you don't pay that $25 directly — your main thread spends *quota*, not dollars. That's the whole point: every routine task you offload is premium quota you keep for the hard problems. *(Summarizing a 40-page doc on DeepSeek Flash runs ~$0.005 — your quota never even notices.)*\n\n<sub>Prices are public list rates, mid-2026, and vary by tier/caching — check each provider. The stable takeaway is the order-of-magnitude gap, not an exact dollar saving.</sub>\n\n## Billing isolation (the whole point)\n\nMost \"save money\" hacks blur your bills together. Cheaplane keeps them physically apart:\n\n```mermaid\nflowchart LR\n    A[\"Main agent<br/>premium subscription\"] -->|\"delegate(task)\"| B[\"Cheaplane MCP<br/>own process, own key\"]\n    B -->|HTTP| C[\"LiteLLM proxy<br/>localhost:4000\"]\n    C --> D[\"DeepSeek / Kimi / Qwen<br/>cheap, pay-per-use\"]\n```\n\nThe Cheaplane process **never imports your subscription provider's SDK, never reads its auth, never touches its OAuth token.** It knows exactly one thing: an HTTP endpoint (your proxy) and its key. Your main thread bills to your subscription; delegated calls bill to your cheap proxy. **The two can't cross — not by policy, by architecture.**\n\n## Quick start\n\n**Fastest path** — Claude Code, one script:\n\n```bash\ngit clone https://github.com/millennialdreamer/cheaplane && cd cheaplane\ncp litellm.yaml.example litellm.yaml          # then: export DEEPSEEK_API_KEY=sk-...\nlitellm --config litellm.yaml &               # start the cheap-model proxy on :4000\nbash setup.sh                                 # deps + register MCP + reminder hook + verify\n```\n\n`setup.sh` is idempotent (safe to re-run): it installs deps, registers the `delegate` MCP server with Claude Code, installs the per-turn reminder hook, and verifies the chain end-to-end. Then start a fresh Claude Code session — done.\n\n<p align=\"center\"><img src=\"assets/setup.png\" alt=\"bash setup.sh — installs deps, registers the MCP server with Claude Code, installs the reminder hook, and verifies the chain end-to-end\" width=\"760\"></p>\n\n**Prefer a package?** Cheaplane is on PyPI — no clone, no path to hard-code:\n\n```bash\npip install cheaplane          # or: uvx cheaplane  /  pipx install cheaplane\nclaude mcp add delegate cheaplane\n```\n\nYou still want the proxy from step 1 below, and the [reminder hook](#make-your-agent-actually-use-it) is worth it — that part needs the repo.\n\n<details>\n<summary><b>Manual setup / what <code>setup.sh</code> does under the hood</b></summary>\n\n<br>\n\n**1. Get an OpenAI-compatible endpoint for the cheap models.** Most people run [LiteLLM](https://github.com/BerriAI/litellm) locally as a proxy in front of DeepSeek / Kimi / Qwen. A minimal config is ~5 lines:\n\n```yaml\n# litellm.yaml — exposes DeepSeek under the model_name \"deepseek\"\nmodel_list:\n  - model_name: deepseek\n    litellm_params:\n      model: deepseek/deepseek-chat        # swap for any provider/model LiteLLM supports\n      api_key: os.environ/DEEPSEEK_API_KEY\n```\n\n```bash\npip install 'litellm[proxy]'\nlitellm --config litellm.yaml        # serves http://localhost:4000\n```\n\nThat `model_name: deepseek` lines up with Cheaplane's default alias, so it works out of the box. (`deepseek` is a built-in LiteLLM provider — no `api_base` needed; you'd add one only for a custom or self-hosted endpoint.) Already have an OpenAI-compatible endpoint (LiteLLM, OpenRouter, Ollama, vLLM…)? Skip this and just point `DELEGATE_BASE_URL` at it.\n\n**2. Install Cheaplane** — from PyPI, or from a clone if you also want the reminder hook and `probe.py`:\n\n```bash\npip install cheaplane        # installs a `cheaplane` command; that's the whole install\n```\n```bash\ngit clone https://github.com/millennialdreamer/cheaplane && cd cheaplane\nuv sync     # or:  python -m venv .venv && .venv/bin/pip install mcp\n```\n\n**3. Register it with your MCP client.** Installed from PyPI — the command is already on your `PATH`:\n\n```json\n{\n  \"mcpServers\": {\n    \"delegate\": { \"command\": \"cheaplane\" }\n  }\n}\n```\n\nFrom a clone — copy `.mcp.json.example` to `.mcp.json` in the repo root and fix the path (or use `claude mcp add`):\n\n```json\n{\n  \"mcpServers\": {\n    \"delegate\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/ABSOLUTE/PATH/TO/cheaplane\", \"python\", \"server.py\"]\n    }\n  }\n}\n```\n\n**4. Verify it end-to-end** — with your proxy from step 1 running (handshake → list tools → a real delegated call):\n\n```bash\nuv run python probe.py\n# ✅ chain works (main → MCP → cheap model → back)\n```\n\n</details>\n\n## Using `delegate`\n\nYour agent now has `delegate(task)` — **routing is automatic**; override only when you want to:\n\n```text\ndelegate(\"convert this JSON to a TypeScript interface: …\")      #  auto → deepseek (code)\ndelegate(\"summarize this 40-page contract: …\")                  #  auto → kimi (very long input)\ndelegate(\"…Chinese text in the task auto-routes here…\")        #  auto → qwen (Chinese copy)\ndelegate(\"translate these UI strings to Japanese\", \"flash\")     #  explicit alias still wins\n```\n\n| alias | good for |\n|---|---|\n| `auto` | **default** — picks one of the below from the task itself |\n| `deepseek` | code / balanced |\n| `mimo` | reasoning / multi-step |\n| `flash` | fast / formatting / translation |\n| `kimi` | long documents (very large context) |\n| `qwen` | Chinese copywriting |\n\nAliases map to your LiteLLM `model_name`s. Point them at your proxy **without editing code** — set the `DELEGATE_MODEL_MAP` env var (a JSON object), or drop a `~/.claude/delegate-model-map.json` (hot-reloaded — no restart needed); editing `MODEL_ALIASES` in `server.py` also works.\n\n<details>\n<summary><b>What to delegate vs keep (rule of thumb)</b></summary>\n\n<br>\n\n**Delegate** (let the cheap model do it):\n- boilerplate / scaffolding from a clear spec\n- mechanical refactors, formatting, lint fixes\n- translation; summarizing or extracting facts from long docs\n- routine prose: changelogs, docstrings, commit messages\n\n**Keep** (you do it yourself):\n- planning, architecture, technical trade-offs\n- **final review of delegated output — always you**\n- talking to the user; judgment calls\n- anything where being subtly wrong is expensive\n\nThe delegated model sees **only your `task` string** — it has no access to your conversation. Make each task self-contained: spec + the actual input + the exact output format you want.\n\n</details>\n\n## See what you saved\n\nEvery delegated call appends one line of **metadata only — never the task content** — to `~/.cheaplane/usage.jsonl`. Ask your agent for `savings` any time (sample output):\n\n```text\nCheaplane savings — all time\n  delegated calls : 184\n  tokens offloaded: ~412,300 in / ~365,800 out\n  premium cost avoided (Opus list): ~$11.21\n  actually spent (DeepSeek-class) : ~$0.16  (≈70× cheaper, in+out blended)\n  last 7 days     : 31 calls, ~$2.04 avoided\n```\n\nNumbers are estimates at public list prices — the real win is the premium **quota** that never left your subscription. The ledger records token counts and model names only; delete the file any time, or set `DELEGATE_NO_LOG=1` to turn logging off entirely.\n\n## Make your agent actually use it\n\nHere's the dirty secret of every \"delegate to a cheap model\" tool: **installing it isn't the hard part — getting your agent to actually *use* it is.** Drop a tool into an agent and, a few turns into a real task, it forgets the tool exists and grinds through the grunt work itself on premium tokens. The instruction sinks down the context; attention moves on.\n\nCheaplane ships the fix in the box — three layers you can stack:\n\n1. **Skill** (`SKILL.md`) — teaches the agent *when* to delegate. Works on any client; passive, so treat it as the baseline.\n2. **A one-line default** in your `CLAUDE.md` / system prompt: *\"Before doing replaceable grunt work yourself, delegate it.\"* Stronger — but a static instruction still drifts down a long conversation.\n3. **A per-turn reminder hook** — the reliable one (Claude Code). It re-injects the nudge on **every** prompt, so the habit never sinks out of view. This is what turns an *installed* tool into a *used* one.\n\n**On other MCP clients** (no `UserPromptSubmit` hook system), use layers 1–2 — wire the one-liner into whatever system prompt your client supports.\n\nInstall the hook — safe and idempotent (backs up your settings, **merges** instead of overwriting, de-dupes on re-run):\n\n```bash\nbash install-hook.sh            # registers hooks/delegate-reminder.sh as a UserPromptSubmit hook\n# verify it's wired up:\npython3 -c \"import json,os;s=json.load(open(os.path.expanduser('~/.claude/settings.json')));print([h['command'] for e in s.get('hooks',{}).get('UserPromptSubmit',[]) for h in e.get('hooks',[])])\"\n```\n\nStart a fresh session, and your agent self-checks every turn: *\"is this replaceable grunt work? → delegate it.\"*\n\n<sub>The reminder costs ~60 tokens per turn — trivially less than the hundreds of premium tokens a single forgotten delegation burns. The hook uses Claude Code's <code>UserPromptSubmit</code> mechanism.</sub>\n\n## Config\n\n| Env var | Default | Meaning |\n|---|---|---|\n| `DELEGATE_BASE_URL` | `http://localhost:4000` | OpenAI-compatible endpoint (your proxy) |\n| `DELEGATE_API_KEY` | `sk-litellm` | key for that endpoint |\n| `DELEGATE_TIMEOUT` | `120` | per-call timeout (seconds) |\n| `DELEGATE_MODEL_MAP` | *(none)* | JSON remapping aliases, e.g. `{\"deepseek\":\"deepseek-v4-flash\"}` — overrides defaults, no code edit |\n| `DELEGATE_LOG` | `~/.cheaplane/usage.jsonl` | where the savings ledger lives |\n| `DELEGATE_NO_LOG` | *(unset)* | set to `1` to disable the ledger entirely |\n\n## FAQ\n\n**Will this leak my subscription credentials?**\nNo. The `delegate` tool runs in its own process and only ever makes a plain HTTP call to the endpoint *you* configure. It never imports your subscription SDK and never sees its auth — see [Billing isolation](#billing-isolation-the-whole-point).\n\n**What exactly does the savings ledger record?**\nOne JSON line per call: timestamp, alias, model name, and token/character counts. **Never the task text, never the model's output.** Delete `~/.cheaplane/usage.jsonl` any time, or set `DELEGATE_NO_LOG=1`.\n\n**How does `auto` decide which model to use?**\nA small deterministic heuristic in `server.py` (`_pick_model`, ~20 lines you can read and tweak): code signals → `deepseek`, very long input → `kimi`, Chinese-heavy → `qwen`, multi-step language → `mimo`, short mechanical chores → `flash`. An explicit alias always overrides it.\n\n**How is this different from just using one API key for everything?**\nWith a single API key you stop using your subscription entirely and pay per token for *all* work — including the hard parts. Cheaplane keeps your subscription as the premium main thread and sends only the cheap, replaceable churn elsewhere.\n\n**Does it work with anything besides Claude Code?**\nYes — any MCP-compatible client (Cursor, Cline, Windsurf, …). The main agent just needs to support MCP tools; see Manual setup for the generic JSON config.\n\n**Do I have to use DeepSeek / Kimi / Qwen?**\nNo. Anything reachable through an OpenAI-compatible endpoint works; the aliases are just convenience labels you can remap with `DELEGATE_MODEL_MAP`.\n\n**Why a proxy instead of calling providers directly?**\nOne endpoint, one key, usage logging, and easy model swaps — and it keeps provider keys out of the MCP server entirely.\n\n## Roadmap & ideas (help wanted)\n\nCheaplane's core stays deliberately tiny — but the surface it opens up is big. Shipped so far: ✅ auto-routing (v0.2), ✅ savings ledger (v0.2). Still worth building — proposals and PRs welcome, and most are small enough to be good first issues:\n\n- **Smarter routing** — the current router is a readable heuristic; better signals (or a learned router) are an open playground.\n- **Richer savings dashboard** — the ledger is plain JSONL; a `cheaplane stats` HTML view would be lovely.\n- **Result cache** — skip re-delegating identical tasks.\n- **Auto-review** — lint/test code that comes back before you trust it.\n- **Batch / parallel delegate** — hand off several chores in one call.\n- **More client adoption recipes** — the reminder hook targets Claude Code's `UserPromptSubmit`; Cursor / Cline / others want their own nudge.\n\n> Design rule: **keep the core single-file and dependency-light — that's the whole point.** Build extensions as opt-in, so the 5-minute read stays a 5-minute read.\n\n## Contributing\n\nIssues and PRs welcome — it's ~250 lines of single-file Python with no heavy deps, easy to hack on. Add a useful model alias, a routing signal, or a client recipe and send it over.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 17555,
  "sha": "bccd7ffbabd16356238dd39fb0aaea3e8d82b5e93abd26b6ab91a3c25f6d84df",
  "repo_slug": "millennialdreamer/cheaplane",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_millennialdreamer_cheaplane_774d1a1f/readme"
}