A
licenseNot graded
qualityD
maintenanceEnables analyzing and optimizing context window token usage by measuring, compressing, and eliminating waste from MCP tool definitions.
27 npm
MIT
context-doctor
by KushalP1
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@context-doctorProfile this conversation and suggest what to trim to save tokens."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 toWhich 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
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)
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 <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.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 |
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, unused servers), with what each costs in quality; applies one only on a yes, |
| Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes, including which surfaces autopilot can reach and any other program on its port |
| 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, and what its subagents cost (their own windows, your bill; never in the parent's profile). Also reads Codex rollouts, Gemini CLI chats and ChatGPT data exports ( |
| 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; |
| 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 |
| 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); |
| Your plan's limits in their own unit: each window's %, pace and run-out time (Claude's 5-hour and weekly windows from the status line's readings, 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 |
| 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.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) andcache-ttlThe 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
.contextdoctorrcEditor 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 (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
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo issues
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
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 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.325MIT
- AlicenseAqualityCmaintenanceProvides 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 gradedqualityBmaintenanceEnables 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.7-
