context-doctor 0.20.1 → 0.22.0

package/README.md

@@ -2,28 +2,60 @@
 
 [![CI](https://github.com/KushalP1/context-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/KushalP1/context-doctor/actions) [![npm](https://img.shields.io/npm/v/context-doctor)](https://www.npmjs.com/package/context-doctor) [![npm downloads](https://img.shields.io/npm/dm/context-doctor)](https://www.npmjs.com/package/context-doctor) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE) ![macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
 
-**Keep every AI session's context lean, automatically, without ever making it more expensive.**
+**Keep every AI session's context lean, and see exactly what it costs you, without ever making it more expensive.**
 
-Long agent sessions fill up with tool output nobody reads again: file dumps, shell logs, search results, screenshots. You pay for all of it on every request, the model gets slower, and it drifts as the window fills. `context-doctor` measures that, and with **autopilot** it removes it from every Claude Code (and GPT API) request on your machine, only at moments when doing so costs nothing extra.
+Long agent sessions fill up with tool output nobody reads again, and a 500k-token session re-reads all of it on every message. The most expensive moment is coming back after lunch: the prompt cache has expired, so the next message re-sends everything at full price. `context-doctor` measures this on your own sessions and acts on it at the moments that pay.
 
-- **9.8% less input cost, no session worse.** Replaying 130 days of the author's real Claude Code use (43 sessions) through the shipped code: **3.8 billion input tokens not sent, $4,694 saved at API list price, about $1,080 a month**, and not one session more expensive. Up to 37.7% on a long session. [What it saves →](#what-it-saves)
-- **Counts Claude correctly.** Current Claude models pack 2.75 characters per token, not the 4 most tools assume; estimates built on 4 undercount Claude by about 40%. The ratios here were measured from the API's own counts, and `context-doctor accuracy` re-checks them on yours. [How →](#why-token-counts-are--and-where-they-are-exact)
-- **Works where you work:** Claude Code, Cursor, Codex, Claude Desktop, any Anthropic or OpenAI API app, VS Code, CI. macOS, Linux and Windows, Node 20+.
-- **Local and keyless.** No account, no telemetry, no API key. Your own login passes through untouched. MIT.
+- **Tells you when to `/compact`, at the moment it pays.** When you come back to a large session after the cache expired, the every-prompt hook gives the model the numbers and it offers `/compact` once. Replayed over 133 days of the author's Claude Code history: 401 such returns, and compacting then would have saved **$4,053 net at list price, about $914 a month**. It works in every Claude Code surface, including the desktop app. [What it saves →](#what-it-saves)
+- **Autopilot for terminal and IDE sessions and API apps:** a local proxy that clears stale tool output only when the prompt cache is cold, so it never costs more. **9.8% less input cost, no session made more expensive**, in the same replay. (The desktop app's Code tab sets its own API address, so autopilot cannot reach it; `doctor` tells you if that is your case.)
+- **Counts Claude correctly.** Current Claude models pack 2.75 characters per token, not the 4 most tools assume, so estimates built on 4 undercount Claude by about 40%. The ratios were measured from the API's own counts; `context-doctor accuracy` re-checks them on yours.
+- **Works where you work:** Claude Code (terminal, IDE, desktop app, plugin), Cursor, Codex, Claude Desktop chat, any Anthropic or OpenAI API app, VS Code, CI. macOS, Linux and Windows, Node 20+. Local, keyless, no telemetry, MIT.
 
 Built and maintained by [gAI Ventures](https://gai.ventures).
 
 ## Quick start
 
+**See what it would save you first** (no install, reads your local Claude Code history):
+
 ```bash
+npx context-doctor savings
+```
+
+```
+What context-doctor finds in your Claude Code sessions (last 30 days, 29 sessions)
+────────────────────────────────────────────────────────────────
+Input you were billed for            $6,021   from the usage your transcripts record
+
+1. Compact when you come back        $2,492   199 returns to a session over 150k tokens
+   after the prompt cache expired. Running /compact then, net of the compaction
+   itself, would have saved this. The every-prompt hook points these moments out;
+   it works in every Claude Code surface, the desktop app included.
+
+2. Autopilot                            n/a   all 29 sessions ran in the desktop app, which
+   sets its own API address, so the autopilot proxy cannot sit in front of it.
+   (Had they run in the terminal or an IDE: $788, 12.9%.)
+```
+
+That is the author's machine: every session there runs in the desktop app, so the first line is the one that applies. Yours is computed the same way, from your own transcripts: every session replayed request by request through the shipped code, against what you were actually billed.
+
+**Then install it**, whichever way suits you:
+
+```bash
+# Everything, every app it finds (Claude Code, Cursor, Codex, Claude Desktop)
 npm install -g context-doctor
-context-doctor install          # hooks, MCP server and skill in every AI app it finds
+context-doctor install
 context-doctor autopilot on     # every new Claude Code session keeps its context lean
 ```
 
-Then start a new Claude Code session and work as usual. `context-doctor autopilot status` shows what it did; `context-doctor doctor` checks the whole setup. Everything is reversible: `context-doctor autopilot off`, `context-doctor uninstall`.
+```text
+# Or as a Claude Code plugin, from inside Claude Code
+/plugin marketplace add KushalP1/context-doctor
+/plugin install context-doctor@context-doctor
+```
+
+The plugin brings the every-prompt check, the MCP tools, and `/context-doctor:savings`, `/context-doctor:checkup` and `/context-doctor:autopilot`. It needs no npm step: the MCP server ships as one self-contained file, so it also works on Claude Code versions that do not install plugin dependencies.
 
-Just want a look first? `npx context-doctor session` profiles your latest Claude Code or Codex session in place, no install.
+`context-doctor autopilot status` shows what autopilot did; `context-doctor doctor` checks the whole setup. Everything is reversible: `context-doctor autopilot off`, `context-doctor uninstall`, or `/plugin uninstall`.
 
 ```
 Where the tokens go
@@ -43,26 +75,36 @@ Findings (4)
 
 ## What it saves
 
-Measured, not modelled: every Claude Code session on the author's machine from 18 May to 25 September 2026 (43 sessions, 130 days, mostly Opus 5 and Fable 5 with the 1M window) was replayed request by request through the shipped autopilot code, with the real timestamps, and priced the way the prompt cache bills it (cached reads 0.1x, writes 1.25x). Run it on your own history with `node scripts/replay-autopilot.mjs`.
+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 0.1x, writes 1.25x) at API list prices. `context-doctor savings` runs the same measurement on yours.
+
+**1. Compacting when you come back** (every Claude Code surface, desktop app included). 133 days, 401 returns to a session over 150k tokens after more than 65 idle minutes; median context at the return, 517k tokens.
+
+| | |
+|---|---|
+| Net saving had you run `/compact` after the first reply | **$4,053 (about $914 a month)** |
+| Returns where it paid off | 296 of 401 |
+| Worst single case | −$2.30 (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** (terminal and IDE sessions, API apps). 130 days, 43 sessions, replayed through the shipped autopilot code with real timestamps:
 
 | | Without autopilot | With autopilot | Saved |
 |---|---|---|---|
 | Input tokens sent | 41.4 billion | 37.6 billion | **3.8 billion (9.2%)** |
 | Input cost at API list price | $48,962 | $44,268 | **$4,694 (9.8%)** |
-| Per 30 days | | | **~875 million tokens, ~$1,080** |
 | Sessions made more expensive | | | **0 of 43** |
 
-How it spreads: the median session saves 1.9%, the best 37.7%. Short sessions barely change, because they rarely pile up 20k tokens of stale tool output before they end. Long sessions are where the money is: on this machine 94% of input cost came from requests above 200k tokens, and those are the requests autopilot makes smaller. Savings scale with how long your sessions run and how much they read, so a lighter user saves proportionally less, and never pays more.
-
-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 dollar column as the size of the effect, not as your bill. The token column holds either way, and every request that is 9% smaller is also faster to first token and further from auto-compaction.
+The median session saves 1.9%, the best 37.7%: long sessions are where the money is (94% of input cost on that machine came from requests above 200k tokens). 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.
 
-What is not counted here: the proxy's full optimizer for your own API apps, the hook's guidance to the model, and fixes you make from `session` findings. Those save more on top, but they depend on what the model or you do with the advice, so they are not in this table.
+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.
 
 ## What happens on each platform
 
 | Where you work | Automatic, every request | What you get on top |
 |---|---|---|
-| **Claude Code** (terminal, VS Code, JetBrains, desktop app's Code tab) | **Autopilot** clears stale tool output (cold cache only, never more expensive). **Hook** on every prompt warns the model with the real context size and its largest waste | Status bar context meter, `/context-doctor` skill, `session`, `watch`, `report`, dashboard |
+| **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 |
+| **Claude Code** in the desktop app's Code tab | **Hook**, as above, including the cold-resume `/compact` offer. Not autopilot: the app sets its own API address and ignores the one in settings | Same install options | Install via npm or as a **plugin** (`/plugin marketplace add KushalP1/context-doctor`). Status bar context meter, `/context-doctor:savings`, `session`, `watch`, `report`, dashboard |
 | **Cursor** (agent) | Cursor runs Claude Code's hooks, so the same every-prompt check fires inside Cursor | MCP tools, editor status bar extension, `cursor` profiler. With your own OpenAI key, autopilot too via a tokened tunnel ([how](#putting-the-proxy-on-a-public-url-cursor-with-your-own-openai-key-remote-apps)) |
 | **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. On an API key, autopilot too (`OPENAI_BASE_URL`) |
 | **Your own apps on the Anthropic or OpenAI API** | Autopilot on `/v1/messages`, `/v1/chat/completions` and `/v1/responses` (`ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL`), or the full optimizing proxy | Exact usage and cache hit rates in `/stats`, prompt-cache placement advice |
@@ -75,6 +117,8 @@ Not claimed, because no process on your machine sends those requests: trimming i
 ## What's new
 
 - **0.20 Autopilot**: stale tool output cleared from every Claude Code request, only when the prompt cache is cold, so it cannot cost more (measured: 9.8% less input cost, ~$1,080 a month on the author's usage, no session worse); runs as a login service on macOS, Linux and Windows; now also for GPT via OpenAI's Chat Completions and Responses APIs.
+- **0.22 Honest about where each lever works, and a new one that works everywhere**: the every-prompt hook now offers `/compact` when you return to a large session after the cache expired (measured: ~$914 a month on the author's history), including in the desktop app. Found and fixed: autopilot cannot reach the desktop app's Code tab, and `doctor` now says so instead of reporting ✓; `savings` counted whole-file history as "last 30 days"; the hook quoted per-message cost at the uncached rate (10x too high). `--version` added.
+- **0.21 See it before you install it**: `npx context-doctor savings` replays your own recent sessions through autopilot and shows what it would have saved, against what you were actually billed. Install as a **Claude Code plugin** from inside Claude Code. Ready for the official **MCP Registry** (`io.github.KushalP1/context-doctor`), which every release now publishes to; any MCP client can launch it as `npx -y context-doctor mcp`.
 - **0.20.1 Releases that finish themselves**: one tag publishes to npm and creates a GitHub release with the Claude Desktop bundle (signed when a certificate is configured); the editor extension is ready for the VS Code Marketplace and Open VSX.
 - **0.19 Measured Claude tokenizer**: estimates were 40% low for Claude; fixed from the API's own counts, with a per-model check in `accuracy`.
 - **0.18** `proxy --token` for putting the proxy on a public URL safely. **0.17** Claude Desktop: a `profile_context` the model can afford to call from chat, `.mcpb` bundle, standing preferences for web and mobile. **0.16** Codex. **0.15** Cursor.
@@ -138,6 +182,8 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | Command | What it does |
 |---|---|
 | `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor/Codex, the Agent Skill, the every-prompt hook |
+| `context-doctor savings [--days n]` | What autopilot saves, or would have saved, on your own recent Claude Code sessions: replayed through the shipped code, against your actual billed usage. A bare `context-doctor` in a terminal shows the same |
+| `context-doctor mcp [--http]` | The MCP server as a subcommand, for clients and registries that launch `npx -y context-doctor mcp` |
 | `context-doctor autopilot on\|off\|pause\|resume\|status` | Every new Claude Code session goes through the local proxy, which clears stale tool output only when the prompt cache is cold: measured 9.8% less input cost, no session worse |
 | `context-doctor instructions [--copy]` | The ~180-token standing rules (~120 on GPT) for claude.ai / ChatGPT preferences, for web and phones where no server runs |
 | `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates. `--fail-over-budget` exits 1 on a breach, for CI |
@@ -207,7 +253,7 @@ context-doctor autopilot pause     # instant passthrough, nothing restarts
 context-doctor autopilot off       # remove it
 ```
 
-`autopilot on` runs the local proxy as a background service (launchd on macOS, a systemd user service on Linux, a logon task on Windows), waits until it answers, and only then points Claude Code at it through `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`. Every Claude Code session started afterwards, in the terminal, an IDE, or the desktop app's Code tab, sends its requests through it. Your login (subscription or API key) passes through untouched.
+`autopilot on` runs the local proxy as a background service (launchd on macOS, a systemd user service on Linux, a logon task on Windows), waits until it answers, and only then points Claude Code at it through `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`. Every Claude Code session started afterwards in a terminal or an IDE sends its requests through it. **Not the desktop app's Code tab:** it runs Claude Code "host-orchestrated", sets `ANTHROPIC_BASE_URL` from its own account configuration, and drops the same key from settings files (checked in Claude Code 2.1.284). `autopilot on`, `autopilot status` and `doctor` look at which surface your recent sessions ran in and warn when autopilot cannot reach them; for desktop sessions the cold-resume advice is the lever that works. Your login (subscription or API key) passes through untouched.
 
 **What it does to each request:** once old tool output adds up to 20k+ tokens (file reads, shell output, search and web results, screenshots inside them), it replaces that output with a one-line note, keeping the 3 most recent results. The tool call stays in the history, so the model can simply run it again if it needs the output. Your messages, its answers, answers you gave to its questions, subagent reports and MCP results are never touched.
 

package/dist/autopilot.d.ts

@@ -40,6 +40,10 @@ export interface Health {
     version?: string;
 }
 export declare function health(port: number, timeoutMs?: number): Promise<Health>;
+/** Which Claude Code surfaces ran recent sessions: entrypoint -> count. */
+export declare function recentSurfaces(days?: number, home?: string): Map<string, number>;
+/** Lines explaining which recent sessions autopilot can reach, or nothing when all can. */
+export declare function reachNote(days?: number): string[];
 export declare function currentCli(): string;
 export declare function autopilotOn(port?: number, paths?: AutopilotPaths): Promise<{
     ok: boolean;

package/dist/autopilot.js

@@ -19,7 +19,7 @@
  * backend, not an API base URL).
  */
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -179,24 +179,86 @@ async function waitHealthy(port, ms) {
     }
 }
 function readConfig(paths) {
+    // readJson returns {} for a missing file; only a file with a port is a config.
+    if (!existsSync(paths.config))
+        return undefined;
     try {
-        return readJson(paths.config);
+        const cfg = readJson(paths.config);
+        return typeof cfg.port === "number" && cfg.port > 0 ? cfg : undefined;
     }
     catch {
         return undefined;
     }
 }
+/** Which Claude Code surfaces ran recent sessions: entrypoint -> count. */
+export function recentSurfaces(days = 30, home = homedir()) {
+    const out = new Map();
+    const root = join(home, ".claude", "projects");
+    const since = Date.now() - days * 86_400_000;
+    let dirs = [];
+    try {
+        dirs = readdirSync(root);
+    }
+    catch {
+        return out;
+    }
+    for (const d of dirs) {
+        let files = [];
+        try {
+            files = readdirSync(join(root, d)).filter((f) => f.endsWith(".jsonl"));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            const p = join(root, d, f);
+            try {
+                if (statSync(p).mtimeMs < since)
+                    continue;
+                const head = readFileSync(p, "utf8").slice(0, 64 * 1024);
+                const m = head.match(/"entrypoint":"([^"]+)"/);
+                const ep = m ? m[1] : "unknown";
+                out.set(ep, (out.get(ep) ?? 0) + 1);
+            }
+            catch { /* unreadable: skip */ }
+        }
+    }
+    return out;
+}
+/** Lines explaining which recent sessions autopilot can reach, or nothing when all can. */
+export function reachNote(days = 30) {
+    const surfaces = recentSurfaces(days);
+    let desktop = 0, other = 0;
+    // Sessions with no recorded surface are evidence of nothing either way.
+    for (const [ep, n] of surfaces) {
+        if (ep.startsWith("claude-desktop"))
+            desktop += n;
+        else if (ep !== "unknown")
+            other += n;
+    }
+    if (desktop === 0)
+        return [];
+    const lines = [
+        `! ${desktop} of your ${desktop + other} Claude Code sessions in the last ${days} days (with a recorded surface) ran in the desktop app. The desktop app`,
+        "  sets its own API address and ignores the one in settings.json, so autopilot cannot reach those sessions.",
+        "  It applies to Claude Code in a terminal (`claude`) and in IDEs. For desktop sessions, the every-prompt",
+        "  hook points out when /compact would pay off (see `context-doctor savings`).",
+    ];
+    if (other === 0)
+        lines.push("  Every recent session of yours is a desktop one: autopilot will not change anything until you use the terminal or an IDE.");
+    return lines;
+}
 export function currentCli() {
     return join(dirname(fileURLToPath(import.meta.url)), "cli.js");
 }
 export async function autopilotOn(port = DEFAULT_AUTOPILOT_PORT, paths = autopilotPaths()) {
     const lines = [];
     const cli = currentCli();
-    if (isEphemeralPath(cli)) {
+    if (isEphemeralPath(cli) || /[\\/]\.claude[\\/]plugins[\\/]/.test(cli)) {
         return {
             ok: false,
             lines: [
-                "✗ Running from the npx cache, which npm deletes at will; a background service cannot point there.",
+                "✗ Running from the npx cache or a Claude Code plugin copy, which are replaced or deleted on update; a background service cannot point there.",
                 "  Install it once, then re-run:  npm install -g context-doctor && context-doctor autopilot on",
             ],
         };
@@ -238,6 +300,7 @@ export async function autopilotOn(port = DEFAULT_AUTOPILOT_PORT, paths = autopil
     lines.push(`✓ Claude Code routed through it (env.ANTHROPIC_BASE_URL in ${paths.settings})`);
     lines.push("  Applies to Claude Code sessions started from now on (CLI, IDE, and the desktop app's Code tab).");
     lines.push("  Sessions already open keep their old route until restarted.");
+    lines.push(...reachNote());
     lines.push(`  GPT apps on your own OpenAI key get the same: export OPENAI_BASE_URL=${proxyUrl(port)}/v1`);
     return { ok: true, lines };
 }
@@ -295,6 +358,8 @@ export async function autopilotStatus(paths = autopilotPaths()) {
                 lines.push(`Since ${s.startedAt.slice(0, 16).replace("T", " ")} UTC: ${a.requests} requests, ${a.changedRequests} sent lighter`);
                 lines.push(`  ${a.resultsCleared} stale tool outputs cleared in ${a.batches} batches (${a.coldBatches} while the cache was cold anyway)`);
                 lines.push(`  ~${formatTokens(a.tokensRemoved)} tokens not sent`);
+                if (a.requests === 0)
+                    lines.push(...reachNote(7).map((l) => l.replace(/^! /, "  ")));
                 const billed = s.upstreamInputTokens + s.upstreamCacheReadTokens + s.upstreamCacheWriteTokens;
                 if (billed > 0)
                     lines.push(`  Billed input: ${formatTokens(billed)} (${Math.round((s.upstreamCacheReadTokens / billed) * 100)}% cache reads)`);
@@ -318,7 +383,7 @@ export async function ensureProxyUp(paths = autopilotPaths()) {
         return;
     if ((await health(cfg.port, 300)).ok)
         return;
-    if (!existsSync(cfg.node) || !existsSync(cfg.cli))
+    if (typeof cfg.node !== "string" || typeof cfg.cli !== "string" || !existsSync(cfg.node) || !existsSync(cfg.cli))
         return;
     startDetached(serviceCommand(cfg.node, cfg.cli, cfg.port, paths), paths.log);
     await waitHealthy(cfg.port, 2500);

package/dist/cli.js

@@ -21,7 +21,8 @@ import { listSessions, parseSessionFile } from "./session.js";
 import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
 import { measureTokenizer, renderTokenizer } from "./tokenizer-measure.js";
-import { autopilotOff, autopilotOn, autopilotPause, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
+import { autopilotOff, autopilotOn, autopilotPause, autopilotPaths, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
+import { estimateSavings, renderSavings } from "./savings.js";
 import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
@@ -49,10 +50,16 @@ Usage:
   context-doctor install                        Wire the MCP server + skill into Claude Desktop,
                                                 Claude Code, and Cursor automatically
   context-doctor uninstall                      Undo install
+  context-doctor --version                      Print the installed version
+  context-doctor savings [--days n]              What autopilot saves (or would have) on YOUR recent
+                                                Claude Code sessions: replayed, priced as billed.
+                                                Also what a bare \`context-doctor\` shows
   context-doctor autopilot on|off|pause|resume|status
                                                 Every new Claude Code session goes through the
                                                 local proxy, which clears stale tool output only
                                                 when the prompt cache is cold (never costs more)
+  context-doctor mcp [--http]                   The MCP server (same as context-doctor-mcp), for clients
+                                                that launch \`npx -y context-doctor mcp\`
   context-doctor instructions [--copy]          Standing context rules to paste into claude.ai or
                                                 ChatGPT preferences (works on web and mobile too)
   context-doctor session [file]                 Profile a Claude Code session transcript or a
@@ -142,6 +149,10 @@ function parseArgs(argv) {
             case "--help":
                 console.log(HELP);
                 process.exit(0);
+            case "-v":
+            case "--version":
+                console.log(packageVersion());
+                process.exit(0);
             case "--json":
                 args.json = true;
                 break;
@@ -211,6 +222,9 @@ function parseArgs(argv) {
             case "--token":
                 args.token = argv[++i];
                 break;
+            case "--days":
+                args.days = Number(argv[++i]);
+                break;
             case "--autopilot":
                 args.autopilot = true;
                 break;
@@ -266,6 +280,24 @@ function readInput(file) {
         return readFileSync(0, "utf8");
     return readFileSync(file, "utf8");
 }
+/** The installed package's version, read from its package.json so it cannot drift. */
+function packageVersion() {
+    try {
+        return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Any Claude Code transcript on this machine? One directory listing, no parsing. */
+function hasClaudeSessions() {
+    try {
+        return listSessions(1).some((s) => s.path.includes(".claude"));
+    }
+    catch {
+        return false;
+    }
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.command === "hook") {
@@ -459,6 +491,35 @@ async function main() {
             process.exitCode = 1;
         return;
     }
+    if (args.command === "savings" || (!args.command && process.stdout.isTTY && hasClaudeSessions())) {
+        // A bare `context-doctor` in a terminal, with Claude Code history on the
+        // machine, answers the question people install this for: what would it
+        // save me? Scripts and pipes still get the help text.
+        const progress = process.stderr.isTTY
+            ? (done, total) => process.stderr.write(`\rReplaying your Claude Code sessions through autopilot… ${done}/${total}`)
+            : undefined;
+        const report = estimateSavings(args.days ?? 30, {}, undefined, progress);
+        if (progress)
+            process.stderr.write("\r\x1b[K");
+        const on = existsSync(autopilotPaths().config);
+        if (args.json)
+            console.log(JSON.stringify(report, null, 2));
+        else {
+            console.log(renderSavings(report, on));
+            if (!args.command)
+                console.log("\nAll commands: context-doctor --help");
+        }
+        return;
+    }
+    if (args.command === "mcp") {
+        // `context-doctor mcp [--http ...]` is the MCP server, the same program as
+        // the context-doctor-mcp binary. Registries and clients that launch a
+        // package with `npx -y context-doctor <args>` can only reach the package's
+        // main binary, so the server has to be a subcommand of it too.
+        process.argv.splice(2, 1);
+        await import("./mcp.js");
+        return;
+    }
     if (args.command === "autopilot") {
         const sub = args.file ?? "status";
         const port = args.port ?? DEFAULT_AUTOPILOT_PORT;

package/dist/coldresume.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Cold resume: coming back to a large session after the prompt cache expired.
+ *
+ * Claude Code caches the conversation for an hour on a subscription (five
+ * minutes on the API). Come back later and the next message re-sends the
+ * whole context at the cache-WRITE rate (1.25x), and every message after it
+ * re-reads it (0.1x each). On a 500k-token session that is the most expensive
+ * moment of the day, and the one moment `/compact` is cheapest to accept:
+ * the cache is being rebuilt anyway.
+ *
+ * Measured on the author's 133 days of Claude Code history: 401 returns to a
+ * session over 150k tokens after more than 65 idle minutes (median context
+ * 517k). Compacting right after the first reply, counting the compaction
+ * request itself and only the messages up to the next such return, would have
+ * saved $4,053 at list price, about $914 a month; it paid off in 296 of 401
+ * cases, and the worst single loss was $2.30 (sessions left after a few more
+ * messages). So this advises, with the numbers, and the user decides.
+ *
+ * It works where the proxy cannot: the desktop app's Code tab runs Claude Code
+ * host-orchestrated and drops a settings-file ANTHROPIC_BASE_URL, but it runs
+ * the every-prompt hook, which is where this is called from.
+ */
+/** Just past Claude Code's one-hour cache, as Claude Code's own idle clearing uses. */
+export declare const COLD_IDLE_MS: number;
+/** Below this, a rebuilt cache is cheap and compaction is not worth the interruption. */
+export declare const COLD_MIN_TOKENS = 150000;
+export interface ColdResume {
+    idleMs: number;
+    /** Context size at the last request, from the API's own usage. */
+    tokens: number;
+    model?: string;
+    /** Timestamp of the last assistant reply: identifies this idle period. */
+    lastReplyAt: number;
+    /** This message's cost to rebuild the cache, at list price. */
+    resumeUsd?: number;
+    /** Each later message's cost to re-read the context, at list price. */
+    perMessageUsd?: number;
+}
+/**
+ * Is the prompt being submitted now a return to a large, cache-cold session?
+ * Reads only the transcript's tail. Undefined when not (or when unreadable).
+ */
+export declare function detectColdResume(path: string, now?: number, idleMs?: number, minTokens?: number): ColdResume | undefined;
+/** The note the hook hands the model: the numbers, and one sentence to say. */
+export declare function renderColdResume(c: ColdResume): string;
+export interface ColdResumeEvent {
+    at: number;
+    tokens: number;
+    /** Messages until the session ended, was compacted, or went cold again. */
+    messagesAfter: number;
+    /** Net USD compaction after the first reply would have saved (negative: cost). */
+    netUsd: number;
+}
+/**
+ * Replay a transcript's billed usage and price what compacting at each cold
+ * resume would have saved. Each resume only counts the messages up to the
+ * next one (no double counting), and the compaction request is a cost.
+ */
+export declare function coldResumeEvents(path: string, idleMs?: number, minTokens?: number): ColdResumeEvent[];

package/dist/coldresume.js

@@ -0,0 +1,174 @@
+/**
+ * Cold resume: coming back to a large session after the prompt cache expired.
+ *
+ * Claude Code caches the conversation for an hour on a subscription (five
+ * minutes on the API). Come back later and the next message re-sends the
+ * whole context at the cache-WRITE rate (1.25x), and every message after it
+ * re-reads it (0.1x each). On a 500k-token session that is the most expensive
+ * moment of the day, and the one moment `/compact` is cheapest to accept:
+ * the cache is being rebuilt anyway.
+ *
+ * Measured on the author's 133 days of Claude Code history: 401 returns to a
+ * session over 150k tokens after more than 65 idle minutes (median context
+ * 517k). Compacting right after the first reply, counting the compaction
+ * request itself and only the messages up to the next such return, would have
+ * saved $4,053 at list price, about $914 a month; it paid off in 296 of 401
+ * cases, and the worst single loss was $2.30 (sessions left after a few more
+ * messages). So this advises, with the numbers, and the user decides.
+ *
+ * It works where the proxy cannot: the desktop app's Code tab runs Claude Code
+ * host-orchestrated and drops a settings-file ANTHROPIC_BASE_URL, but it runs
+ * the every-prompt hook, which is where this is called from.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { forEachLine } from "./session.js";
+import { pricingFor, formatUsd } from "./pricing.js";
+import { formatTokens } from "./tokens.js";
+/** Just past Claude Code's one-hour cache, as Claude Code's own idle clearing uses. */
+export const COLD_IDLE_MS = 65 * 60_000;
+/** Below this, a rebuilt cache is cheap and compaction is not worth the interruption. */
+export const COLD_MIN_TOKENS = 150_000;
+/** What a compacted session restarts from: system prompt and tools plus the summary. */
+const AFTER_COMPACT_TOKENS = 45_000;
+/** Output tokens a compaction summary costs, and output's price relative to input. */
+const SUMMARY_OUTPUT_TOKENS = 8_000;
+const OUTPUT_PRICE_RATIO = 5;
+function tailLines(path, bytes = 256 * 1024) {
+    const size = statSync(path).size;
+    const n = Math.min(size, bytes);
+    const fd = openSync(path, "r");
+    const buf = Buffer.alloc(n);
+    try {
+        readSync(fd, buf, 0, n, size - n);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return buf.toString("utf8").split("\n").reverse();
+}
+/**
+ * Is the prompt being submitted now a return to a large, cache-cold session?
+ * Reads only the transcript's tail. Undefined when not (or when unreadable).
+ */
+export function detectColdResume(path, now = Date.now(), idleMs = COLD_IDLE_MS, minTokens = COLD_MIN_TOKENS) {
+    try {
+        for (const line of tailLines(path)) {
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (e?.type !== "assistant" || e.isSidechain)
+                continue;
+            const u = e.message?.usage;
+            if (!u)
+                continue;
+            const tokens = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+            if (tokens <= 0)
+                continue;
+            const lastReplyAt = Date.parse(e.timestamp);
+            if (!Number.isFinite(lastReplyAt))
+                return undefined;
+            const idle = now - lastReplyAt;
+            if (idle < idleMs || tokens < minTokens)
+                return undefined;
+            const model = e.message?.model;
+            const p = pricingFor(model);
+            return {
+                idleMs: idle,
+                tokens,
+                model,
+                lastReplyAt,
+                resumeUsd: p ? (tokens * 1.25 * p.inputPerM) / 1e6 : undefined,
+                perMessageUsd: p ? (tokens * 0.1 * p.inputPerM) / 1e6 : undefined,
+            };
+        }
+    }
+    catch {
+        /* unreadable transcript: no advice */
+    }
+    return undefined;
+}
+function duration(ms) {
+    const m = Math.round(ms / 60_000);
+    if (m < 90)
+        return `${m} minutes`;
+    const h = ms / 3_600_000;
+    return h < 48 ? `${h.toFixed(h < 10 ? 1 : 0)} hours` : `${Math.round(h / 24)} days`;
+}
+/** The note the hook hands the model: the numbers, and one sentence to say. */
+export function renderColdResume(c) {
+    const cheaper = Math.max(0, Math.round((1 - AFTER_COMPACT_TOKENS / c.tokens) * 100));
+    const money = c.resumeUsd !== undefined
+        ? ` (~${formatUsd(c.resumeUsd)} at list price), and every later message re-reads it (~${formatUsd(c.perMessageUsd)} each)`
+        : ", and every later message re-reads it";
+    return [
+        `This session was idle for ${duration(c.idleMs)}, longer than the prompt cache lasts, so this message re-sends the whole ~${formatTokens(c.tokens)}-token context at the full cache-write rate${money}.`,
+        `If the user is going to keep working in this session, running /compact now restarts it from a short summary and makes each later message roughly ${cheaper}% cheaper; the cache is being rebuilt anyway, so now is when compaction costs least.`,
+        "Begin your reply with one short sentence offering that (only the user can run /compact), then answer the request normally. Do not raise it again this session unless it goes idle again.",
+    ].join("\n");
+}
+/**
+ * Replay a transcript's billed usage and price what compacting at each cold
+ * resume would have saved. Each resume only counts the messages up to the
+ * next one (no double counting), and the compaction request is a cost.
+ */
+export function coldResumeEvents(path, idleMs = COLD_IDLE_MS, minTokens = COLD_MIN_TOKENS) {
+    const reqs = [];
+    let lastId, model;
+    forEachLine(path, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (e.type === "system" && e.subtype === "compact_boundary") {
+            reqs.push("compact");
+            return;
+        }
+        if (e.type !== "assistant" || !e.message || e.message.id === lastId)
+            return;
+        lastId = e.message.id;
+        const u = e.message.usage ?? {};
+        const total = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+        const at = Date.parse(e.timestamp);
+        if (total > 0 && Number.isFinite(at)) {
+            reqs.push({ at, total });
+            model ??= e.message.model;
+        }
+    });
+    const perM = pricingFor(model)?.inputPerM;
+    if (!perM)
+        return [];
+    const real = reqs.filter((r) => r !== "compact");
+    if (real.length < 2)
+        return [];
+    const events = [];
+    for (let i = 1; i < reqs.length; i++) {
+        const a = reqs[i - 1], b = reqs[i];
+        if (a === "compact" || b === "compact")
+            continue;
+        if (b.at - a.at <= idleMs || b.total < minTokens)
+            continue;
+        const removed = Math.max(0, b.total - AFTER_COMPACT_TOKENS);
+        let saved = 0, n = 0, prev = b.at;
+        for (const c of reqs.slice(i + 1)) {
+            if (c === "compact")
+                break;
+            if (c.at - prev > idleMs && c.total >= minTokens)
+                break;
+            saved += (c.at - prev > 3_600_000 ? 1.25 : 0.1) * removed;
+            prev = c.at;
+            n++;
+        }
+        const cost = 0.1 * b.total + OUTPUT_PRICE_RATIO * SUMMARY_OUTPUT_TOKENS + 1.25 * AFTER_COMPACT_TOKENS;
+        events.push({ at: b.at, tokens: b.total, messagesAfter: n, netUsd: ((saved - cost) * perM) / 1e6 });
+    }
+    return events;
+}

package/dist/doctor.js

@@ -5,7 +5,7 @@
  * check, so "it doesn't work" becomes a single pasteable diagnosis. Always
  * exits 0 — absence of an app is a note, not a failure.
  */
-import { autopilotPaths, health, proxyUrl } from "./autopilot.js";
+import { autopilotPaths, health, proxyUrl, recentSurfaces } from "./autopilot.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
@@ -226,12 +226,24 @@ export async function runDoctor() {
             }
             catch { /* reported below */ }
             const paused = existsSync(paths.pauseFile);
-            checks.push(h.ok && h.autopilot && routed
-                ? { label: "Autopilot", status: "ok", detail: `proxy up on ${proxyUrl(cfg.port)}, Claude Code routed through it${paused ? " (PAUSED: passthrough)" : ""}` }
-                : { label: "Autopilot", status: "fail", detail: !h.ok ? `proxy not answering on ${proxyUrl(cfg.port)}: the next Claude Code prompt restarts it; or run: context-doctor autopilot on` : "settings.json no longer routes Claude Code to the proxy: run context-doctor autopilot on" });
+            // Routed in settings is not the same as reached: the desktop app ignores it.
+            let seen = -1;
+            try {
+                const st = (await fetch(`${proxyUrl(cfg.port)}/stats`, { signal: AbortSignal.timeout(800) }).then((r) => r.json()));
+                seen = st.autopilot?.requests ?? -1;
+            }
+            catch { /* stats are best effort */ }
+            const surfaces = recentSurfaces(7);
+            const known = [...surfaces.keys()].filter((ep) => ep !== "unknown");
+            const desktopOnly = known.length > 0 && known.every((ep) => ep.startsWith("claude-desktop"));
+            checks.push(h.ok && h.autopilot && routed && seen === 0 && desktopOnly
+                ? { label: "Autopilot", status: "warn", detail: "running, but it has seen 0 requests: your recent Claude Code sessions all ran in the desktop app, which ignores settings.json's API address. Autopilot only reaches terminal and IDE sessions" }
+                : h.ok && h.autopilot && routed
+                    ? { label: "Autopilot", status: "ok", detail: `proxy up on ${proxyUrl(cfg.port)}, Claude Code routed through it${seen >= 0 ? ` (${seen} requests since start)` : ""}${paused ? " (PAUSED: passthrough)" : ""}` }
+                    : { label: "Autopilot", status: "fail", detail: !h.ok ? `proxy not answering on ${proxyUrl(cfg.port)}: the next Claude Code prompt restarts it; or run: context-doctor autopilot on` : "settings.json no longer routes Claude Code to the proxy: run context-doctor autopilot on" });
         }
     }
-    const mark = { ok: "✓", fail: "✗", skip: "–" };
+    const mark = { ok: "✓", warn: "!", fail: "✗", skip: "–" };
     console.log("CONTEXT DOCTOR — self-check");
     console.log("═".repeat(56));
     for (const c of checks) {

package/dist/hook.js

@@ -12,6 +12,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { recordLedger, statePath } from "./ledger.js";
 import { parseConversation } from "./parse.js";
@@ -19,7 +20,8 @@ import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
 import { formatTokens, CHARS_PER_TOKEN } from "./tokens.js";
 import { ensureProxyUp } from "./autopilot.js";
-import { formatUsd } from "./pricing.js";
+import { detectColdResume, renderColdResume } from "./coldresume.js";
+import { formatUsd, pricingFor } from "./pricing.js";
 import { checkBudget, loadConfig } from "./config.js";
 /** Default nudge threshold; a project budget or env var can lower/raise it. */
 const DEFAULT_WARN_TOKENS = 80_000;
@@ -119,6 +121,15 @@ async function readStdin() {
         chunks.push(chunk);
     return Buffer.concat(chunks).toString("utf8");
 }
+function settingsHasOurHook() {
+    try {
+        const hooks = JSON.parse(readFileSync(join(homedir(), ".claude", "settings.json"), "utf8"))?.hooks?.UserPromptSubmit;
+        return JSON.stringify(hooks ?? "").includes("context-doctor");
+    }
+    catch {
+        return false;
+    }
+}
 export async function runHook() {
     // A hook must never break the user's prompt: any failure exits silently.
     try {
@@ -126,6 +137,12 @@ export async function runHook() {
         // so if the proxy died, start it now. One existsSync when autopilot is
         // off; a ~1ms localhost health check when it is on and healthy.
         const heal = ensureProxyUp().catch(() => undefined);
+        // Installed both ways (plugin and `context-doctor install`)? The plugin
+        // copy stays silent so the model is told once, not twice.
+        if (process.env.CLAUDE_PLUGIN_ROOT && settingsHasOurHook()) {
+            await heal;
+            return;
+        }
         const input = JSON.parse(await readStdin());
         await heal;
         const transcriptPath = input.transcript_path;
@@ -144,8 +161,28 @@ export async function runHook() {
         // expensive read. Heavy-but-quiet sessions cost one stat + tiny state read.
         const sessionId = input.session_id ?? transcriptPath;
         const prev = readSessionState(sessionId);
-        if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR)
+        // Cold resume: back on a large session after the cache expired. Checked
+        // before the growth gate, because a return after idle involves no growth.
+        // Once per idle period; the tail read is ~1 ms and only on large files.
+        const notes = [];
+        const cold = detectColdResume(transcriptPath);
+        let cr = prev.cr;
+        if (cold && cold.lastReplyAt !== prev.cr) {
+            notes.push(renderColdResume(cold));
+            cr = cold.lastReplyAt;
+            recordLedger({ ev: "cold_resume", sid: sessionId.slice(0, 12), tok: cold.tokens, model: cold.model });
+        }
+        const emit = (lines) => {
+            if (lines.length === 0)
+                return;
+            console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: `<context-doctor>\n${lines.join("\n")}\n</context-doctor>` } }));
+        };
+        if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR) {
+            if (cr !== prev.cr)
+                writeSessionState(sessionId, { ...prev, cr });
+            emit(notes);
             return;
+        }
         // Slow path (growth events only): full parse + profile.
         const parsed = parseSessionFile(transcriptPath);
         if (parsed.messageCount === 0)
@@ -157,18 +194,24 @@ export async function runHook() {
         const liveTokens = parsed.reportedInputTokens ?? profile.totalTokens;
         // Record this parse so the next prompts take fast path 2.
         const shouldWarn = liveTokens >= threshold && liveTokens >= prev.t * REGROWTH_FACTOR;
-        writeSessionState(sessionId, { t: shouldWarn ? liveTokens : prev.t, b: sizeBytes });
+        writeSessionState(sessionId, { t: shouldWarn ? liveTokens : prev.t, b: sizeBytes, cr });
         recordLedger({ ev: "check", sid: sessionId.slice(0, 12), tok: liveTokens, warn: shouldWarn });
-        if (!shouldWarn)
+        if (!shouldWarn) {
+            emit(notes);
             return;
+        }
         const windowPct = profile.contextWindow ? (liveTokens / profile.contextWindow) * 100 : undefined;
-        const costPerCall = profile.cost && profile.totalTokens > 0
-            ? (profile.cost.perCallUsd * liveTokens) / profile.totalTokens
-            : undefined;
+        // Agent sessions run on the prompt cache: a message normally re-reads the
+        // context at the cached rate (0.1x) and pays the full rate only when the
+        // cache has expired. Quoting the uncached figure alone overstated the
+        // per-message cost tenfold (fixed in 0.22).
+        const pricing = pricingFor(parsed.model);
+        const cachedUsd = pricing ? (liveTokens * pricing.cacheReadPerM) / 1e6 : undefined;
+        const coldUsd = pricing ? (liveTokens * pricing.inputPerM * 1.25) / 1e6 : undefined;
         const lines = [
             `This session's context is at ~${formatTokens(liveTokens)} tokens` +
                 (windowPct !== undefined ? ` (${windowPct.toFixed(0)}% of the window)` : "") +
-                (costPerCall !== undefined ? `, costing ~${formatUsd(costPerCall)} of input per message` : "") +
+                (cachedUsd !== undefined ? `: each message re-reads it for ~${formatUsd(cachedUsd)} from the prompt cache, ~${formatUsd(coldUsd)} when the cache has expired` : "") +
                 ".",
             "Practice context hygiene from here on: summarize large tool results instead of keeping them verbatim, reference earlier content rather than re-reading or re-quoting it, and keep responses lean.",
         ];
@@ -184,12 +227,7 @@ export async function runHook() {
         if (liveTokens > threshold * 2) {
             lines.push("If it fits the flow, offer the user a compaction of the older history.");
         }
-        console.log(JSON.stringify({
-            hookSpecificOutput: {
-                hookEventName: "UserPromptSubmit",
-                additionalContext: `<context-doctor>\n${lines.join("\n")}\n</context-doctor>`,
-            },
-        }));
+        emit([...notes, ...lines]);
     }
     catch {
         /* silent — never disturb the prompt */

package/dist/impact.js

@@ -130,8 +130,11 @@ export async function buildImpactReport(proxyPort = 8787) {
                 const p = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
                 totalTokens += p.totalTokens;
                 totalWaste += p.totalEstSavings;
-                if (p.cost)
-                    totalWasteUsd += p.cost.savingsPerCallUsd;
+                // Claude Code sessions run on the prompt cache, so recoverable tokens
+                // cost the cached rate on each message, not the full input rate.
+                const pr = pricingFor(p.model);
+                if (p.cost && pr)
+                    totalWasteUsd += p.cost.savingsPerCallUsd * (pr.cacheReadPerM / pr.inputPerM);
                 const wastePct = p.totalTokens > 0 ? Math.round((p.totalEstSavings / p.totalTokens) * 100) : 0;
                 // Ledger sids are the session UUID's first 12 chars (= filename prefix).
                 const sid = (s.path.split("/").pop() ?? "").slice(0, 12);

package/dist/index.d.ts

@@ -23,3 +23,5 @@ export * from "./preferences.js";
 export * from "./tokenizer-measure.js";
 export * from "./autoclear.js";
 export * from "./autopilot.js";
+export * from "./savings.js";
+export * from "./coldresume.js";

package/dist/index.js

@@ -18,3 +18,5 @@ export * from "./preferences.js";
 export * from "./tokenizer-measure.js";
 export * from "./autoclear.js";
 export * from "./autopilot.js";
+export * from "./savings.js";
+export * from "./coldresume.js";

package/dist/install.js

@@ -470,6 +470,7 @@ export function runInstall(options = {}) {
     else {
         console.log("\nDone. Restart the apps to pick up the new tools, then try:");
         console.log('  "What\'s eating my context?" — or paste a conversation and ask for a profile.');
+        console.log("See what it is worth on your own sessions:   context-doctor savings");
         console.log("Chat apps (Claude Desktop, claude.ai, ChatGPT, phones) have no hook. To make the rules standing there:");
         console.log("  context-doctor instructions --copy   then paste into the app's preferences (it tells you where).");
     }

package/dist/ledger.d.ts

@@ -17,7 +17,7 @@
  */
 export interface LedgerEntry {
     ts: number;
-    ev?: "check" | "optimize" | "proxy" | "rollup";
+    ev?: "check" | "optimize" | "proxy" | "rollup" | "cold_resume";
     sid?: string;
     tok?: number;
     warn?: boolean;

package/dist/mcp.js

@@ -49,7 +49,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.20.1" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.22.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~120 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({

package/dist/proxy.d.ts

@@ -47,7 +47,7 @@ export interface ProxyOptions extends OptimizeOptions {
     openaiUpstream?: string;
 }
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export declare const PROXY_VERSION = "0.20.1";
+export declare const PROXY_VERSION = "0.22.0";
 /**
  * Remove a leading `/t/<token>` from a request path, or return undefined when
  * the prefix is absent or the token differs. The comparison is constant time

package/dist/proxy.js

@@ -20,7 +20,7 @@ import { formatTokens, CHARS_PER_TOKEN, providerFor } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
 import { recordLedger } from "./ledger.js";
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export const PROXY_VERSION = "0.20.1";
+export const PROXY_VERSION = "0.22.0";
 /** Connection-level headers that must not be forwarded. */
 const SKIP_REQUEST_HEADERS = new Set(["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
 const SKIP_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);
@@ -169,8 +169,9 @@ export function startProxy(opts = {}) {
                                 stats.optimizedRequests++;
                                 stats.tokensSaved += r.tokensRemoved;
                                 const pricing = pricingFor(typeof parsed.model === "string" ? parsed.model : undefined);
+                                // What autopilot removes would mostly have been cached reads: price it so.
                                 if (pricing)
-                                    stats.estUsdSaved += inputCostUsd(r.tokensRemoved, pricing);
+                                    stats.estUsdSaved += (r.tokensRemoved / 1e6) * pricing.cacheReadPerM;
                                 note = `autopilot: ${formatTokens(r.tokensRemoved)} tokens of stale tool output not sent (${r.reason})`;
                             }
                             else {

package/dist/savings.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `context-doctor savings`: what autopilot would have saved on YOUR recent
+ * Claude Code sessions, measured, not modelled.
+ *
+ * Each session is replayed request by request, twice: as it was sent, and as
+ * autopilot (autoclear.ts, the shipped class) would have sent it. Both arms
+ * are priced the way the prompt cache bills (reads 0.1x, writes 1.25x, a
+ * cold cache after an idle gap longer than the request's own TTL). The
+ * difference between the arms is the saving. The baseline shown to the user
+ * is not an estimate: it is the input the sessions were actually billed for,
+ * read from the usage every transcript records.
+ */
+import { type AutoClearOptions } from "./autoclear.js";
+export interface SessionSavings {
+    path: string;
+    project: string;
+    model?: string;
+    requests: number;
+    /** Cache-weighted input actually billed (usage in the transcript), in base-input-token units. */
+    billedWeighted: number;
+    billedUsd: number;
+    /** Replay difference, in the same units. */
+    savedWeighted: number;
+    savedUsd: number;
+    /** Raw input tokens autopilot would not have sent. */
+    savedTokens: number;
+    savedPct: number;
+    /** Claude Code surface that ran the session ("cli", "claude-vscode", "claude-desktop", ...). */
+    entrypoint?: string;
+    /** Can a settings-file ANTHROPIC_BASE_URL route this surface through autopilot? */
+    autopilotReachable: boolean;
+    /** Returns to this session after the cache expired, and what /compact then would have saved. */
+    coldResumes: number;
+    coldResumeNetUsd: number;
+}
+/**
+ * The desktop app runs Claude Code "host-orchestrated": it sets
+ * ANTHROPIC_BASE_URL itself and drops the same key from settings files, so
+ * the autopilot proxy cannot sit in front of it (checked in Claude Code
+ * 2.1.284). Terminal and IDE sessions read settings normally.
+ */
+export declare function autopilotReaches(entrypoint?: string): boolean;
+export interface SavingsReport {
+    days: number;
+    sessions: SessionSavings[];
+    billedUsd: number;
+    savedUsd: number;
+    savedTokens: number;
+    billedTokens: number;
+    savedPct: number;
+    worse: number;
+    /** Autopilot's share in sessions it can actually reach. */
+    reachableUsd: number;
+    unreachableSessions: number;
+    coldResumes: number;
+    coldResumeNetUsd: number;
+}
+/** Replay one Claude Code transcript. Undefined when it holds too few requests to mean anything. */
+export declare function replaySession(path: string, options?: AutoClearOptions, since?: number): SessionSavings | undefined;
+export declare function estimateSavings(days?: number, options?: AutoClearOptions, paths?: string[], onProgress?: (done: number, total: number) => void): SavingsReport;
+export declare function renderSavings(r: SavingsReport, autopilotOn?: boolean): string;

package/dist/savings.js

@@ -0,0 +1,238 @@
+/**
+ * `context-doctor savings`: what autopilot would have saved on YOUR recent
+ * Claude Code sessions, measured, not modelled.
+ *
+ * Each session is replayed request by request, twice: as it was sent, and as
+ * autopilot (autoclear.ts, the shipped class) would have sent it. Both arms
+ * are priced the way the prompt cache bills (reads 0.1x, writes 1.25x, a
+ * cold cache after an idle gap longer than the request's own TTL). The
+ * difference between the arms is the saving. The baseline shown to the user
+ * is not an estimate: it is the input the sessions were actually billed for,
+ * read from the usage every transcript records.
+ */
+import { basename, dirname } from "node:path";
+import { AutoClearer } from "./autoclear.js";
+import { coldResumeEvents } from "./coldresume.js";
+import { forEachLine, listSessions } from "./session.js";
+import { pricingFor } from "./pricing.js";
+import { estimateTokens, formatTokens } from "./tokens.js";
+/** System prompt and tool schemas: sent on every request, identical in both arms. */
+const FIXED_TOKENS = 54_000;
+const CLAUDE_CODE_TTL_MS = 3_600_000;
+/**
+ * The desktop app runs Claude Code "host-orchestrated": it sets
+ * ANTHROPIC_BASE_URL itself and drops the same key from settings files, so
+ * the autopilot proxy cannot sit in front of it (checked in Claude Code
+ * 2.1.284). Terminal and IDE sessions read settings normally.
+ */
+export function autopilotReaches(entrypoint) {
+    return !(entrypoint ?? "").startsWith("claude-desktop");
+}
+/** One arm of the replay: the history as sent, priced incrementally. */
+function arm(model, clearer) {
+    const msgs = [];
+    const tok = [];
+    let total = 0, prevLen = 0, weighted = 0, raw = 0;
+    const size = (m) => estimateTokens(JSON.stringify(m), model);
+    return {
+        push(m) { msgs.push(structuredClone(m)); const k = size(m); tok.push(k); total += k; },
+        extend(blocks) {
+            const i = msgs.length - 1;
+            msgs[i].content.push(...structuredClone(blocks));
+            total -= tok[i];
+            tok[i] = size(msgs[i]);
+            total += tok[i];
+        },
+        request(now, cold, counted = true) {
+            let first = -1;
+            if (clearer) {
+                const body = { model, messages: msgs, system: [{ type: "text", text: "", cache_control: { type: "ephemeral", ttl: "1h" } }] };
+                first = clearer.apply(body, now).firstChanged;
+            }
+            if (first >= 0)
+                for (let i = first; i < msgs.length; i++) {
+                    total -= tok[i];
+                    tok[i] = size(msgs[i]);
+                    total += tok[i];
+                }
+            const k = cold ? 0 : Math.min(prevLen, first >= 0 ? first : prevLen);
+            let read = 0;
+            for (let i = 0; i < k; i++)
+                read += tok[i];
+            const write = total - read;
+            if (counted) {
+                weighted += (cold ? FIXED_TOKENS * 1.25 : FIXED_TOKENS * 0.1) + read * 0.1 + write * 1.25;
+                raw += FIXED_TOKENS + total;
+            }
+            prevLen = msgs.length;
+        },
+        get weighted() { return weighted; },
+        get raw() { return raw; },
+    };
+}
+/** Replay one Claude Code transcript. Undefined when it holds too few requests to mean anything. */
+export function replaySession(path, options = {}, since = 0) {
+    let model;
+    let base = arm(undefined, null), auto = arm(undefined, new AutoClearer(options));
+    let baseW = 0, autoW = 0, baseRaw = 0, autoRaw = 0;
+    let entrypoint;
+    let billed = 0, billedRaw = 0, requests = 0, lastId, lastTs = null;
+    const flush = () => { baseW += base.weighted; autoW += auto.weighted; baseRaw += base.raw; autoRaw += auto.raw; };
+    forEachLine(path, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (!entrypoint && typeof e.entrypoint === "string")
+            entrypoint = e.entrypoint;
+        if (e.type === "system" && e.subtype === "compact_boundary") {
+            // Compaction replaces the history in both arms alike: start fresh.
+            flush();
+            base = arm(model, null);
+            auto = arm(model, new AutoClearer(options));
+            return;
+        }
+        if (e.type === "assistant" && e.message) {
+            const m = e.message;
+            model = model ?? m.model;
+            const blocks = (Array.isArray(m.content) ? m.content : []).filter((b) => b?.type !== "thinking" && b?.type !== "redacted_thinking");
+            if (m.id !== lastId) {
+                lastId = m.id;
+                const u = m.usage ?? {};
+                const read = u.cache_read_input_tokens ?? 0, write = u.cache_creation_input_tokens ?? 0, fresh = u.input_tokens ?? 0;
+                if (read + write + fresh > 0) {
+                    const now = Date.parse(e.timestamp) || 0;
+                    // History before the window still shapes the replay's state; only
+                    // requests inside the window are billed and counted.
+                    const inWindow = now >= since;
+                    if (inWindow) {
+                        billed += fresh + read * 0.1 + write * 1.25;
+                        billedRaw += fresh + read + write;
+                        requests++;
+                    }
+                    const cold = lastTs === null || now - lastTs > CLAUDE_CODE_TTL_MS;
+                    base.request(now, cold, inWindow);
+                    auto.request(now, cold, inWindow);
+                    lastTs = now;
+                }
+                base.push({ role: "assistant", content: blocks });
+                auto.push({ role: "assistant", content: blocks });
+            }
+            else {
+                base.extend(blocks);
+                auto.extend(blocks);
+            }
+        }
+        else if (e.type === "user" && e.message) {
+            const c = e.message.content;
+            const msg = { role: "user", content: Array.isArray(c) ? c : [{ type: "text", text: String(c ?? "") }] };
+            base.push(msg);
+            auto.push(msg);
+        }
+    });
+    flush();
+    if (requests < 10 || billed <= 0)
+        return undefined;
+    // The replay decides the SHARE saved (both arms priced the same way); that
+    // share is applied to what was actually billed, so the dollars and tokens
+    // shown are fractions of the user's real usage, not of an estimate.
+    const perM = pricingFor(model)?.inputPerM ?? 0;
+    const cold = coldResumeEvents(path).filter((c) => c.at >= since);
+    const pct = baseW > 0 ? (baseW - autoW) / baseW : 0;
+    const rawPct = baseRaw > 0 ? (baseRaw - autoRaw) / baseRaw : 0;
+    const dir = basename(dirname(path));
+    return {
+        path,
+        project: dir.replace(/^-Users-[^-]+-/, "").replace(/^-/, "") || dir,
+        model,
+        requests,
+        billedWeighted: billed,
+        billedUsd: (billed / 1e6) * perM,
+        savedWeighted: pct * billed,
+        savedUsd: ((pct * billed) / 1e6) * perM,
+        savedTokens: rawPct * billedRaw,
+        savedPct: pct,
+        entrypoint,
+        autopilotReachable: autopilotReaches(entrypoint),
+        coldResumes: cold.length,
+        coldResumeNetUsd: cold.reduce((n, c) => n + c.netUsd, 0),
+    };
+}
+export function estimateSavings(days = 30, options = {}, paths, onProgress) {
+    const since = Date.now() - days * 86_400_000;
+    const targets = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
+    const sessions = [];
+    for (const [i, p] of targets.entries()) {
+        onProgress?.(i, targets.length);
+        try {
+            const s = replaySession(p, options, since);
+            if (s)
+                sessions.push(s);
+        }
+        catch {
+            /* one unreadable transcript must not sink the report */
+        }
+    }
+    const sum = (k) => sessions.reduce((n, s) => n + s[k], 0);
+    const billedUsd = sum("billedUsd"), savedUsd = sum("savedUsd");
+    const billedW = sum("billedWeighted");
+    const savedPct = billedW > 0 ? sum("savedWeighted") / billedW : 0;
+    return {
+        days,
+        sessions: sessions.sort((a, b) => b.savedUsd - a.savedUsd),
+        billedUsd,
+        savedUsd,
+        savedTokens: sum("savedTokens"),
+        billedTokens: sessions.reduce((n, s) => n + s.billedWeighted, 0),
+        savedPct,
+        worse: sessions.filter((s) => s.savedPct < -1e-9).length,
+        reachableUsd: sessions.filter((s) => s.autopilotReachable).reduce((n, s) => n + s.savedUsd, 0),
+        unreachableSessions: sessions.filter((s) => !s.autopilotReachable).length,
+        coldResumes: sum("coldResumes"),
+        coldResumeNetUsd: sum("coldResumeNetUsd"),
+    };
+}
+const tokens = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(1)}B` : formatTokens(n));
+const usd = (n) => (n >= 100 ? `$${Math.round(n).toLocaleString("en-US")}` : `$${n.toFixed(2)}`);
+export function renderSavings(r, autopilotOn = false) {
+    const lines = [];
+    if (r.sessions.length === 0) {
+        lines.push(`No Claude Code sessions with 10+ requests in the last ${r.days} days to replay.`);
+        lines.push("Use Claude Code for a while, then run this again: `context-doctor savings`.");
+        return lines.join("\n");
+    }
+    const n = r.sessions.length;
+    const allDesktop = r.unreachableSessions === n;
+    lines.push(`What context-doctor finds in your Claude Code sessions (last ${r.days} days, ${n} session${n === 1 ? "" : "s"})`);
+    lines.push("─".repeat(64));
+    lines.push(`Input you were billed for        ${usd(r.billedUsd).padStart(10)}   from the usage your transcripts record`);
+    lines.push("");
+    lines.push(`1. Compact when you come back    ${usd(Math.max(0, r.coldResumeNetUsd)).padStart(10)}   ${r.coldResumes} return${r.coldResumes === 1 ? "" : "s"} to a session over 150k tokens`);
+    lines.push("   after the prompt cache expired. Running /compact then, net of the compaction");
+    lines.push("   itself, would have saved this. The every-prompt hook points these moments out;");
+    lines.push("   it works in every Claude Code surface, the desktop app included.");
+    lines.push("");
+    if (allDesktop) {
+        lines.push(`2. Autopilot                     ${"n/a".padStart(10)}   all ${n} sessions ran in the desktop app, which`);
+        lines.push("   sets its own API address, so the autopilot proxy cannot sit in front of it.");
+        lines.push(`   (Had they run in the terminal or an IDE: ${usd(r.savedUsd)}, ${(r.savedPct * 100).toFixed(1)}%.)`);
+    }
+    else {
+        lines.push(`2. Autopilot                     ${usd(r.reachableUsd).padStart(10)}   stale tool output cleared only when the cache`);
+        lines.push(`   is cold (never costs more; ${r.worse} session${r.worse === 1 ? "" : "s"} made more expensive), ${tokens(r.savedTokens)} tokens not sent.`);
+        if (r.unreachableSessions > 0)
+            lines.push(`   Counts terminal and IDE sessions only; ${r.unreachableSessions} desktop-app session${r.unreachableSessions === 1 ? "" : "s"} excluded (not reachable).`);
+        if (!autopilotOn)
+            lines.push("   Turn it on:  context-doctor autopilot on");
+    }
+    lines.push("");
+    lines.push("Replayed request by request through the shipped code and priced as the prompt");
+    lines.push("cache bills, at list prices. On a subscription the same tokens come out of your");
+    lines.push("usage limit instead.");
+    return lines.join("\n");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "context-doctor",
-  "version": "0.20.1",
-  "description": "Keep AI coding sessions lean automatically: clears stale tool output from every Claude Code and GPT API request, only when it costs nothing extra (measured 9.8% less input, no session worse). Token profiler, hooks and MCP tools for Claude Code, Cursor, Codex and Claude Desktop.",
+  "version": "0.22.0",
+  "description": "See what your Claude Code sessions cost and cut it: offers /compact when you return to a large session after the cache expired (every surface, desktop app included), and a cache-safe autopilot for terminal, IDE and API traffic. Token profiler, hooks, MCP tools and a Claude Code plugin.",
   "keywords": [
     "agent",
     "ai-agents",
@@ -46,6 +46,7 @@
   "files": [
     "dist",
     "!dist/test",
+    "!dist/mcp.bundle.js",
     "skills",
     "README.md",
     "LICENSE"
@@ -54,11 +55,12 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
+    "build": "tsc && node scripts/bundle-mcp.mjs && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
     "prepublishOnly": "npm test",
     "dev": "tsc --watch",
     "test": "npm run build && node scripts/test.mjs",
-    "build:mcpb": "npm run build && node scripts/build-mcpb.mjs"
+    "build:mcpb": "npm run build && node scripts/build-mcpb.mjs",
+    "version": "node scripts/sync-versions.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -66,10 +68,12 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "esbuild": "^0.25.12",
     "typescript": "^5.5.0"
   },
   "homepage": "https://github.com/KushalP1/context-doctor#readme",
   "bugs": {
     "url": "https://github.com/KushalP1/context-doctor/issues"
-  }
+  },
+  "mcpName": "io.github.KushalP1/context-doctor"
 }