context-doctor
Profiles and optimizes OpenAI chat conversation contexts, providing token breakdowns, duplicate content removal, base64 stripping, and in-flight API request optimization via a proxy for GPT and ChatGPT.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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, Cursor, Copilot CLI, OpenCode and ClineWhich context-doctor is this? Several projects share the name. This one is
context-doctoron npm andio.github.KushalP1/context-doctorin the official MCP Registry (see the entry). The registry is a service, not a list in a GitHub repo: themodelcontextprotocol/serversrepository holds only reference servers and points to the registry for the rest. Built and maintained by gAI Ventures.
Quick start
See it first, nothing installed: in a terminal, npx context-doctor reads your last 30 days of Claude Code sessions on this machine and shows what the fixes with no quality cost would have saved, as one total, then asks once: y applies them all, npx context-doctor fix undo puts them back. The fixes that trade something (compacting earlier, the subagents' model) are listed with their dollars and the command for each.
Pick where you work. Each takes about a minute and is fully reversible.
You use | Do this |
Claude Code (terminal, IDE, desktop app) | Inside Claude Code: |
Everything on this machine at once |
|
Claude Desktop, Cursor or any MCP client | Add the server to the client's MCP config (or install the one-click |
claude.ai, ChatGPT, phone apps |
|
Your own app on an LLM API | Run |
Python / RAG pipelines |
|
GitHub pull requests |
|
Related MCP server: Context Engine
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, Cursor, Copilot CLI, OpenCode and Cline, by tool, project, model and day, as billed at list rates; past your plan's limit, what Claude Code ran on usage credits (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. And the cold returns (back after the cache expired): each one as billed, compacted on return, and kept warm by a cache read every 55 minutes, by how long you were away; what keeping warm for up to 1-8 hours would have netted; and a compacted segment the Desktop app put back (#107157).limits: your plan's weekly and 5-hour windows (Claude Pro, Max and Ultra, which has no 5-hour window; recorded by the plugin's mod, the status line or the proxy) and Codex's, the pace and when each runs out, what 1M tokens of each kind cost in % of the limit, and for each weekly window the API-equivalent dollars and tokens per 1%, by entrypoint and model, with every move in that figure dated, and, when a limit ran out and Claude Code kept going on usage credits, when and about how much.limits --reportprints it as a block to paste into a bug report, with no prompts, paths or ids.cache-plan <request.json>: where an Anthropic API request should carrycache_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 thepack_contextMCP 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 therecallMCP 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.ciand 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/modelswitch costs before it happens: the whole context re-written into the new model's cache.A subagent price (
PreToolUseon 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
/compactwhen 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
/compactor 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--blockholds 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'spromptCacheTtlto 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.
Net saving had you run | $2,993 (about $675 a month) |
Returns where it paid off | 342 of 479 |
Worst single case | −$1.79 (a session left a few messages later) |
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:
Without autopilot | With autopilot | Saved | |
Input cost at API list price | $11,347 | $9,905 | $1,442 (12.7%, about $325 a month) |
Sessions made more expensive | 0 of 67 |
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:
Window | Input cost, last 30 days | Saved | Compactions a week |
as now (~970k) | $3,648 | 4.7 | |
600k | $2,242 | $1,405 (39%) | 6.5 |
400k | $1,814 | $1,833 (50%) | 14.2 |
300k | $1,664 | $1,983 (54%) | 25.2 |
200k | $1,501 | $2,146 (59%) | 48.1 |
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 accuracyre-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
Where you work | Automatic, every request | What you get on top |
Claude Code in the terminal, VS Code or JetBrains | Autopilot clears stale tool output (cold cache only, never more expensive). Hook on every prompt: real context size, largest waste, and a | Install via npm or as a plugin. Status bar context meter, |
Claude Code in the desktop app's Code tab | Hooks, as above, the cold-resume | Same as above, and the plugin's mod: |
Cursor (agent) | A native after-tool-call hook ( | MCP tools, editor status bar extension, |
Codex (ChatGPT app's Codex tab, IDE extension, CLI) | Every-prompt hook with the API's own token counts | MCP tools, skill, |
Gemini CLI | Every-prompt hook ( | MCP tools, |
GitHub Copilot (Copilot CLI, the Copilot app, VS Code agent sessions) | A session-start hook ( | MCP tools ( |
Your own apps on the Anthropic, OpenAI or Gemini API | Autopilot on | Exact usage and cache hit rates in |
Claude Desktop chat | The six standing rules below, sent to every chat (whether classic Chat shows them to the model is unverified, why); one cheap | One-click |
claude.ai, ChatGPT, the phone apps | Your account's standing preferences, pasted once (Quick start) | Profile an exported chat with |
CI |
|
|
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 (Cursor and Claude Code put them in front of the model; for Claude Desktop's classic Chat that is unverified):
When asked about tokens, cost, speed or limits, and once at ~30 turns or 3+ large pastes: call profile_context BEFORE answering; in a chat app pass a
sketch. Act on its top finding. Do not estimate token counts yourself.When a chat grows long, offer a handoff once (save_handoff): only a new chat cuts its history.
Summarize any paste or tool result over ~2k tokens into the points you need.
Refer to earlier content by name; never re-quote it or inline base64.
For a big file you won't edit, call pack_context with the question; don't read it whole.
If optimize_context returns a pruned-turns digest, write its ≤150-token summary.
Rules 1-4 end exactly at character 512, the part ChatGPT's guide says must stand alone.
Commands
Command | What it does |
| Wire (or remove) everything it finds: the MCP server for Claude Desktop, Claude Code, Cursor, Codex, Gemini CLI, Google Antigravity and GitHub Copilot; the Agent Skill (Claude Code, Codex, Antigravity); the every-prompt hook (Claude Code, Codex, Gemini CLI's |
| Every lever ranked by what it would have saved on your last 30 days (compact earlier, the cache lifetime, autopilot, MCP tool search, MCP servers set to load up front, the Desktop app's own tools kept behind tool search through the plugin's mod, unused servers, the subagents' model, long Bash output to a file, Codex's auto-compact limit, subagent progress summaries), with what each costs in quality; applies one only on a yes (the subagents' model and the two MCP deferrals only when named), |
| One bill across every tool on this machine: Claude Code (main conversation and subagents), Codex, Gemini CLI, Cursor (an estimate: no cache split), Copilot CLI (with the AI credits it counted), OpenCode and Cline, by tool, project (or repository or branch), model and day; |
| A spend budget the every-prompt hook applies: a line at 50%, 80% and 100%, and with |
| Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes, including which surfaces autopilot can reach and any other program on its port, and whether extra usage (usage credits past a plan's limit) is on |
| What your recent Claude Code sessions cost, and what |
| Every new Claude Code session started in a terminal or IDE goes through the local proxy, which clears stale tool output only when the prompt cache is cold: measured 12.7% less input cost, no session worse (details) |
| Local proxy for your own Anthropic, OpenAI and Gemini API apps: clears stale tool output only when the prompt cache is cold, so it never costs more. Plain |
| Replay your last 30 days at auto-compact windows from 200k to 800k: input cost, saving, and how many more compactions each means. |
| The main conversation's (or subagents') prompt cache lifetime: what 5 minutes and 1 hour would each have cost on your last 30 days, then set or remove |
| The ~190-token standing rules (~130 on GPT) for claude.ai / ChatGPT preferences, for web and phones where no server runs |
| Handoffs saved from chat apps (the |
| The MCP server as a subcommand, for clients and registries that launch |
| The MCP server itself — stdio by default (what the installer wires); |
| Profile a Claude Code session: live context, findings, measured tokens and prompt-cache economics, where the wall clock went per tool, output's and reasoning's share of the cost, repeated identical (polling) tool calls priced, what its subagents cost (their own windows, your bill; never in the parent's profile), and Claude Code's own figure for it (its |
| Live monitor of a growing session transcript or agent trace (Claude Code / Codex JSONL, or a plain OpenAI/Anthropic conversation JSON file): token/cost line per change, findings as they appear |
| Profile a chat from Cursor's local history (both storage formats) |
| Profile a conversation: token breakdown, findings, cost + latency estimates. |
| Apply the safe fixes; add |
| Compare two profiles: what moved by category, which findings were resolved or introduced, and what it saves in money and latency |
| What every request re-reads before your message: measured first-request size (Claude Code, Codex and Gemini CLI sessions), each memory file (CLAUDE.md and imports, rules, auto memory, AGENTS.md, Cursor rules, GEMINI.md) priced per month, MCP calls per server; each session's and subagent's start per entrypoint (Desktop app, terminal, SDK) and subagent type, priced over the period, with the MCP tool definitions sent whole and whether any setting defers them; |
| Per project, the MCP servers and skills its sessions never used in n days; |
| Move a memory file's big or code-heavy sections word for word to |
| Only the chunks of big documents, logs or code a question needs, ranked and fit to |
| Search this session's own transcript on disk (Claude Code or Codex; turns before a compaction and tool output cleared from the context included) and print the best excerpts with time and position, secrets masked. Never another project's session unless named with |
| Cost per commit, per project: each session priced from its recorded usage against the commits it made |
| Files read into session after session: reads, tokens, cost, and whether a CLAUDE.md summary or |
| Which subagents paid for themselves: each one's bill vs the same steps run in the parent session (read through the transcript cache: 15 s to 0.3 s warm on the author's machine) |
| Do sessions work worse right after compacting? Re-reads, tool errors and your corrections, before vs after each compaction |
| Requests that re-wrote the prompt cache within its lifetime (no compaction between, previous context over 20k, over 60% of it written again): priced above the cache-read rate, by model and context size, with the cause where visible and the model versions that miss less; by Claude Code version, with step changes after an upgrade flagged (the 1-hour cache share, the first request's size, a model's miss rate). Then the cold returns, each replayed as billed, compacted on return and kept warm (a cache read every 55 min while away, 4.5 on a 5-minute cache), by time away (<1h to >8h); keeping warm for up to 1, 2, 4 and 8 hours priced with every ping a timer would send; and #107157's re-added compacted segment with its re-write; |
| Your plan's limits in their own unit: each window's %, pace and run-out time (Claude's weekly and 5-hour windows, from the readings the plugin's mod, the status line or the proxy record; Ultra has no 5-hour window; Codex's from its rollouts), and % of the limit per 1M tokens of input, cache read, cache write and output, fitted on your readings with the fit's error; too-thin data is said to be thin, never quoted. Each weekly window, reset to reset: API-equivalent $ and tokens per 1%, split by entrypoint ( |
| Where an Anthropic API request should carry |
| How much of what you are billed for is visible in your transcript (the fixed harness baseline, per-turn injected content), plus a tokenizer check: real chars/token per model from the API's own counts, next to the ratio the estimator uses |
| Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, how often the cold-resume |
| Local savings dashboard on 127.0.0.1: tokens saved per day, sessions by context in use vs recoverable, budget status |
| Memory files (CLAUDE.md, AGENTS.md, GEMINI.md, rules, their imports) at HEAD vs a base commit; exit 1 over budget. What the GitHub Action runs (details) |
| Write a |
| Run one task twice from the same commit, in a fresh session and forked from an |
| Does a lever cost quality? Eight small coding tasks, each a tiny repository scored by a hidden check, run with and without the standing rules, autopilot's clearing, |
| Claude Code status bar: live context vs window, cache share, cost, and (Claude Code 2.1.251+) until when the cache is warm and what the next turn costs once it is cold. Wired by |
| The every-prompt hook (Claude Code, Codex, Gemini CLI, Cursor) and Claude Code's compaction hook, registered by |
| Print the installed version. |
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.
Speed: the history reports read each transcript once per run and keep what they took from it (token counts, times, ids, no message text) in ~/.cache/context-doctor, so a second fix or savings answers in under a second and later runs read only what was appended. CONTEXT_DOCTOR_NO_CACHE=1 keeps nothing; uninstall removes it (details).
What's new
0.49.1 The Desktop band off by default, and the rest of Claude Code's figure explained: the band above the prompt in the Desktop app no longer shows unless
CONTEXT_DOCTOR_MOD_BAND=cold(a cold return, with Compact first) oralways; the mod still records limits and cost. Subagent replies Claude Code 2.1.284-2.1.299 never finished writing are counted, and the gap to Claude Code's own cost names its prompt suggestions and requests that hung (details).0.49 Count what Claude Code counts, cold returns, limits you can paste, a Desktop usage pane, and teams:
spendanddoctorshow Claude Code's own cost (itscost-state) beside ours, 2% apart on the author's 30 days, and count the advisor's calls and replies a server-side fallback replaced.cache-missesreplays every return after the cache expired three ways (as billed, compacted, kept warm) by time away (the author's: $894 in 183 returns), and the mod's/context-doctor-keep-warmkeeps it warm on request only, capped in hours and dollars.overheadprices every session's and subagent's start ($455 a month here) andfixgainsmcp-defer.limitsgives dollars per 1% per weekly reset with the moves dated,limits --reporta block for a bug report, and handles Ultra (no 5-hour window)./context-doctor-usageis a usage pane in the Desktop app.spendreads Copilot CLI, OpenCode and Cline, splits--by repo|branch, and--export/spend mergeadd up a team's totals with no prompt or path (details).0.48 Directory-ready, quality on your own plan, and MCP SDK v2: a build of the plugin for Anthropic's directory (strict-clean, with and without the mod);
ab --via claude-codemeasures the subagent lever on your own sign-in, no API key; the price check covers OpenAI, Google, Codex and Gemini CLI and warns before a price ends; the MCP server speaks protocol 2026-07-28 to Claude Code and the old handshake to everyone else. Fixed: installing the plugin from the marketplace no longer pulls 80 MB of build tools into Claude Code's cache (details).0.47 One keystroke to a saving, the mod through
install, a weekly live check, and an audit of 0.46: a barecontext-doctorin a terminal shows the fixes that cost no quality as one monthly total and asks once (the author's: $469 a month: long Bash output to a file, the 1-hour cache). On Claude Code 2.1.286+,installenables the plugin, so npm users get the mod too (limit readings and Claude Code's own cost after each turn, Compact first,/context-doctor-fix). A weekly canary runs the plugin and mod in the newest Claude Code against a local mock API.spendestimates compaction requests and, for terminal sessions, subagent progress summaries, andfixcan switch the summaries off. An audit fixed, among others, the GitHub Action's YAML (it could not load), programs planted in a cloned repository running on Windows,pack_contextopening network shares, a re-pricing gap after upgrades, and a test that would have failed from 2026-12-16 (details).0.46 Fable 5.2, the Desktop app, and an audit: Claude Fable 5.2 is priced (0.45 read it 1.5x too high); managed
modelPricingis honoured; a check catches new models without a price. The plugin's new mod brings limit readings, Claude Code's own cost and/context-doctor-fixwith Apply and Undo buttons to the Desktop app, VS Code and the terminal, and a cache-expiry band with Compact first to the Desktop app and the terminal (Claude Code draws a mod's band on no other surface) (Desktop, details).0.45 Price what is billed, and a security pass: fast mode, US-only inference, Haiku 5.5's long-prompt rates, web searches and OpenAI's and Gemini's long-prompt tiers are priced per request in every report, and prices that end on a known day say so. A security pass fixed a cloned repository approving its own MCP servers for
overhead --mcp, a PDF's name running as a command throughpackon macOS, the agents' API-key configs being packed, and the proxy answering a DNS-rebinding page (details).0.44 Workflow agents on the bill, current prices, and an audit: Claude Code's workflow agents were in no report: on the author's last 30 days $1,494 of $5,542.
spend, the budget, a session's price,subagentsandfixnow count them, andspendequals an independent sum of every transcript to the cent. Prices re-read from each provider (Sonnet 5.5's cache read $0.10, gpt-5.5 $5/$30, the gpt-6 family); estimates are labelled. An audit fixedoverhead --mcplaunching a cloned repository's unapproved MCP servers,pack_contextreturning the agents' sign-in files, and more (details).0.43 Long tool output,
fixfor Codex, and a session's price: every Bash result stays in the conversation and is re-read on every later message until a compaction;fixnow replays them at lower caps and, on a yes, sets Claude Code'sbashOutputMaxChars, so longer output goes to a file the model can still open after a 2,000-character preview (the author's 30 days: $323 less at 8k, 9% of input).fixalso works for Codex: it replays your rollouts at earlier auto-compact limits and setsmodel_auto_compact_token_limitinconfig.toml, on a machine with only Codex too. And the every-prompt hook now tells you once when a session passes $25, $100 and $500, with what each message costs from there (the author's: 15 sessions passed $25 in 30 days and spent $3,369 after).0.42 An audit of 0.41: each Codex request counts once (forks repeat their parent's), the budget no longer double-counts a reply streamed across midnight, unpriced models show as such instead of $0, Cursor is read after it quits, and
CODEX_HOMEis followed everywhere.fix's subagent lever reads agent files the way Claude Code merges them, and every writer ofsettings.jsontakes one lock, so concurrent runs lose nothing (details).0.41 One bill, a budget, and the subagents' model:
context-doctor spendputs Claude Code (subagents included), Codex, Gemini CLI and Cursor on one bill by tool, project, model and day.context-doctor budget 50/dayhas the every-prompt hook tell you at 50%, 80% and 100%, and with--blockholds prompts over budget; the status line shows$12/$50 today, at about 5 ms a prompt.fixgainssubagent-model: subagents run on your main conversation's model (Opus or Fable included), andCLAUDE_CODE_SUBAGENT_MODELset to Sonnet 5.5 would have cost the author $632 less in 30 days (38% of the subagents' $1,658); it changes the model, so it is applied only when you name it, andfix undoreverts it.0.40 Reports in under a second:
fix,savings,compact-window,cache-ttl,cache-missesandoverheadread each transcript once and keep what they took from it in~/.cache/context-doctor, so a second run reads only what was appended:fix23.5 s → 0.4 s,savings41 s → 0.6 s on the author's 2.7 GB history, every figure unchanged (details). Also from a QA pass on 0.39:installthenuninstallgives every config back byte for byte, anddoctorwarns about an out-of-date skill.0.39
fix, the cache lifetime, the cache clock, and Antigravity:context-doctor fixturns the measurements into changes: every lever ranked by what it would have saved on your own sessions, with what each costs in quality, applied only on a yes, undone withfix undo, and re-measured afterwards (/context-doctor:fixin the plugin).cache-ttlreplays your pauses at a 5-minute and a 1-hour prompt cache and sets Claude Code'spromptCacheTtlto the cheaper one, a price-only change. On Claude Code 2.1.251+ the status line says until when the cache is warm and what going cold costs,cache-missesexplains misses in Claude Code's own words, andinstallwires Google Antigravity.0.38 Your limits in their own unit, regressions after upgrades, recall, and a subagent price:
context-doctor limitsshows each plan window's %, pace and run-out time (Claude Pro/Max through the status line, Codex from its rollouts) and what 1M tokens cost in % of it, fitted on your readings with the error;savingsthen speaks in your limit too.cache-missesflags step changes after a Claude Code upgrade,recallsearches the session's own transcript (compacted turns included), a hook prices a subagent before it starts (never blocking), andoverhead pruneswitches off unused MCP servers and skills per project, reversibly. OpenAI caches count as warm for up to 24 hours. An independent QA pass's findings were fixed before the release.0.37 Desktop chat apps: a handoff, uploads, compact results, and a security pass: a chat app's history cannot be edited, so the
handoffprompt (Claude Desktop's + menu) has the model write a ≤400-token brief and save it withsave_handoff(secrets masked,handoff://latestto attach in the next chat, the per-turn saving reported: a 52k-token chat drops to ~600).ask_fileanswers from a big file throughpack_context, which over--httpalso takes ChatGPT uploads; ChatGPT gets compact results. An independent QA pass's eleven findings were fixed with tests; behind a tunnel,--httpnow needs--allowed-hosts <tunnel host>(handoff).
Every release, with the details: docs/whats-new.md.
Documentation
What
installdoes: every file it writes, what runs in each session after, and when you need MCPAutopilot: how it clears stale tool output, and why it never costs more
Fixes:
fix(one plan, applied with consent, undone in one step, re-measured),cache-ttland the subagents' modelSpend and budget: one bill across every tool, and a budget the every-prompt hook applies
The proxy: autopilot and the optimizing mode for your API apps,
/stats, cache advice, a public URL for CursorChat apps: Claude Desktop, ChatGPT, claude.ai and the phone apps; what acts by itself and what only nudges; the MCP tools, prompts and resources
Handoff: continue a long chat in a new one from a ≤400-token brief
Profiling: sessions, prompt-cache economics, subagents,
tasks,reads,compactions,cache-misses,limits,reportPack and overhead:
pack,recall,overhead,overhead splitandoverhead pruneDetectors and fixes: what the profiler finds and what each optimizer strategy changes
Library:
profileConversation,optimizeConversation,packContext,withContextDoctorBudgets and CI: the GitHub Action and
.contextdoctorrcPrivacy and the directory submission: what the plugin reads, writes and sends; the package for Anthropic's plugin directory
Desktop app and VS Code: the plugin's mod: limit readings, Claude Code's own cost,
/context-doctor-fix,/context-doctor-usage(the context ring, limit windows, tokens and dollars by model, running subagents) and/context-doctor-keep-warm(Desktop app, VS Code, terminal), the Desktop app's own tools behind tool search once you applyfix --apply desktop-tools-defer, and an optional cache band with Compact first (CONTEXT_DOCTOR_MOD_BAND=cold; Desktop app and terminal only)Editor and status line: the VS Code / Cursor extension, Claude Code's status bar and Codex's footer
Token counts: why counts are "~", how the Claude ratios were measured, exact counts
Performance: what context-doctor itself costs (its six MCP tool definitions: at most ~2,344 tokens)
Experiment and A/B suite: does a smaller context help, and does a lever cost quality? Measured on real tasks
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
Scan prompts for injection attacks, redact PII, and audit LLM SDK usage from any MCP client
Cross-tool persistent memory and context for AI assistants over MCP.
Multiple MCP tools, persistent graph memory, token-saving data pointers, and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables analyzing and optimizing context window token usage by measuring, compressing, and eliminating waste from MCP tool definitions.59 npmMIT
- AlicenseNot gradedqualityDmaintenanceA task-aware context compression layer for Agent workflows, RAG pipelines, and AI Coding assistants, reducing noisy logs, retrieval chunks, and code context into high-signal LLM inputs via CLI, Python SDK, and MCP.20 PyPI324MIT
- AlicenseAqualityDmaintenanceProvides MCP tools to migrate or compress conversation sessions between models based on context window capacity, including querying model context windows and listing known models.31MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables MCP-compatible clients and autonomous agents to dynamically compress long-horizon context by pruning verbose tool outputs, HTML boilerplate, and semantic redundancy by 40-70%. It reduces token burn and latency through deterministic, zero-dependency processing.-