Cheaplane

Cheaplane 🛣️

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.

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

The trick that makes it *safe*: the delegated calls and your subscription live in physically separate processes and never share credentials. (why that matters ⬇️)

The 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 ⬇️)

The 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. And a savings ledger shows you what it kept off your quota.

See it in action — your agent hands a chore over; auto-routing sends it to the cheap code model:

delegate("convert to a TypeScript interface: {id, name, email, isAdmin, roles[]}")

interface User {

id: number; name: string; email: string; isAdmin: boolean; roles: string[]; }

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

The problem

Premium 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:

• Downgrade the whole agent → you lose main-thread quality on the work that actually matters.
• Route everything through an API key → you stop using the subscription you're already paying for.

Cheaplane keeps the sweet spot: premium main thread for judgment + cheap models for the churn + billing that physically can't cross.

How Cheaplane compares

The 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:

Comparison reflects how backend-swap setups (DeepClaude-style) behaved per public reports in mid-2026; specifics vary by tool and can change.

How cheap is "cheap"?

The grunt work is the *easy* part — paying premium rates for it is pure waste. Per million tokens (public list prices, mid-2026):

That'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.)*

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.

Billing isolation (the whole point)

Most "save money" hacks blur your bills together. Cheaplane keeps them physically apart:

flowchart LR

A["Main agent premium subscription"] -->|"delegate(task)"| B["Cheaplane MCP own process, own key"] B -->|HTTP| C["LiteLLM proxy localhost:4000"] C --> D["DeepSeek / Kimi / Qwen cheap, pay-per-use"]

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

Quick start

Fastest path — Claude Code, one script:

git clone https://github.com/millennialdreamer/cheaplane && cd cheaplane

cp litellm.yaml.example litellm.yaml # then: export DEEPSEEK_API_KEY=sk-... litellm --config litellm.yaml & # start the cheap-model proxy on :4000 bash setup.sh # deps + register MCP + reminder hook + verify

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.

Prefer a package? Cheaplane is on PyPI — no clone, no path to hard-code:

pip install cheaplane          # or: uvx cheaplane  /  pipx install cheaplane

claude mcp add delegate cheaplane

You still want the proxy from step 1 below, and the reminder hook is worth it — that part needs the repo.

Manual setup / what setup.sh does under the hood

1. Get an OpenAI-compatible endpoint for the cheap models. Most people run LiteLLM locally as a proxy in front of DeepSeek / Kimi / Qwen. A minimal config is ~5 lines:

# litellm.yaml — exposes DeepSeek under the model_name "deepseek"

model_list:

• model_name: deepseek litellm_params: model: deepseek/deepseek-chat # swap for any provider/model LiteLLM supports api_key: os.environ/DEEPSEEK_API_KEY

pip install 'litellm[proxy]'

litellm --config litellm.yaml # serves http://localhost:4000

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

2. Install Cheaplane — from PyPI, or from a clone if you also want the reminder hook and probe.py:

pip install cheaplane        # installs a `cheaplane` command; that's the whole install

git clone https://github.com/millennialdreamer/cheaplane && cd cheaplane

uv sync # or: python -m venv .venv && .venv/bin/pip install mcp

3. Register it with your MCP client. Installed from PyPI — the command is already on your PATH:

{

"mcpServers": { "delegate": { "command": "cheaplane" } } }

From a clone — copy .mcp.json.example to .mcp.json in the repo root and fix the path (or use claude mcp add):

{

"mcpServers": { "delegate": { "command": "uv", "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/cheaplane", "python", "server.py"] } } }

4. Verify it end-to-end — with your proxy from step 1 running (handshake → list tools → a real delegated call):

uv run python probe.py

✅ chain works (main → MCP → cheap model → back)

Using delegate

Your agent now has delegate(task) — routing is automatic; override only when you want to:

delegate("convert this JSON to a TypeScript interface: …")      #  auto → deepseek (code)

delegate("summarize this 40-page contract: …") # auto → kimi (very long input) delegate("…Chinese text in the task auto-routes here…") # auto → qwen (Chinese copy) delegate("translate these UI strings to Japanese", "flash") # explicit alias still wins

Aliases map to your LiteLLM model_names. 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.

What to delegate vs keep (rule of thumb)

Delegate (let the cheap model do it):

• boilerplate / scaffolding from a clear spec
• mechanical refactors, formatting, lint fixes
• translation; summarizing or extracting facts from long docs
• routine prose: changelogs, docstrings, commit messages

Keep (you do it yourself):

• planning, architecture, technical trade-offs
• final review of delegated output — always you
• talking to the user; judgment calls
• anything where being subtly wrong is expensive

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

See what you saved

Every 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):

Cheaplane savings — all time

delegated calls : 184 tokens offloaded: ~412,300 in / ~365,800 out premium cost avoided (Opus list): ~$11.21 actually spent (DeepSeek-class) : ~$0.16 (≈70× cheaper, in+out blended) last 7 days : 31 calls, ~$2.04 avoided

Numbers 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 tur