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 (terminal, IDE, desktop app), Claude Desktop, ChatGPT, Codex, Cursor, Gemini CLI, GitHub Copilot, 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

npx context-doctor fix # the fixes ranked by dollars; applies only the ones you say yes to npx context-doctor spend # one bill across Claude Code, Codex, Gemini CLI and Cursor

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 (see the entry). The registry is a service, not a list in a GitHub repo: the modelcontextprotocol/servers repository holds only reference servers and points to the registry for the rest. Built and maintained by gAI Ventures.

Quick start

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

| Claude Desktop, Cursor or any MCP client | Add the server to the client's MCP config (or install the one-click .mcpb from the latest release in Claude Desktop): {"mcpServers": {"context-doctor": {"command": "npx", "args": ["-y", "context-doctor", "mcp"]}}} | | claude.ai, ChatGPT, phone apps | npx context-doctor instructions --copy, then paste into the app's personal preferences (it tells you where). ChatGPT can also reach the MCP server at a URL (how) | | Your own app on an LLM API | Run npx context-doctor proxy --autopilot and point ANTHROPIC_BASE_URL, OPENAI_BASE_URL (add /v1) or GOOGLE_GEMINI_BASE_URL at the proxy on 127.0.0.1:8787, plain HTTP (exact values). No proxy possible? Wrap the SDK client: withContextDoctor(new Anthropic()) (library) | | Python / RAG pipelines | pip install "git+https://github.com/KushalP1/context-doctor#subdirectory=python" (PyPI release coming), then pack_documents(retrieved_docs, question, budget=4000) trims LangChain or LlamaIndex results to the chunks that matter. Python README | | GitHub pull requests | uses: KushalP1/context-doctor@v0.44.0 comments how much a PR grows CLAUDE.md, AGENTS.md and rules, and can fail over a budget (setup) |

What it does

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

• spend: one bill across Claude Code (subagents and workflow agents included), Codex, Gemini CLI and Cursor, by tool, project, model and day, at list prices (spend and budget).
• 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.
• limits: your plan's 5-hour and weekly windows (Claude Pro/Max, recorded by the status line) and Codex's, the pace and when each runs out, and what 1M tokens of each kind cost in % of the limit, fitted on your own readings with the error shown.
• cache-plan : 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.
• recall (and the recall MCP tool): the few lines of this session's own transcript a question needs, including turns a compaction summarised away and tool output autopilot cleared, with their time and position; secrets masked.
• 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 subagent price (PreToolUse on the Agent tool) shows what a subagent costs before it starts, at your own median for that type (the author's: $3.99 for general-purpose, $1.43 for Explore, 422 runs in 30 days), with the Sonnet price where it would run on Opus or Fable, and a total when launches bunch up. It never blocks.
• 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.
• A session's own price: once a session passes $25, $100 and $500 (subagents included), the every-prompt hook tells you what it has cost and what each message now costs, and that /compact or a fresh session cuts it (docs).
• budget 50/day (or /week): the every-prompt hook in Claude Code, Codex and Gemini CLI says when today's spend passes 50%, 80% and 100% of it, and with --block holds prompts over budget; the status line shows $12/$50 today.
• compact-window: sets Claude Code's own auto-compact window, measured on your history first. Works in the desktop app too.
• cache-ttl: replays your own pauses at a 5-minute and a 1-hour prompt cache and sets Claude Code's promptCacheTtl to the cheaper one (the author's: 7% less main-conversation input at 1 hour; 22% less than the 5-minute default an API key gets). Same content either way, so no quality cost (fixes).
• 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, pri