Context Doctor

context-doctor 🩺

See where your AI agent's tokens go, and stop paying for the ones that do nothing.

AI agents re-send their whole context on every message: old tool output, pasted files, long instructions. A 500k-token session pays for all of it again each time, and at full price after a coffee break, when the prompt cache has expired. context-doctor measures that waste on your own sessions, in dollars, and removes it at the moments it pays: before it enters the context, while it sits there, and on every request. It runs on your machine, needs no API key, sends no telemetry, and works with Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, any app on the Anthropic, OpenAI or Gemini API, and CI. MIT licensed, Node 20+, macOS, Linux and Windows.

npx context-doctor savings     # what your recent sessions cost, and what each fix would have saved

Which context-doctor is this? Several projects share the name. This one is context-doctor on npm and io.github.KushalP1/context-doctor in the official MCP Registry. Built and maintained by gAI Ventures.

Quick start

Pick where you work. Each takes about a minute and is fully reversible.

What it does

Measure, in dollars, on your own history (profiling)

• savings: what your recent Claude Code sessions cost and what each fix below would have saved, replayed request by request against what you were billed.
• overhead: what every request re-reads before your message (system prompt, tools, MCP servers, CLAUDE.md, rules, memory), each file priced per month.
• tasks, reads, subagents, compactions: cost per commit; files read into session after session; whether each subagent was cheaper than the same steps in the parent; whether sessions work worse after compacting.
• cache-misses: requests that re-wrote the prompt cache while it should still have been warm, priced, by model and context size, with the cause where the transcript shows one.
• cache-plan <request.json>: where an Anthropic API request should carry cache_control, and what it saves over N calls.
• session, watch, analyze, report, dashboard: token breakdown and wasted-context findings for any session, conversation file or agent trace.

Keep waste out of the context (pack and overhead)

• pack (and the pack_context MCP tool): only the chunks of a big document, PDF, log or codebase that a question needs, within a token budget, instead of the whole thing.
• overhead split: turns a heavy CLAUDE.md or memory file into a lean one plus a reference file the agent opens when needed, word for word, nothing lost.
• ci and the GitHub Action: review memory-file growth like any other cost.

Remove waste automatically

• A model-switch warning (PreModelSwitch, Claude Code 2.1.251+) shows what a /model switch costs before it happens: the whole context re-written into the new model's cache.
• A compaction hook (PreCompact) tells each Claude Code compaction what the session cannot lose (files changed, open tasks, your instructions, failing tests), so compacting saves tokens without losing the thread.
• An every-prompt hook (Claude Code, Codex, Gemini CLI; Cursor after each tool call) tells the model its real context size and the largest waste, and offers /compact when you return to a big session after the cache expired.
• compact-window: sets Claude Code's own auto-compact window, measured on your history first. Works in the desktop app too.
• Autopilot: a local proxy (or SDK wrapper) that clears stale tool output only when the prompt cache is cold, so a request never costs more.

What it saves

Measured, not modelled, on every Claude Code session on the author's machine (mostly Opus 5 and Fable 5 with the 1M window), priced the way the prompt cache bills it (cached reads at each model's read rate, 2.5-10% of input; writes 1.25x input for the 5-minute cache, 2x for the hour) at API list prices. Re-measured on 2026-10-13 with each request at its own model and current prices (Opus 5.5 is $4 per million input tokens with $0.20 reads). context-doctor savings runs the same measurement on yours.

1. Compacting when you come back (every Claude Code surface, desktop app included). 133 days, 479 returns to a session over 150k tokens after its prompt cache expired (65 idle minutes on the 1-hour cache, 10 on the 5-minute one that Claude Code 2.1.295 often writes); median context at the return, 522k tokens.

Each return counts only the messages up to the next return, and the compaction request is charged as a cost. Not counted: files the model may re-read after compacting, and what the summary leaves out. That is why this is advice with the numbers attached, not something done for you.

2. Autopilot (Claude Code in a terminal or IDE, API apps). 133 days, 67 sessions, replayed through the shipped autopilot code with real timestamps:

30 of 67 sessions save something, the best 34.9%: long sessions that go idle are where the money is. These sessions ran in the desktop app, which autopilot cannot reach, so for the author this is what the same sessions would have saved in a terminal; context-doctor savings separates the two for you. How it works →

3. Compacting earlier (automatic, every Claude Code surface, desktop app included). The offer in 1 is advice, and on the author's machine it was followed 1 time in 33. Claude Code has a native setting that needs nobody to follow anything: autoCompactWindow in ~/.claude/settings.json makes it compact as if the window were that size. context-doctor compact-window replays each session request by request at several sizes, priced as the cache bills (each simulated compaction pays its own request and a 20k-token summary at the output rate), and changes nothing until you pick one:

41 sessions. The cost is real: each compaction replaces the session's history with a summary, so a smaller window trades detail for money. That is why the command shows the table first and sets a window only when you name one (context-doctor compact-window 400k; off undoes it, and a backup of settings.json is kept).

Also measured:

• pack: 9 of 10 questions about this repository answered from 0.6% of its tokens. How →
• Counting Claude correctly: current Claude models pack 2.75 characters per token on prose (2.4 on code), not the 4 most tools assume: Claude counts about 40% more tokens than the usual 4-characters rule (~45% on prose, ~33% on code). context-doctor accuracy re-checks the ratio on your own sessions. Why →

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 dollars as the size of the effect, not as your bill.

Where it works

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.

The MCP server hands these standing rules, verbatim, to every chat where it is enabled (Claude Desktop, Cursor and Claude Code put them in front of the model):

1. When asked about tokens, cost, speed or limits, and once at ~30 turns or 3+ large pastes: call profile_context BEFORE answering; act on its top finding. In a chat app pass a sketch (turns + big blocks). Do not estimate token counts yourself.
2. Summarize any paste or tool result over ~2k tokens into the points you need; keep it verbatim only to edit or quote it exactly.
3. Refer to earlier content by name; never re-quote it or inline base64.
4. To answer from a big file or folder you won't edit, call pack_context with the question; don't read it whole.
5. If optimize_context returns a pruned-turns digest, write its ≤150-token summary.

Commands

Privacy: everything runs on your machine. No API key is needed for anything core, nothing is sent anywhere, and no telemetry is collected; the proxy forwards your app's own credentials untouched and holds none of its own.

What's new

• 0.35 Cache misses, a price before a model switch, and a QA pass fixed: context-doctor cache-misses finds requests that re-wrote the prompt cache while it was still warm (on the author's history: 390 such misses, $1,925 above the cache-read price, 28% of all cache writes; claude-sonnet-5 missed on 10.4% of warm requests, claude-opus-5-5 on 0.11%) and says which model versions miss less; savings mentions them when they add up. On Claude Code 2.1.251+ a PreModelSwitch hook shows what a /model switch will cost before it happens. pack no longer reads .env, .npmrc, private keys or other credential files unless you pass --include-secrets, refuses ~/.ssh-style folders, and survives unreadable files. Fixed from a QA pass: rc values warned as ignored were applied, near-duplicates were counted per pair (781 findings), autopilot's cleared results leaked between conversations reusing tool ids, a malformed config stopped uninstall midway, and more (list).
• 0.34 Native idle compaction, automatic caching, Codex and Cursor fixes: the cold-resume offer steps aside for Claude Code's own idle compaction (silent after it, still there for the 5-minute caches and sessions under 200k it skips), uses Claude Code's SessionStart verdict and price on a resumed session, and no longer offers /compact on a conversation that was just compacted. cache-plan uses Anthropic's automatic caching for the conversation's moving end and prices reads at each model's own rate. Codex on an API key is routed by autopilot on through openai_base_url (Codex no longer reads OPENAI_BASE_URL); ChatGPT sign-in is left alone. The OpenAI proxy adds a stable prompt_cache_key per conversation where the app sent none (models before GPT-5.6). Cursor gets postToolUseFailure and sessionStart hooks, and doctor says what your Cursor version does with the guidance. Measured and dropped: Anthropic's server-side tool-result clearing (7 to 14 of 37 replayed sessions more expensive). Re-run context-doctor install to add the new hooks.

Every release: docs/whats-new.md.

Documentation

• What install does: every file it writes, what runs in each session after, and when you need MCP
• Autopilot: how it clears stale tool output, and why it never costs more
• The proxy: autopilot and the optimizing mode for your API apps, /stats, cache advice, a public URL for Cursor
• Chat apps: Claude Desktop, ChatGPT, claude.ai and the phone apps; what acts by itself and what only nudges; the MCP tools
• Profiling: conversations, sessions, prompt-cache economics, subagents, report, sharing a profile safely
• Pack and overhead: keep big documents and fixed overhead out of the context
• Detectors and fixes: what the profiler finds and what each optimizer strategy changes
• Library: profileConversation, optimizeConversation, packContext, withContextDoctor
• Budgets and CI: the GitHub Action and .contextdoctorrc
• Editor and status line: the VS Code / Cursor extension and Claude Code's status bar
• Token counts: why counts are "~", how the Claude ratios were measured, exact counts
• Performance: what context-doctor itself costs
• Experiment: does a smaller context actually help? Measure it
• What's new, ,

Contributing

Issues and PRs welcome — see CONTRIBUTING.md for the rules that keep this tool trustworthy, how to run the checks, and how releases are made. What comes next is in ROADMAP.md: the research items and the steps waiting on the owner's accounts (PyPI, the editor extension's marketplaces, a signed Desktop bundle, the Glama listing).

License

MIT © gAI Ventures