context-doctor 0.21.0 → 0.23.0

package/README.md

@@ -2,14 +2,14 @@
 
 [![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).
 
@@ -21,16 +21,9 @@ Built and maintained by [gAI Ventures](https://gai.ventures).
 npx context-doctor savings
 ```
 
-```
-What autopilot would have saved you (last 30 days, 53 Claude Code sessions)
-────────────────────────────────────────────────────────
-Input you were billed for           $11,205   (from the usage your transcripts record)
-Autopilot would have cut             $1,396   12.5%, 1.2B tokens not sent
-Sessions made more expensive              0
-Biggest win                            $503   tech-Whatsit (31% of that session)
-```
+<img src="https://raw.githubusercontent.com/KushalP1/context-doctor/main/assets/savings.svg" alt="npx context-doctor savings: input billed, what /compact at cold resumes and autopilot would have saved" width="640">
 
-That is the author's machine. Yours is computed the same way: every recent session replayed request by request through the shipped autopilot code, against what your transcripts show you were actually billed.
+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. `context-doctor savings --share` prints a few lines with totals only (no project names or paths) if you want to post your number.
 
 **Then install it**, whichever way suits you:
 
@@ -69,26 +62,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 | Install via npm or as a **plugin** (`/plugin marketplace add KushalP1/context-doctor`). Status bar context meter, `/context-doctor:savings`, `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 |
@@ -101,6 +104,7 @@ 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`.
@@ -236,7 +240,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/autoclear.js

@@ -54,7 +54,9 @@ export const CLEARABLE_TOOLS = new Set([
 const IMAGE_TOKENS = 1600;
 const HOUR = 3_600_000;
 export function clearedNote(tokens) {
-    return `[context-doctor: old tool output cleared to keep context lean (~${tokens} tokens). Run the tool again if you need it.]`;
+    // Not "run it again": a cleared Bash result may come from a command with
+    // side effects (a push, a delete), and repeating that would be wrong.
+    return `[context-doctor: old tool output cleared to keep context lean (~${tokens} tokens). The call above shows what ran; repeat it only if it is read-only, otherwise ask the user.]`;
 }
 function resultTokens(content, model) {
     if (typeof content === "string")

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";
@@ -190,6 +190,64 @@ function readConfig(paths) {
         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");
 }
@@ -242,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 };
 }
@@ -299,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)`);

package/dist/cli.js

@@ -22,7 +22,7 @@ import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
 import { measureTokenizer, renderTokenizer } from "./tokenizer-measure.js";
 import { autopilotOff, autopilotOn, autopilotPause, autopilotPaths, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
-import { estimateSavings, renderSavings } from "./savings.js";
+import { estimateSavings, renderSavings, renderShare } from "./savings.js";
 import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
@@ -50,9 +50,12 @@ Usage:
   context-doctor install                        Wire the MCP server + skill into Claude Desktop,
                                                 Claude Code, and Cursor automatically
   context-doctor uninstall                      Undo install
-  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 --version                      Print the installed version
+  context-doctor savings [--days n] [--share [--copy]]
+                                                What your recent Claude Code sessions cost, and what
+                                                /compact at cold resumes and autopilot would save,
+                                                replayed and priced as billed. --share: totals only,
+                                                to paste. 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
@@ -148,6 +151,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;
@@ -173,19 +180,19 @@ function parseArgs(argv) {
                 args.strategies.push(argv[++i]);
                 break;
             case "--keep-recent":
-                args.keepRecent = Number(argv[++i]);
+                args.keepRecent = numArg("--keep-recent", argv[++i], { min: 0, integer: true });
                 break;
             case "--max-tool-tokens":
-                args.maxToolTokens = Number(argv[++i]);
+                args.maxToolTokens = numArg("--max-tool-tokens", argv[++i], { min: 1, integer: true });
                 break;
             case "--port":
-                args.port = Number(argv[++i]);
+                args.port = numArg("--port", argv[++i], { min: 0, max: 65535, integer: true });
                 break;
             case "--interval-ms":
-                args.intervalMs = Number(argv[++i]);
+                args.intervalMs = numArg("--interval-ms", argv[++i], { min: 100, integer: true });
                 break;
             case "--limit":
-                args.limit = Number(argv[++i]);
+                args.limit = numArg("--limit", argv[++i], { min: 1, integer: true });
                 break;
             case "--task":
                 args.task = argv[++i];
@@ -197,7 +204,7 @@ function parseArgs(argv) {
                 args.existing = argv[++i];
                 break;
             case "--budget":
-                args.budgetUsd = Number(argv[++i]);
+                args.budgetUsd = numArg("--budget", argv[++i], { min: 0 });
                 break;
             case "--dry-run":
                 args.dryRun = true;
@@ -205,6 +212,9 @@ function parseArgs(argv) {
             case "--copy":
                 args.copy = true;
                 break;
+            case "--share":
+                args.share = true;
+                break;
             case "--allow-dirty":
                 args.allowDirty = true;
                 break;
@@ -218,7 +228,7 @@ function parseArgs(argv) {
                 args.token = argv[++i];
                 break;
             case "--days":
-                args.days = Number(argv[++i]);
+                args.days = numArg("--days", argv[++i], { min: 1 });
                 break;
             case "--autopilot":
                 args.autopilot = true;
@@ -275,6 +285,30 @@ 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";
+    }
+}
+/**
+ * A numeric flag's value, or exit 1 with a message naming the flag. Number()
+ * alone turned `--days abc` into "the last NaN days" and a bad --port into a
+ * random port.
+ */
+function numArg(flag, raw, { min, max, integer } = {}) {
+    const n = Number(raw);
+    const ok = raw !== undefined && raw.trim() !== "" && Number.isFinite(n) && (!integer || Number.isInteger(n)) && (min === undefined || n >= min) && (max === undefined || n <= max);
+    if (!ok) {
+        const range = min !== undefined && max !== undefined ? ` between ${min} and ${max}` : min !== undefined ? ` of at least ${min}` : "";
+        console.error(`${flag} needs ${integer ? "a whole number" : "a number"}${range}; got ${raw === undefined ? "nothing" : JSON.stringify(raw)}.`);
+        process.exit(1);
+    }
+    return n;
+}
 /** Any Claude Code transcript on this machine? One directory listing, no parsing. */
 function hasClaudeSessions() {
     try {
@@ -490,6 +524,12 @@ async function main() {
         const on = existsSync(autopilotPaths().config);
         if (args.json)
             console.log(JSON.stringify(report, null, 2));
+        else if (args.share) {
+            const text = renderShare(report);
+            console.log(text);
+            if (args.copy)
+                console.log(copyToClipboard(text) ? "\n(copied to the clipboard)" : "\n(no clipboard tool found; copy the lines above)");
+        }
         else {
             console.log(renderSavings(report, on));
             if (!args.command)
@@ -568,6 +608,11 @@ async function main() {
         return; // server keeps the process alive
     }
     if (!args.command || !args.file) {
+        const known = ["analyze", "optimize"];
+        if (args.command && !known.includes(args.command)) {
+            console.error(`Unknown command "${args.command}". Run \`context-doctor --help\` for the list.`);
+            process.exit(1);
+        }
         console.log(HELP);
         process.exit(args.command ? 1 : 0);
     }

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,180 @@
+/**
+ * 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;
+            }
+            // Compacted since the last reply: the old usage no longer describes the
+            // context, and there is nothing large left to warn about.
+            if (e?.type === "system" && e.subtype === "compact_boundary")
+                return undefined;
+            if (e?.isCompactSummary)
+                return undefined;
+            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

@@ -20,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;
@@ -160,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)
@@ -173,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.",
         ];
@@ -200,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

@@ -24,3 +24,4 @@ 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

@@ -19,3 +19,4 @@ 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.21.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.23.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.21.0";
+export declare const PROXY_VERSION = "0.23.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.21.0";
+export const PROXY_VERSION = "0.23.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

@@ -25,7 +25,21 @@ export interface SessionSavings {
     /** 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[];
@@ -35,8 +49,18 @@ export interface SavingsReport {
     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): SessionSavings | undefined;
+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;
+/**
+ * `savings --share`: a few lines people can paste or screenshot. Totals only:
+ * no project names, paths or session ids, so sharing it leaks nothing.
+ */
+export declare function renderShare(r: SavingsReport): string;

package/dist/savings.js

@@ -12,12 +12,22 @@
  */
 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 = [];
@@ -33,7 +43,7 @@ function arm(model, clearer) {
             tok[i] = size(msgs[i]);
             total += tok[i];
         },
-        request(now, cold) {
+        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" } }] };
@@ -50,8 +60,10 @@ function arm(model, clearer) {
             for (let i = 0; i < k; i++)
                 read += tok[i];
             const write = total - read;
-            weighted += (cold ? FIXED_TOKENS * 1.25 : FIXED_TOKENS * 0.1) + read * 0.1 + write * 1.25;
-            raw += FIXED_TOKENS + total;
+            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; },
@@ -59,10 +71,11 @@ function arm(model, clearer) {
     };
 }
 /** Replay one Claude Code transcript. Undefined when it holds too few requests to mean anything. */
-export function replaySession(path, options = {}) {
+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) => {
@@ -75,6 +88,8 @@ export function replaySession(path, options = {}) {
         }
         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();
@@ -91,13 +106,18 @@ export function replaySession(path, options = {}) {
                 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) {
-                    billed += fresh + read * 0.1 + write * 1.25;
-                    billedRaw += fresh + read + write;
-                    requests++;
                     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);
-                    auto.request(now, cold);
+                    base.request(now, cold, inWindow);
+                    auto.request(now, cold, inWindow);
                     lastTs = now;
                 }
                 base.push({ role: "assistant", content: blocks });
@@ -122,6 +142,7 @@ export function replaySession(path, options = {}) {
     // 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));
@@ -136,6 +157,10 @@ export function replaySession(path, options = {}) {
         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) {
@@ -145,7 +170,7 @@ export function estimateSavings(days = 30, options = {}, paths, onProgress) {
     for (const [i, p] of targets.entries()) {
         onProgress?.(i, targets.length);
         try {
-            const s = replaySession(p, options);
+            const s = replaySession(p, options, since);
             if (s)
                 sessions.push(s);
         }
@@ -166,6 +191,10 @@ export function estimateSavings(days = 30, options = {}, paths, onProgress) {
         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));
@@ -177,22 +206,58 @@ export function renderSavings(r, autopilotOn = false) {
         lines.push("Use Claude Code for a while, then run this again: `context-doctor savings`.");
         return lines.join("\n");
     }
-    const title = autopilotOn ? "What autopilot saves on your sessions" : "What autopilot would have saved you";
-    lines.push(`${title} (last ${r.days} days, ${r.sessions.length} Claude Code session${r.sessions.length === 1 ? "" : "s"})`);
-    lines.push("─".repeat(56));
-    lines.push(`Input you were billed for     ${usd(r.billedUsd).padStart(10)}   (from the usage your transcripts record)`);
-    lines.push(`Autopilot would have cut      ${usd(r.savedUsd).padStart(10)}   ${(r.savedPct * 100).toFixed(1)}%, ${tokens(r.savedTokens)} tokens not sent`);
-    lines.push(`Sessions made more expensive  ${String(r.worse).padStart(10)}`);
-    const best = r.sessions[0];
-    if (best && best.savedUsd > 0)
-        lines.push(`Biggest win                   ${usd(best.savedUsd).padStart(10)}   ${best.project} (${(best.savedPct * 100).toFixed(0)}% of that session)`);
+    const n = r.sessions.length;
+    const allDesktop = r.unreachableSessions === n;
+    const pct = (x) => (r.billedUsd > 0 ? ` (${Math.round((x / r.billedUsd) * 100)}%)` : "");
+    // Kept within 80 columns: this is most people's first screen of the tool.
+    lines.push("What context-doctor finds in your Claude Code sessions");
+    lines.push(`Last ${r.days} days, ${n} session${n === 1 ? "" : "s"}, priced at list prices`);
+    lines.push("─".repeat(60));
+    lines.push(`Input you were billed for         ${usd(r.billedUsd).padStart(9)}   from your transcripts' usage`);
     lines.push("");
-    lines.push("Replayed request by request through the shipped autopilot code and priced as");
-    lines.push("the prompt cache bills. List prices; on a subscription the same tokens come");
-    lines.push("out of your usage limit instead.");
-    if (!autopilotOn) {
-        lines.push("");
-        lines.push("Turn it on for every new session:  context-doctor autopilot on");
+    lines.push(`1. Compact when you come back     ${usd(Math.max(0, r.coldResumeNetUsd)).padStart(9)}${pct(Math.max(0, r.coldResumeNetUsd))}`);
+    lines.push(`   ${r.coldResumes} return${r.coldResumes === 1 ? "" : "s"} to a session over 150k tokens after the prompt cache`);
+    lines.push("   expired. Running /compact then, net of the compaction itself, would");
+    lines.push("   have saved this. The every-prompt hook points these moments out, in");
+    lines.push("   every Claude Code surface, the desktop app included.");
+    lines.push("");
+    if (allDesktop) {
+        lines.push(`2. Autopilot                      ${"n/a".padStart(9)}`);
+        lines.push(`   All ${n} sessions ran in the desktop app, which sets its own API`);
+        lines.push("   address, so the autopilot proxy cannot sit in front of them. In a");
+        lines.push(`   terminal or an IDE they would have saved ${usd(r.savedUsd)} (${(r.savedPct * 100).toFixed(1)}%).`);
+    }
+    else {
+        lines.push(`2. Autopilot                      ${usd(r.reachableUsd).padStart(9)}${pct(r.reachableUsd)}`);
+        lines.push("   Stale tool output cleared only when the cache is cold, so it never");
+        lines.push(`   costs more (${r.worse} session${r.worse === 1 ? "" : "s"} made more expensive); ${tokens(r.savedTokens)} tokens not sent.`);
+        if (r.unreachableSessions > 0)
+            lines.push(`   Terminal and IDE sessions only; ${r.unreachableSessions} desktop-app session${r.unreachableSessions === 1 ? "" : "s"} 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");
+    lines.push("prompt cache bills. On a subscription the same tokens come out of your");
+    lines.push("usage limit instead. Share yours: context-doctor savings --share");
+    return lines.join("\n");
+}
+/**
+ * `savings --share`: a few lines people can paste or screenshot. Totals only:
+ * no project names, paths or session ids, so sharing it leaks nothing.
+ */
+export function renderShare(r) {
+    if (r.sessions.length === 0)
+        return "context-doctor found no Claude Code sessions to measure yet.";
+    const lines = [
+        `My Claude Code input, last ${r.days} days: ${usd(r.billedUsd)} at list price (${r.sessions.length} sessions).`,
+    ];
+    if (r.coldResumeNetUsd > 0) {
+        lines.push(`Running /compact when I came back to a big session after the cache expired would have saved ${usd(r.coldResumeNetUsd)} (${Math.round((r.coldResumeNetUsd / r.billedUsd) * 100)}%, ${r.coldResumes} times).`);
+    }
+    if (r.reachableUsd > 0) {
+        lines.push(`Clearing stale tool output only when the cache is cold would have cut another ${usd(r.reachableUsd)}, with no session made more expensive.`);
     }
+    lines.push("Measured from my own transcripts with context-doctor: npx context-doctor savings");
     return lines.join("\n");
 }

package/dist/sketch.js

@@ -128,7 +128,7 @@ export function profileSketch(sketch) {
             severity: totalTokens > 100_000 ? "high" : "warn",
             estSavings: Math.max(0, totalTokens - afterHandoff),
             message: `${turns} turns: every new message re-reads ~${formatTokens(totalTokens)}.`,
-            action: `Offer a handoff: write a ≤${HANDOFF_SUMMARY_TOKENS}-token summary (decisions, current state, open items, key identifiers) for the user to start a new chat with. A fresh chat re-reads ~${formatTokens(afterHandoff)} instead.`,
+            action: `Offer a handoff: write a ≤${HANDOFF_SUMMARY_TOKENS}-token summary (decisions, current state, open items, key identifiers) for the user to start a new chat with. A fresh chat re-reads ~${formatTokens(afterHandoff)} of conversation instead, plus the app's own system prompt, which every chat carries.`,
         });
     }
     const contextWindow = contextWindowFor(sketch.model);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "context-doctor",
-  "version": "0.21.0",
-  "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.23.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",