context-doctor 🩺

Keep every AI session's context lean, automatically, without ever making it more expensive.

Long agent sessions fill up with tool output nobody reads again: file dumps, shell logs, search results, screenshots. You pay for all of it on every request, the model gets slower, and it drifts as the window fills. context-doctor measures that, and with autopilot it removes it from every Claude Code (and GPT API) request on your machine, only at moments when doing so costs nothing extra.

• 9.8% less input cost, no session worse. Replaying 130 days of the author's real Claude Code use (43 sessions) through the shipped code: 3.8 billion input tokens not sent, $4,694 saved at API list price, about $1,080 a month, and not one session more expensive. Up to 37.7% on a long session. What it saves →
• Counts Claude correctly. Current Claude models pack 2.75 characters per token, not the 4 most tools assume; estimates built on 4 undercount Claude by about 40%. The ratios here were measured from the API's own counts, and context-doctor accuracy re-checks them on yours. How →
• Works where you work: Claude Code, Cursor, Codex, Claude Desktop, any Anthropic or OpenAI API app, VS Code, CI. macOS, Linux and Windows, Node 20+.
• Local and keyless. No account, no telemetry, no API key. Your own login passes through untouched. MIT.

Built and maintained by gAI Ventures.

Quick start

See what it would save you first (no install, reads your local Claude Code history):

npx context-doctor savings

What autopilot would have saved you (last 30 days, 53 Claude Code sessions)
────────────────────────────────────────────────────────
Input you were billed for           $11,205   (from the usage your transcripts record)
Autopilot would have cut             $1,396   12.5%, 1.2B tokens not sent
Sessions made more expensive              0
Biggest win                            $503   tech-Whatsit (31% of that session)

That is the author's machine. Yours is computed the same way: every recent session replayed request by request through the shipped autopilot code, against what your transcripts show you were actually billed.

Then install it, whichever way suits you:

# Everything, every app it finds (Claude Code, Cursor, Codex, Claude Desktop)
npm install -g context-doctor
context-doctor install
context-doctor autopilot on     # every new Claude Code session keeps its context lean

# Or as a Claude Code plugin, from inside Claude Code
/plugin marketplace add KushalP1/context-doctor
/plugin install context-doctor@context-doctor

The plugin brings the every-prompt check, the MCP tools, and /context-doctor:savings, /context-doctor:checkup and /context-doctor:autopilot. It needs no npm step: the MCP server ships as one self-contained file, so it also works on Claude Code versions that do not install plugin dependencies.

context-doctor autopilot status shows what autopilot did; context-doctor doctor checks the whole setup. Everything is reversible: context-doctor autopilot off, context-doctor uninstall, or /plugin uninstall.

Where the tokens go
────────────────────────────────────────────────────────
Tool results      ████████████████░░░░░░░░░░░░  57%  ~41k
System prompt     ██████░░░░░░░░░░░░░░░░░░░░░░  21%  ~15k
Assistant replies ████░░░░░░░░░░░░░░░░░░░░░░░░  13%  ~9.4k
User messages     ██░░░░░░░░░░░░░░░░░░░░░░░░░░   9%  ~6.5k

Findings (4)
────────────────────────────────────────────────────────
✖ Message #12 contains a base64/binary blob (~8.2k tokens). [save ~7.4k]
   → Never put base64 in text content — use the provider's file/image APIs.
▲ Tool result at message #7 (web_search) is ~6.1k tokens. [save ~4.9k]
   → Truncate or summarize large tool outputs before they enter history.

What it saves

Measured, not modelled: every Claude Code session on the author's machine from 18 May to 25 September 2026 (43 sessions, 130 days, mostly Opus 5 and Fable 5 with the 1M window) was replayed request by request through the shipped autopilot code, with the real timestamps, and priced the way the prompt cache bills it (cached reads 0.1x, writes 1.25x). Run it on your own history with node scripts/replay-autopilot.mjs.

How it spreads: the median session saves 1.9%, the best 37.7%. Short sessions barely change, because they rarely pile up 20k tokens of stale tool output before they end. Long sessions are where the money is: on this machine 94% of input cost came from requests above 200k tokens, and those are the requests autopilot makes smaller. Savings scale with how long your sessions run and how much they read, so a lighter user saves proportionally less, and never pays more.

On a Claude subscription you do not pay list price; the same tokens come out of your usage limit instead. Anthropic does not publish how limits weight cached tokens, so read the dollar column as the size of the effect, not as your bill. The token column holds either way, and every request that is 9% smaller is also faster to first token and further from auto-compaction.

What is not counted here: the proxy's full optimizer for your own API apps, the hook's guidance to the model, and fixes you make from session findings. Those save more on top, but they depend on what the model or you do with the advice, so they are not in this table.

What happens on each platform

Not claimed, because no process on your machine sends those requests: trimming inside Claude Desktop chat, claude.ai, ChatGPT, Cursor's own subscription models, or Codex signed in with ChatGPT. Those get the rules and the measurements above, not autopilot.

What's new

• 0.20 Autopilot: stale tool output cleared from every Claude Code request, only when the prompt cache is cold, so it cannot cost more (measured: 9.8% less input cost, ~$1,080 a month on the author's usage, no session worse); runs as a login service on macOS, Linux and Windows; now also for GPT via OpenAI's Chat Completions and Responses APIs.
• 0.21 See it before you install it: npx context-doctor savings replays your own recent sessions through autopilot and shows what it would have saved, against what you were actually billed. Install as a Claude Code plugin from inside Claude Code. Ready for the official MCP Registry (io.github.KushalP1/context-doctor), which every release now publishes to; any MCP client can launch it as npx -y context-doctor mcp.
• 0.20.1 Releases that finish themselves: one tag publishes to npm and creates a GitHub release with the Claude Desktop bundle (signed when a certificate is configured); the editor extension is ready for the VS Code Marketplace and Open VSX.
• 0.19 Measured Claude tokenizer: estimates were 40% low for Claude; fixed from the API's own counts, with a per-model check in accuracy.
• 0.18 proxy --token for putting the proxy on a public URL safely. 0.17 Claude Desktop: a profile_context the model can afford to call from chat, .mcpb bundle, standing preferences for web and mobile. 0.16 Codex. 0.15 Cursor.

Full history with the measurements behind each change: ROADMAP.md.