Skip to main content
Glama
context-doctor
by KushalP1

context-doctor 🩺

CI npm npm downloads MCP Registry AgentHub 已收录:context-doctor license: MIT macOS | Linux | Windows

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 Cline

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

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: /plugin marketplace add KushalP1/context-doctor, then /plugin install context-doctor@context-doctor. You get the every-prompt check, the compaction hook, the MCP tools and /context-doctor:fix, :spend, :savings, :checkup, :overhead, :pack, :autopilot, :compact-window

Everything on this machine at once

npm install -g context-doctor && context-doctor install wires Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, Google Antigravity and GitHub Copilot: MCP server, skill and hooks (what it writes). context-doctor doctor checks it; context-doctor uninstall removes it. Then, for Claude Code in a terminal or IDE, context-doctor autopilot on

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.49.1 comments how much a PR grows CLAUDE.md, AGENTS.md and rules, and can fail over a budget (setup)

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 --report prints 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 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.

Net saving had you run /compact after the first reply

$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 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

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 /compact offer when you return to a large session after the cache expired. Compaction hook on every compaction. compact-window, if you set one

Install via npm or as a plugin. Status bar context meter, /context-doctor:savings, session, watch, report, dashboard, MCP tools

Claude Code in the desktop app's Code tab

Hooks, as above, the cold-resume /compact offer shown to you as well as the model. compact-window, if you set one: Claude Code compacts earlier by itself. Not autopilot: the app sets its own API address and ignores the one in settings

Same as above, and the plugin's mod: /context-doctor-usage, the usage view the app dropped (context ring, limit windows, tokens and dollars by model for today, 7 and 30 days, running subagents), /context-doctor-fix, and, once you apply fix --apply desktop-tools-defer, the app's own browser, session, preview and terminal tools kept behind tool search in new sessions (Claude Code 2.1.326+) (Desktop)

Cursor (agent)

A native after-tool-call hook (~/.cursor/hooks.json): in a heavy chat the agent gets the same hygiene guidance and the largest waste, once per 40% of growth. (Cursor's prompt hook can only allow or block a prompt, so this is the event where guidance reaches the model)

MCP tools, editor status bar extension, cursor profiler. With your own OpenAI key, autopilot too via a tokened tunnel (how)

Codex (ChatGPT app's Codex tab, IDE extension, CLI)

Every-prompt hook with the API's own token counts

MCP tools, skill, session reads Codex rollouts. Codex 0.171+: a footer status line from the MCP server (context, the session's cost, the plan's limits), once you turn on Codex's Custom status line experiment and pick it (how). On an API key, autopilot too (autopilot on sets openai_base_url in ~/.codex/config.toml; Codex no longer reads OPENAI_BASE_URL)

Gemini CLI

Every-prompt hook (BeforeAgent) with the API's own token counts. On an API key, autopilot too: GOOGLE_GEMINI_BASE_URL set to the proxy on 127.0.0.1:8787, plain HTTP (Google sign-in traffic goes elsewhere)

MCP tools, session and watch read its chats, overhead sizes GEMINI.md

GitHub Copilot (Copilot CLI, the Copilot app, VS Code agent sessions)

A session-start hook (~/.copilot/hooks/context-doctor.json) gives every new or resumed session the standing rules. No size check: Copilot passes a transcript only to hooks that cannot add context

MCP tools (~/.copilot/mcp-config.json, which VS Code's Copilot sessions read too)

Your own apps on the Anthropic, OpenAI or Gemini API

Autopilot on /v1/messages, /v1/chat/completions, /v1/responses and Gemini's generateContent (ANTHROPIC_BASE_URL / OPENAI_BASE_URL / GOOGLE_GEMINI_BASE_URL), or the optimizing proxy (which can cost more on cached traffic); no proxy possible (serverless, edge)? withContextDoctor(client) runs autopilot inside the SDK client

Exact usage and cache hit rates in /stats, prompt-cache placement advice (proxy)

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 profile_context call the model makes once at ~30 turns and on any cost question; pack_context instead of reading a big local file whole; a handoff offered once a chat is long, since a chat's history cannot be cut and a new chat can

One-click .mcpb install, context_checkup, handoff and ask_file prompts, handoff://latest to attach in the next chat (handoff)

claude.ai, ChatGPT, the phone apps

Your account's standing preferences, pasted once (Quick start)

Profile an exported chat with analyze or session. ChatGPT developer mode: the MCP tools at a URL, uploads into pack_context (how)

CI

analyze --fail-over-budget fails a build whose prompts outgrow a budget; the GitHub Action gates memory-file growth

.contextdoctorrc budgets and presets (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):

  1. 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.

  2. When a chat grows long, offer a handoff once (save_handoff): only a new chat cuts its history.

  3. Summarize any paste or tool result over ~2k tokens into the points you need.

  4. Refer to earlier content by name; never re-quote it or inline base64.

  5. For a big file you won't edit, call pack_context with the question; don't read it whole.

  6. 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

context-doctor install / uninstall

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 BeforeAgent, Cursor's postToolUse, postToolUseFailure and sessionStart); Claude Code's PreCompact, SessionStart, PreToolUse (the subagent price) and, on 2.1.251+, PreModelSwitch hooks; Copilot's sessionStart (the standing rules). --statusline adds the status bar line (details)

context-doctor fix [--apply ids|all] [--share] / fix undo

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), fix undo reverts exactly what it changed, later runs show what each saved since (details)

context-doctor spend [--days n] [--by repo|branch] [--share] [--export], spend merge <folder>

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; --export writes a file of totals (no prompt or path) and spend merge adds up a team's files, with a month-end forecast, with what drives it, and Claude Code's own figure (its cost-state) beside ours with what the gap is made of: its side requests, prompt suggestions and requests that hung and were sent again, named; subagent output Claude Code 2.1.284-2.1.299 never settled in its rows, estimated from the content and counted; subagent progress summaries estimated beside the total (from Claude Code 2.1.328, short notes on Haiku 5.5). When a plan limit ran out and requests kept going (extra usage), Claude Code's dollars split into past the limit, on usage credits, and inside the plan (at API list prices, an estimate) (docs)

context-doctor budget [<$>/day|<$>/week [--block]|off]

A spend budget the every-prompt hook applies: a line at 50%, 80% and 100%, and with --block prompts over it are held until you raise it or turn it off (docs)

context-doctor doctor

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

context-doctor savings [--days n] [--share [--copy]]

What your recent Claude Code sessions cost, and what /compact at cold resumes, autopilot and an earlier auto-compact window would save, replayed through the shipped code against your actual billed usage. --share prints totals only (no project names or paths) to post. A bare context-doctor in a terminal shows fix's plan instead, with one question for the fixes that cost nothing in quality

context-doctor autopilot on|off|pause|resume|status

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)

context-doctor proxy --autopilot

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 proxy runs the optimizing strategies (dedupe, trim, strip base64), which can cost more on cached traffic. --token for a public URL; /stats for cumulative savings (details)

context-doctor compact-window [status|off|<size>]

Replay your last 30 days at auto-compact windows from 200k to 800k: input cost, saving, and how many more compactions each means. 400k (or 250000, 0.4m) sets Claude Code's autoCompactWindow, with a backup; off removes it. Works in every Claude Code surface, the desktop app included. When you answered the Desktop app's own window offer, it says what the app offered and what you chose, and leaves that model's sessions out of the replay (docs)

context-doctor cache-ttl [status|1h|5m|off] [--subagents]

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 promptCacheTtl / subagentPromptCacheTtl (Claude Code 2.1.243+, every surface). Price only: the same content is sent (details)

context-doctor instructions [--copy]

The ~190-token standing rules (~130 on GPT) for claude.ai / ChatGPT preferences, for web and phones where no server runs

context-doctor handoff [list|show <id>|latest] [--copy]

Handoffs saved from chat apps (the handoff prompt or save_handoff): list them, print one, or copy it to paste as a new chat's first message (handoff)

context-doctor mcp [--http]

The MCP server as a subcommand, for clients and registries that launch npx -y context-doctor mcp

context-doctor-mcp

The MCP server itself — stdio by default (what the installer wires); --http [--port 8808] [--host H] [--allowed-hosts names] [--allowed-origins list] [--store-handoffs] serves streamable HTTP at /mcp for URL-based clients like ChatGPT developer-mode connectors (only for the host names it knows: behind a tunnel, pass its name to --allowed-hosts)

context-doctor session [file]

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 cost-state) beside ours, with what the gap is made of. Also reads Codex rollouts, Gemini CLI chats and ChatGPT data exports (conversations.json); --list to browse

context-doctor watch [file]

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

context-doctor cursor [--list]

Profile a chat from Cursor's local history (both storage formats)

context-doctor analyze <file>

Profile a conversation: token breakdown, findings, cost + latency estimates. --exact adds a true count; --fail-over-budget exits 1 on a breach, for CI

context-doctor optimize <file>

Apply the safe fixes; add --strategy trim-tool-calls for big inline file writes, --strategy prune-history for consented lossy compaction (what each does)

context-doctor diff <before> <after>

Compare two profiles: what moved by category, which findings were resolved or introduced, and what it saves in money and latency

context-doctor overhead [--days n] [--mcp]

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; --mcp sizes each configured server's tool definitions and flags unused ones

context-doctor overhead prune [--days n] [--write] [--undo]

Per project, the MCP servers and skills its sessions never used in n days; --write switches them off for this folder's project in its .claude/settings.local.json (backup kept, every entry recorded), --undo takes exactly those out. Never the app's connectors, plugins, or context-doctor itself

context-doctor overhead split <file> [--min-tokens n] [--write]

Move a memory file's big or code-heavy sections word for word to <name>.reference.md, leaving pointers; indexes stay. A plan until --write, which backs up first

context-doctor pack <files|dirs|-> -q "…"

Only the chunks of big documents, logs or code a question needs, ranked and fit to --max-tokens (default 4000). No query: an outline; --ids a#2,b#5 picks chunks from it. --semantic also ranks by meaning with a local Ollama model. Offline, no key

context-doctor recall "<query>" [--session <id|path>]

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 --session. Also the recall MCP tool

context-doctor tasks [--days n]

Cost per commit, per project: each session priced from its recorded usage against the commits it made

context-doctor reads [--days n] [--limit n]

Files read into session after session: reads, tokens, cost, and whether a CLAUDE.md summary or pack pays

context-doctor subagents [--days n]

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)

context-doctor compactions [--days n]

Do sessions work worse right after compacting? Re-reads, tool errors and your corrections, before vs after each compaction

context-doctor cache-misses [--days n]

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; --json per model and version

context-doctor limits [--days n] [--report [--copy]]

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 (cli, claude-desktop, sdk-cli) and model, and where that moved, by how much and on what date. When a limit ran out and Claude Code kept going on usage credits (extra usage), one line says when, how many requests and about how much at API list prices (an estimate), from the API's own headers where the proxy read them, else inferred from a 100% reading and said to be. --report: the same as a block to paste into a GitHub issue (no prompts, paths, session or account ids)

context-doctor cache-plan <request.json> [--calls n] [--out file] [--explicit]

Where an Anthropic API request should carry cache_control (top-level automatic caching for the moving end, unless --explicit), and what it saves over n calls; --out writes it applied

context-doctor accuracy

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

context-doctor report

Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, how often the cold-resume /compact offer was followed by a compaction, recoverable waste in recent sessions

context-doctor dashboard

Local savings dashboard on 127.0.0.1: tokens saved per day, sessions by context in use vs recoverable, budget status

context-doctor ci [--base <ref>] [--max-tokens n] [--max-increase n] [--markdown]

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)

context-doctor init [preset]

Write a .contextdoctorrc from a preset (chat, agent, batch) — a budget you can adopt in one command and tune later

context-doctor experiment --task "…"

Run one task twice from the same commit, in a fresh session and forked from an --existing one, same model and tools; compare bill, cache split, wall clock, and whether --check passed. The only command here that spends money, so it caps spend per arm and refuses a dirty tree (details)

context-doctor ab [--lever …] [--yes]

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, pack_context or the PreCompact instructions through the Messages API; pass counts, tokens and cost side by side. Bills ANTHROPIC_API_KEY: prints the estimate, sends nothing without --yes, stops at --budget (details)

context-doctor statusline

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 install --statusline; never overwrites a statusLine you already have. Codex has its own: the MCP server's statusline, picked in Codex's /statusline (details)

context-doctor hook

The every-prompt hook (Claude Code, Codex, Gemini CLI, Cursor) and Claude Code's compaction hook, registered by install; hook copilot is GitHub Copilot's session-start hook; you never run these yourself. Warning threshold tunable via CONTEXT_DOCTOR_WARN_TOKENS (default 80000)

context-doctor --version

Print the installed version. --help lists every flag

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) or always; 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: spend and doctor show Claude Code's own cost (its cost-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-misses replays 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-warm keeps it warm on request only, capped in hours and dollars. overhead prices every session's and subagent's start ($455 a month here) and fix gains mcp-defer. limits gives dollars per 1% per weekly reset with the moves dated, limits --report a block for a bug report, and handles Ultra (no 5-hour window). /context-doctor-usage is a usage pane in the Desktop app. spend reads Copilot CLI, OpenCode and Cline, splits --by repo|branch, and --export / spend merge add 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-code measures 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 bare context-doctor in 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+, install enables 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. spend estimates compaction requests and, for terminal sessions, subagent progress summaries, and fix can 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_context opening 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 modelPricing is 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-fix with 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 through pack on 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, subagents and fix now count them, and spend equals 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 fixed overhead --mcp launching a cloned repository's unapproved MCP servers, pack_context returning the agents' sign-in files, and more (details).

  • 0.43 Long tool output, fix for Codex, and a session's price: every Bash result stays in the conversation and is re-read on every later message until a compaction; fix now replays them at lower caps and, on a yes, sets Claude Code's bashOutputMaxChars, 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). fix also works for Codex: it replays your rollouts at earlier auto-compact limits and sets model_auto_compact_token_limit in config.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_HOME is followed everywhere. fix's subagent lever reads agent files the way Claude Code merges them, and every writer of settings.json takes one lock, so concurrent runs lose nothing (details).

  • 0.41 One bill, a budget, and the subagents' model: context-doctor spend puts Claude Code (subagents included), Codex, Gemini CLI and Cursor on one bill by tool, project, model and day. context-doctor budget 50/day has the every-prompt hook tell you at 50%, 80% and 100%, and with --block holds prompts over budget; the status line shows $12/$50 today, at about 5 ms a prompt. fix gains subagent-model: subagents run on your main conversation's model (Opus or Fable included), and CLAUDE_CODE_SUBAGENT_MODEL set 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, and fix undo reverts it.

  • 0.40 Reports in under a second: fix, savings, compact-window, cache-ttl, cache-misses and overhead read each transcript once and keep what they took from it in ~/.cache/context-doctor, so a second run reads only what was appended: fix 23.5 s → 0.4 s, savings 41 s → 0.6 s on the author's 2.7 GB history, every figure unchanged (details). Also from a QA pass on 0.39: install then uninstall gives every config back byte for byte, and doctor warns about an out-of-date skill.

  • 0.39 fix, the cache lifetime, the cache clock, and Antigravity: context-doctor fix turns 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 with fix undo, and re-measured afterwards (/context-doctor:fix in the plugin). cache-ttl replays your pauses at a 5-minute and a 1-hour prompt cache and sets Claude Code's promptCacheTtl to 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-misses explains misses in Claude Code's own words, and install wires Google Antigravity.

  • 0.38 Your limits in their own unit, regressions after upgrades, recall, and a subagent price: context-doctor limits shows 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; savings then speaks in your limit too. cache-misses flags step changes after a Claude Code upgrade, recall searches the session's own transcript (compacted turns included), a hook prices a subagent before it starts (never blocking), and overhead prune switches 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 handoff prompt (Claude Desktop's + menu) has the model write a ≤400-token brief and save it with save_handoff (secrets masked, handoff://latest to attach in the next chat, the per-turn saving reported: a 52k-token chat drops to ~600). ask_file answers from a big file through pack_context, which over --http also takes ChatGPT uploads; ChatGPT gets compact results. An independent QA pass's eleven findings were fixed with tests; behind a tunnel, --http now needs --allowed-hosts <tunnel host> (handoff).

Every release, with the details: 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

  • Fixes: fix (one plan, applied with consent, undone in one step, re-measured), cache-ttl and the subagents' model

  • Spend 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 Cursor

  • Chat 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, report

  • Pack and overhead: pack, recall, overhead, overhead split and overhead prune

  • 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

  • Privacy 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 apply fix --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

  • What's new, Roadmap, Python package

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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables analyzing and optimizing context window token usage by measuring, compressing, and eliminating waste from MCP tool definitions.
      59 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 PyPI
      324
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -