context-doctor 0.23.1 → 0.25.0

package/README.md

@@ -7,6 +7,7 @@
 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.
 
 - **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)
+- **Compacts earlier, automatically, in every Claude Code surface.** Claude Code auto-compacts near the full window (measured: ~970k tokens on a 1M model), so long sessions re-read 400k-900k tokens on every message. `context-doctor compact-window` replays your history at smaller windows and, if you choose, sets Claude Code's own `autoCompactWindow`. On the author's last 30 days: **a 400k window would have cut input cost 55%** ($6,119 to $2,757), for 15 compactions a week instead of 5. A native setting, so it works in the desktop app too. [The trade-off →](#3-compacting-earlier-automatic)
 - **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.
@@ -21,7 +22,7 @@ Built and maintained by [gAI Ventures](https://gai.ventures).
 npx context-doctor savings
 ```
 
-<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">
+<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, autopilot and an earlier auto-compact window would have saved" width="640">
 
 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.
 
@@ -40,7 +41,7 @@ context-doctor autopilot on     # every new Claude Code session keeps its contex
 /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.
+The plugin brings the every-prompt check, the MCP tools, and `/context-doctor:savings`, `/context-doctor:checkup`, `/context-doctor:autopilot` and `/context-doctor:compact-window`. 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.
 
 `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`.
 
@@ -84,14 +85,26 @@ Each return counts only the messages up to the next return, and the compaction r
 
 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.
 
+**3. Compacting earlier** <a id="3-compacting-earlier-automatic"></a>(automatic, every Claude Code surface, desktop app included). The offer in 1 is advice, and on the author's machine it was followed 1 time in 33. Claude Code has a native setting that needs nobody to follow anything: `autoCompactWindow` in `~/.claude/settings.json` makes it compact as if the window were that size. `context-doctor compact-window` replays each session request by request at several sizes, priced as the cache bills (each simulated compaction pays its own request and a 20k-token summary at the output rate), and changes nothing until you pick one:
+
+| Window | Input cost, last 30 days | Saved | Compactions a week |
+|---|---|---|---|
+| as now (~970k) | $6,119 | | 5.1 |
+| 600k | $3,570 | $2,549 (42%) | 6.5 |
+| **400k** | **$2,757** | **$3,362 (55%)** | **14.7** |
+| 300k | $2,353 | $3,766 (62%) | 24.5 |
+| 200k | $1,963 | $4,155 (68%) | 46.9 |
+
+29 sessions. The replay's baseline came within 9% of what the transcripts say was billed, on the low side. The cost is real: each compaction replaces the session's history with a summary, so a smaller window trades detail for money. That is why the command shows the table first and sets a window only when you name one (`context-doctor compact-window 400k`; `off` undoes it, and a backup of settings.json is kept).
+
 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** 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 |
+| **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. **`compact-window`**, if you set one |
+| **Claude Code** in the desktop app's Code tab | **Hook**, as above, including the cold-resume `/compact` offer, shown to you as well as the model. **`compact-window`**, if you set one: Claude Code compacts earlier by itself. Not autopilot: the app sets its own API address and ignores the one in settings | 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 |
@@ -103,7 +116,9 @@ Not claimed, because no process on your machine sends those requests: trimming i
 
 ## What's new
 
+- **0.25 Compact earlier, by itself**: the `/compact` offer at cold resumes was followed 1 time in 33 on the author's machine, so two changes. The hook now also shows you the notice (it went only to the model, which rarely raised it), with the dollar cost of the message you just sent. And `context-doctor compact-window` measures and sets Claude Code's own auto-compact window, which works without anyone acting on advice, in every surface including the desktop app: 55% less input cost at 400k on the author's last 30 days. `savings` shows it as a third lever.
 - **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.24 A full audit, fixed**: the session parser now rebuilds API messages from Claude Code's one-row-per-block transcripts (it had split each reply into several messages, breaking tool pairing in exported conversations and inflating profiles); the proxy forwards every non-conversation endpoint and never re-encodes bodies it does not rewrite (model listing and file uploads failed or were corrupted through it); `report` and the dashboard no longer count compaction as tokens context-doctor saved, and MCP sketches no longer inflate them; `watch` follows plain conversation files; MCP inputs are bounded. 0.23: four dependency vulnerabilities patched, no false `/compact` alarm after compacting, `savings --share`.
 - **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.
@@ -169,7 +184,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 savings [--days n] [--share [--copy]]` | What your recent Claude Code sessions cost, and what `/compact` at cold resumes, autopilot and an earlier auto-compact window would save, replayed through the shipped code against your actual billed usage. `--share` prints totals only (no project names or paths) to post. A bare `context-doctor` in a terminal shows the same |
+| `context-doctor compact-window [status\|off\|<size>]` | Replay your last 30 days at auto-compact windows from 200k to 800k: input cost, saving, and how many more compactions each means. `400k` (or `250000`, `0.4m`) sets Claude Code's `autoCompactWindow`, with a backup; `off` removes it. Works in every Claude Code surface, the desktop app included |
 | `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 |
@@ -181,9 +197,9 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor diff <before> <after>` | Compare two profiles: what moved by category, which findings were resolved or introduced, and what it saves in money and latency |
 | `context-doctor accuracy` | How much of what you are billed for is visible in your transcript (the fixed harness baseline, per-turn injected content), plus a tokenizer check: real chars/token per model from the API's own counts, next to the ratio the estimator uses |
 | `context-doctor cursor [--list]` | Profile a chat from Cursor's local history (both storage formats) |
-| `context-doctor report` | Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, recoverable waste in recent sessions |
+| `context-doctor report` | Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, how often the cold-resume `/compact` offer was followed by a compaction, recoverable waste in recent sessions |
 | `context-doctor proxy` | Always-on local proxy that optimizes every Anthropic/OpenAI API request in flight (`/stats` for cumulative savings) |
-| `context-doctor watch [file]` | Live monitor of a growing session/agent trace: token/cost line per change, findings as they appear |
+| `context-doctor watch [file]` | Live monitor of a growing session transcript or agent trace (Claude Code / Codex JSONL, or a plain OpenAI/Anthropic conversation JSON file): token/cost line per change, findings as they appear |
 | `context-doctor doctor` | Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes |
 | `context-doctor dashboard` | Local savings dashboard on 127.0.0.1: tokens saved per day, sessions by context in use vs recoverable, budget status |
 | `context-doctor statusline` | Claude Code status bar: live context vs window, cache share, cost. Wired by `install --statusline`; never overwrites a statusLine you already have |
@@ -240,7 +256,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 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.
+`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 levers that work are the cold-resume advice and `compact-window`. 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.
 
@@ -281,6 +297,8 @@ The proxy dedupes repeated content, trims stale tool results, and strips base64
 [context-doctor] POST /v1/messages → 200 in 842ms | optimized 7.3k → 518 tokens (2 changes) | session total: 6.9k tokens ≈ $0.021 saved
 ```
 
+Only conversation requests (`/v1/messages`, `/v1/chat/completions`, `/v1/responses`) are ever rewritten. Every other endpoint a client uses through the proxy (listing models, uploading files, counting tokens) is forwarded untouched, to Anthropic when the request carries `anthropic-version` or `x-api-key` and to OpenAI otherwise, and request bodies the proxy does not rewrite reach upstream byte for byte.
+
 `GET http://localhost:8787/stats` returns cumulative savings (requests, tokens, estimated USD), **exact upstream usage** read from every response (JSON and SSE), and **prompt-cache advisories** — the proxy watches your real traffic and flags big stable prefixes missing `cache_control` or prefix churn that silently re-bills the cache. Per-model behavior via `--config`: The advisor now says *where*: for a large system/tools prefix it names the block to mark (the last tool definition, or the last system block), and when the older messages were byte-identical to the previous request it names the exact message to put `cache_control` on, with the token count that run is re-billing each turn. Anyone who already placed breakpoints is left alone.
 
 ```json
@@ -521,7 +539,7 @@ One report for your whole machine, led by a headline of **tokens context-doctor
 
 - **exact** proxy savings (real before/after on every request),
 - **exact** savings from every optimization applied via the CLI or the in-chat tools — split by model family (Claude vs GPT), with dollar estimates,
-- **observed per-session shrinkage**: real context reductions recorded between the hook's deep checks after hygiene warnings — shown per session in the table alongside remaining waste.
+- and, **on its own line, not in the total**: sessions that got smaller after a hygiene warning. That is mostly compaction, by you or by Claude Code, and a warning may or may not be why it happened, so it is not credited to context-doctor (until 0.24 it was, which overclaimed). The dashboard keeps the same split.
 
 Honest measurement note: proxy numbers are exact. Session numbers are measured-now. What no tool can report is the counterfactual — tokens Claude *avoided* adding because of the hygiene guidance — since the same session can't be re-run without it. The report says so instead of inventing a number.
 

package/dist/autopilot.js

@@ -253,7 +253,8 @@ export function reachNote(days = 30) {
         `! ${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`).",
+        "  hook points out when /compact would pay off, and `context-doctor compact-window` makes Claude Code",
+        "  compact earlier by itself, which the desktop app honours (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.");

package/dist/cli.js

@@ -23,6 +23,7 @@ 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, renderShare } from "./savings.js";
+import { currentCompactWindow, estimateCompactWindows, MAX_WINDOW, MIN_WINDOW, parseWindow, renderCompactWindows, setCompactWindow } from "./compactwindow.js";
 import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
@@ -56,6 +57,10 @@ Usage:
                                                 /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 compact-window [status|off|<size>]
+                                                Claude Code's own auto-compact window (e.g. 400k):
+                                                what each size would have saved on your sessions,
+                                                and set or remove it. Works in the desktop app too
   context-doctor autopilot on|off|pause|resume|status
                                                 Every new Claude Code session goes through the
                                                 local proxy, which clears stale tool output only
@@ -521,6 +526,12 @@ async function main() {
         const report = estimateSavings(args.days ?? 30, {}, undefined, progress);
         if (progress)
             process.stderr.write("\r\x1b[K");
+        const setWindow = currentCompactWindow();
+        const cwReport = estimateCompactWindows([setWindow ?? 400_000], args.days ?? 30);
+        const est = cwReport.estimates[0];
+        const cwLine = cwReport.sessions > 0 && est
+            ? { window: est.window, savedUsd: est.savedUsd, compactionsPerWeek: (est.compactions / cwReport.days) * 7, nowPerWeek: (cwReport.actualCompactions / cwReport.days) * 7, isCurrent: setWindow !== undefined }
+            : undefined;
         const on = existsSync(autopilotPaths().config);
         if (args.json)
             console.log(JSON.stringify(report, null, 2));
@@ -531,7 +542,7 @@ async function main() {
                 console.log(copyToClipboard(text) ? "\n(copied to the clipboard)" : "\n(no clipboard tool found; copy the lines above)");
         }
         else {
-            console.log(renderSavings(report, on));
+            console.log(renderSavings(report, on, cwLine));
             if (!args.command)
                 console.log("\nAll commands: context-doctor --help");
         }
@@ -546,6 +557,34 @@ async function main() {
         await import("./mcp.js");
         return;
     }
+    if (args.command === "compact-window") {
+        const sub = args.file ?? "status";
+        if (sub === "off") {
+            setCompactWindow(undefined);
+            console.log("✓ autoCompactWindow removed from ~/.claude/settings.json: Claude Code compacts near the model's full window again (new sessions).");
+            return;
+        }
+        if (sub !== "status") {
+            const w = parseWindow(sub);
+            if (w === undefined || w < MIN_WINDOW || w > MAX_WINDOW) {
+                console.error(`Usage: context-doctor compact-window [status | off | <size>], size between 100k and 1m (e.g. 400k); got "${sub}".`);
+                process.exitCode = 1;
+                return;
+            }
+            setCompactWindow(w);
+            console.log(`✓ autoCompactWindow = ${w} in ~/.claude/settings.json (a .backup was kept).`);
+            console.log("  Claude Code sessions started from now on compact as if the window were that size,");
+            console.log("  in the terminal, IDEs and the desktop app. Check in a session with /context.");
+            console.log("  Undo: context-doctor compact-window off");
+            return;
+        }
+        const current = currentCompactWindow();
+        const windows = [200_000, 300_000, 400_000, 600_000, 800_000];
+        if (current && !windows.includes(current))
+            windows.push(current);
+        console.log(renderCompactWindows(estimateCompactWindows(windows.sort((a, b) => a - b), args.days ?? 30), current));
+        return;
+    }
     if (args.command === "autopilot") {
         const sub = args.file ?? "status";
         const port = args.port ?? DEFAULT_AUTOPILOT_PORT;

package/dist/coldresume.d.ts

@@ -41,6 +41,12 @@ export interface ColdResume {
  * 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 one line shown to the USER in the app (hook `systemMessage`). In the
+ * first week the offer lived only inside the model's reply and was acted on
+ * 1 time in 33; a notice of its own is harder to miss.
+ */
+export declare function renderColdResumeNotice(c: ColdResume): string;
 /** The note the hook hands the model: the numbers, and one sentence to say. */
 export declare function renderColdResume(c: ColdResume): string;
 export interface ColdResumeEvent {
@@ -57,3 +63,16 @@ export interface ColdResumeEvent {
  * next one (no double counting), and the compaction request is a cost.
  */
 export declare function coldResumeEvents(path: string, idleMs?: number, minTokens?: number): ColdResumeEvent[];
+/**
+ * How often the cold-resume offer was acted on: offers (ledger events) whose
+ * session has a compaction within an hour after. `sessionPaths` maps the
+ * ledger's 12-char session id to its transcript. Only lines that mention a
+ * compact boundary are parsed, so even very large transcripts scan quickly.
+ */
+export declare function coldResumeFollowThrough(offers: {
+    ts: number;
+    sid?: string;
+}[], sessionPaths: Map<string, string>): {
+    offers: number;
+    compacted: number;
+};

package/dist/coldresume.js

@@ -104,6 +104,16 @@ function duration(ms) {
     const h = ms / 3_600_000;
     return h < 48 ? `${h.toFixed(h < 10 ? 1 : 0)} hours` : `${Math.round(h / 24)} days`;
 }
+/**
+ * The one line shown to the USER in the app (hook `systemMessage`). In the
+ * first week the offer lived only inside the model's reply and was acted on
+ * 1 time in 33; a notice of its own is harder to miss.
+ */
+export function renderColdResumeNotice(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)` : "";
+    return `context-doctor: idle ${duration(c.idleMs)}, so this message re-sent the whole ~${formatTokens(c.tokens)}-token context${money}. If you keep working here, /compact now makes each later message ~${cheaper}% cheaper.`;
+}
 /** 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));
@@ -178,3 +188,42 @@ export function coldResumeEvents(path, idleMs = COLD_IDLE_MS, minTokens = COLD_M
     }
     return events;
 }
+/** A /compact within this long of the offer counts as acting on it. */
+const FOLLOW_MS = 60 * 60_000;
+/**
+ * How often the cold-resume offer was acted on: offers (ledger events) whose
+ * session has a compaction within an hour after. `sessionPaths` maps the
+ * ledger's 12-char session id to its transcript. Only lines that mention a
+ * compact boundary are parsed, so even very large transcripts scan quickly.
+ */
+export function coldResumeFollowThrough(offers, sessionPaths) {
+    const compactsBySid = new Map();
+    let compacted = 0;
+    for (const o of offers) {
+        const path = o.sid ? sessionPaths.get(o.sid) : undefined;
+        if (!path)
+            continue;
+        let times = compactsBySid.get(o.sid);
+        if (!times) {
+            const found = [];
+            try {
+                forEachLine(path, (line) => {
+                    if (!line.includes("compact_boundary"))
+                        return;
+                    try {
+                        const e = JSON.parse(line);
+                        const at = Date.parse(e.timestamp);
+                        if (e.subtype === "compact_boundary" && Number.isFinite(at))
+                            found.push(at);
+                    }
+                    catch { /* not a full JSON row */ }
+                });
+            }
+            catch { /* unreadable transcript: no compactions known */ }
+            compactsBySid.set(o.sid, (times = found));
+        }
+        if (times.some((t) => t >= o.ts && t - o.ts <= FOLLOW_MS))
+            compacted++;
+    }
+    return { offers: offers.length, compacted };
+}

package/dist/compactwindow.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `context-doctor compact-window`: compact earlier, automatically, in every
+ * Claude Code surface, including the desktop app.
+ *
+ * Claude Code auto-compacts near the model's window. With a 1M-token window
+ * that is ~970k (measured: 31 compactions on the author's machine, median
+ * preTokens 970,119), so long sessions spend most of their life re-reading
+ * 400k-900k tokens on every message. Claude Code has a native setting for
+ * this, `autoCompactWindow` in ~/.claude/settings.json ("Auto-compact window
+ * size"): it compacts as if the window were that size. It is a settings key,
+ * not an environment variable, so the desktop app (which filters settings env
+ * it sets itself) honours it, and no proxy or hook is involved.
+ *
+ * The trade-off is real: more compactions, each replacing history with a
+ * summary. So this measures both sides on the user's own history and changes
+ * nothing until asked. The replay uses the usage every transcript records;
+ * its baseline came within 9% of the billed figure on the author's history
+ * (on the low side, so savings are, if anything, understated).
+ */
+export declare const MIN_WINDOW = 100000;
+export declare const MAX_WINDOW = 1000000;
+export interface WindowEstimate {
+    window: number;
+    baselineUsd: number;
+    withWindowUsd: number;
+    savedUsd: number;
+    savedPct: number;
+    /** Compactions there would be over the period with this window. */
+    compactions: number;
+}
+export interface CompactWindowReport {
+    days: number;
+    sessions: number;
+    /** Compactions that actually happened over the period (Claude Code's own, or /compact). */
+    actualCompactions: number;
+    estimates: WindowEstimate[];
+}
+export declare function estimateCompactWindows(windows: number[], days?: number, paths?: string[]): CompactWindowReport;
+export declare function settingsPath(home?: string): string;
+/** The autoCompactWindow Claude Code will use from user settings, if set. */
+export declare function currentCompactWindow(home?: string): number | undefined;
+/** Set (or with undefined, remove) autoCompactWindow in ~/.claude/settings.json. A .backup is kept. */
+export declare function setCompactWindow(window: number | undefined, home?: string): void;
+/** "400k" / "400000" / "0.4m" -> 400000. Undefined when unparseable. */
+export declare function parseWindow(raw: string): number | undefined;
+export declare function renderCompactWindows(r: CompactWindowReport, current?: number): string;

package/dist/compactwindow.js

@@ -0,0 +1,222 @@
+/**
+ * `context-doctor compact-window`: compact earlier, automatically, in every
+ * Claude Code surface, including the desktop app.
+ *
+ * Claude Code auto-compacts near the model's window. With a 1M-token window
+ * that is ~970k (measured: 31 compactions on the author's machine, median
+ * preTokens 970,119), so long sessions spend most of their life re-reading
+ * 400k-900k tokens on every message. Claude Code has a native setting for
+ * this, `autoCompactWindow` in ~/.claude/settings.json ("Auto-compact window
+ * size"): it compacts as if the window were that size. It is a settings key,
+ * not an environment variable, so the desktop app (which filters settings env
+ * it sets itself) honours it, and no proxy or hook is involved.
+ *
+ * The trade-off is real: more compactions, each replacing history with a
+ * summary. So this measures both sides on the user's own history and changes
+ * nothing until asked. The replay uses the usage every transcript records;
+ * its baseline came within 9% of the billed figure on the author's history
+ * (on the low side, so savings are, if anything, understated).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { forEachLine, listSessions } from "./session.js";
+import { pricingFor } from "./pricing.js";
+import { readJson, writeJsonWithBackup } from "./install.js";
+/** Claude Code compacts at about this share of the window (970k of 1M, measured). */
+const TRIGGER_SHARE = 0.97;
+/** Context right after a compaction: system prompt, tools and the summary (median 75,447, measured). */
+const AFTER_COMPACT = 75_000;
+/** Output tokens a compaction summary costs, priced at output's 5x input rate. */
+const SUMMARY_OUTPUT = 20_000;
+const OUTPUT_RATIO = 5;
+const TTL_MS = 3_600_000;
+export const MIN_WINDOW = 100_000;
+export const MAX_WINDOW = 1_000_000;
+function readRequests(path) {
+    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 prompt = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+        const at = Date.parse(e.timestamp);
+        if (prompt > 0 && Number.isFinite(at)) {
+            reqs.push({ at, prompt });
+            model ??= e.message.model;
+        }
+    });
+    return { model, reqs };
+}
+/**
+ * Replay one session twice: as it ran, and with compaction whenever the
+ * context reaches the window's trigger. Both arms are priced as the prompt
+ * cache bills (warm: 0.1x re-read + 1.25x for what is new; cold after an hour
+ * idle: 1.25x for everything); each simulated compaction also pays its own
+ * request and summary.
+ */
+function replay(reqs, window, since) {
+    let base = 0, sim = 0, extra = 0, actual = 0;
+    let removed = 0, prevActual, prevSim, prevAt;
+    for (const r of reqs) {
+        if (r === "compact") {
+            if (prevAt !== undefined && prevAt >= since)
+                actual++;
+            // A real compaction in the transcript: the simulated arm compacts there too.
+            if (prevAt !== undefined && prevAt >= since && removed === 0)
+                extra++;
+            removed = 0;
+            prevActual = prevSim = undefined;
+            continue;
+        }
+        const counted = r.at >= since;
+        const cold = prevAt === undefined || r.at - prevAt > TTL_MS;
+        const cost = (ctx, prev) => {
+            if (cold)
+                return 1.25 * ctx;
+            const fresh = prev === undefined || ctx < prev ? ctx : ctx - prev;
+            return 0.1 * (ctx - fresh) + 1.25 * fresh;
+        };
+        if (counted)
+            base += cost(r.prompt, prevActual);
+        let ctx = r.prompt - removed;
+        // The real context fell below what we had removed (a rewind with no
+        // compaction marker): the two arms are back in step.
+        if (ctx < AFTER_COMPACT && removed > 0) {
+            removed = 0;
+            ctx = r.prompt;
+        }
+        let simPrev = prevSim;
+        if (ctx >= TRIGGER_SHARE * window) {
+            if (counted) {
+                sim += 0.1 * ctx + OUTPUT_RATIO * SUMMARY_OUTPUT;
+                extra++;
+            }
+            removed = r.prompt - AFTER_COMPACT;
+            ctx = AFTER_COMPACT;
+            simPrev = undefined; // everything after a compaction is new to the cache
+        }
+        if (counted)
+            sim += cost(ctx, simPrev);
+        prevActual = r.prompt;
+        prevSim = ctx;
+        prevAt = r.at;
+    }
+    return { base, sim, extra, actual };
+}
+export function estimateCompactWindows(windows, days = 30, paths) {
+    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 acc = windows.map((w) => ({ window: w, base: 0, sim: 0, extra: 0 }));
+    let sessions = 0, actualCompactions = 0;
+    for (const p of targets) {
+        let parsed;
+        try {
+            parsed = readRequests(p);
+        }
+        catch {
+            continue;
+        }
+        const perM = pricingFor(parsed.model)?.inputPerM;
+        if (!perM || parsed.reqs.filter((r) => r !== "compact" && r.at >= since).length < 10)
+            continue;
+        sessions++;
+        actualCompactions += replay(parsed.reqs, Number.MAX_SAFE_INTEGER, since).actual;
+        for (const a of acc) {
+            const r = replay(parsed.reqs, a.window, since);
+            a.base += (r.base * perM) / 1e6;
+            a.sim += (r.sim * perM) / 1e6;
+            a.extra += r.extra;
+        }
+    }
+    return {
+        days,
+        sessions,
+        actualCompactions,
+        estimates: acc.map((a) => ({
+            window: a.window,
+            baselineUsd: a.base,
+            withWindowUsd: a.sim,
+            savedUsd: a.base - a.sim,
+            savedPct: a.base > 0 ? (a.base - a.sim) / a.base : 0,
+            compactions: a.extra,
+        })),
+    };
+}
+export function settingsPath(home = homedir()) {
+    return join(home, ".claude", "settings.json");
+}
+/** The autoCompactWindow Claude Code will use from user settings, if set. */
+export function currentCompactWindow(home = homedir()) {
+    const p = settingsPath(home);
+    if (!existsSync(p))
+        return undefined;
+    try {
+        const v = JSON.parse(readFileSync(p, "utf8"))?.autoCompactWindow;
+        return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Set (or with undefined, remove) autoCompactWindow in ~/.claude/settings.json. A .backup is kept. */
+export function setCompactWindow(window, home = homedir()) {
+    if (window !== undefined && (!Number.isInteger(window) || window < MIN_WINDOW || window > MAX_WINDOW)) {
+        throw new Error(`window must be a whole number of tokens between ${MIN_WINDOW} and ${MAX_WINDOW}`);
+    }
+    const p = settingsPath(home);
+    const settings = readJson(p);
+    if (window === undefined)
+        delete settings.autoCompactWindow;
+    else
+        settings.autoCompactWindow = window;
+    writeJsonWithBackup(p, settings);
+}
+/** "400k" / "400000" / "0.4m" -> 400000. Undefined when unparseable. */
+export function parseWindow(raw) {
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([km]?)\s*$/i.exec(raw);
+    if (!m)
+        return undefined;
+    const n = Number(m[1]) * (m[2].toLowerCase() === "m" ? 1e6 : m[2].toLowerCase() === "k" ? 1e3 : 1);
+    return Math.round(n);
+}
+const usd = (n) => (Math.abs(n) >= 100 ? `$${Math.round(n).toLocaleString("en-US")}` : `$${n.toFixed(2)}`);
+const k = (n) => `${Math.round(n / 1000)}k`;
+export function renderCompactWindows(r, current) {
+    const lines = [];
+    lines.push("Auto-compact window: compact earlier, automatically (Claude Code's own setting)");
+    lines.push(`Your last ${r.days} days, ${r.sessions} Claude Code session${r.sessions === 1 ? "" : "s"}, priced at list prices`);
+    lines.push("─".repeat(66));
+    lines.push(`Now: ${current ? `${k(current)} (set in ~/.claude/settings.json)` : "not set: Claude Code compacts near the model's full window"}`);
+    if (r.sessions === 0) {
+        lines.push("No sessions with 10+ requests in the window to replay.");
+        return lines.join("\n");
+    }
+    lines.push("");
+    lines.push("  window   input cost   saved            compactions");
+    for (const e of r.estimates) {
+        const mark = current === e.window ? "  ← current" : "";
+        lines.push(`  ${k(e.window).padStart(6)}   ${usd(e.withWindowUsd).padStart(10)}   ${(usd(e.savedUsd) + ` (${Math.round(e.savedPct * 100)}%)`).padEnd(16)} ${String(e.compactions).padStart(4)} (${((e.compactions / r.days) * 7).toFixed(1)}/week)${mark}`);
+    }
+    lines.push(`  as now   ${usd(r.estimates[0]?.baselineUsd ?? 0).padStart(10)}                    ${String(r.actualCompactions).padStart(4)} (${((r.actualCompactions / r.days) * 7).toFixed(1)}/week)`);
+    lines.push("");
+    lines.push("Each compaction replaces the session's history with a summary, so a smaller");
+    lines.push("window trades detail for cost. Set one with:  context-doctor compact-window 400k");
+    lines.push("Undo with:  context-doctor compact-window off");
+    return lines.join("\n");
+}

package/dist/dashboard.d.ts

@@ -9,12 +9,14 @@
 import http from "node:http";
 export interface DashboardData {
     generatedAt: string;
+    /** tokensSaved: removed by context-doctor itself. shrinkage: sessions that got smaller after a warning (mostly compaction), shown apart. */
     totals: {
         tokensSaved: number;
         usdSaved: number;
         checks: number;
         warnings: number;
         optimizeRuns: number;
+        shrinkage: number;
     };
     daily: Array<{
         date: string;

package/dist/dashboard.js

@@ -37,7 +37,8 @@ export async function collectDashboardData(proxyPort = 8787) {
     // real reduction, so it counts alongside explicit optimize runs.
     const perSession = new Map();
     for (const c of checks) {
-        if (!c.sid || typeof c.tok !== "number")
+        // "mcp-sketch" was a shared id for unrelated chats (fixed in 0.24); never a session.
+        if (!c.sid || c.sid === "mcp-sketch" || typeof c.tok !== "number")
             continue;
         perSession.set(c.sid, [...(perSession.get(c.sid) ?? []), c.tok]);
     }
@@ -94,7 +95,10 @@ export async function collectDashboardData(proxyPort = 8787) {
     return {
         generatedAt: new Date().toISOString(),
         totals: {
-            tokensSaved: optimizeSaved + shrinkage + (proxy?.tokensSaved ?? 0),
+            // What context-doctor removed itself; compaction shrinkage is reported
+            // separately (it was counted here until 0.24, which overclaimed).
+            tokensSaved: optimizeSaved + (proxy?.tokensSaved ?? 0),
+            shrinkage,
             usdSaved: usdSaved + (proxy?.estUsdSaved ?? 0),
             checks: checks.length + carried.checks,
             warnings: checks.filter((c) => c.warn).length + carried.warnings,

package/dist/doctor.js

@@ -237,7 +237,7 @@ export async function runDoctor() {
             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" }
+                ? { 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; for desktop ones, see `context-doctor compact-window`" }
                 : 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" });

package/dist/hook.js

@@ -20,7 +20,7 @@ import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
 import { formatTokens, CHARS_PER_TOKEN } from "./tokens.js";
 import { ensureProxyUp } from "./autopilot.js";
-import { detectColdResume, renderColdResume } from "./coldresume.js";
+import { detectColdResume, renderColdResume, renderColdResumeNotice } 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. */
@@ -165,17 +165,25 @@ export async function runHook() {
         // 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 = [];
+        let notice;
         const cold = detectColdResume(transcriptPath);
         let cr = prev.cr;
         if (cold && cold.lastReplyAt !== prev.cr) {
             notes.push(renderColdResume(cold));
+            notice = renderColdResumeNotice(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)
+            if (lines.length === 0 && !notice)
                 return;
-            console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: `<context-doctor>\n${lines.join("\n")}\n</context-doctor>` } }));
+            const out = {};
+            // systemMessage is shown to the user in the app; additionalContext goes to the model.
+            if (notice)
+                out.systemMessage = notice;
+            if (lines.length > 0)
+                out.hookSpecificOutput = { hookEventName: "UserPromptSubmit", additionalContext: `<context-doctor>\n${lines.join("\n")}\n</context-doctor>` };
+            console.log(JSON.stringify(out));
         };
         if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR) {
             if (cr !== prev.cr)

package/dist/impact.js

@@ -14,6 +14,7 @@ import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
+import { coldResumeFollowThrough } from "./coldresume.js";
 /** Sessions larger than this are skipped in the report (keeps it snappy). */
 const MAX_SESSION_BYTES = 30 * 1024 * 1024;
 async function fetchProxyStats(port) {
@@ -41,7 +42,8 @@ export async function buildImpactReport(proxyPort = 8787) {
     // checks (compaction/cleanup after a warning), that drop is measured fact.
     const bySession = new Map();
     for (const c of checks) {
-        if (!c.sid || typeof c.tok !== "number")
+        // "mcp-sketch" was a shared id for unrelated chats (fixed in 0.24); never a session.
+        if (!c.sid || c.sid === "mcp-sketch" || typeof c.tok !== "number")
             continue;
         const s = bySession.get(c.sid) ?? { toks: [], warns: 0 };
         s.toks.push(c.tok);
@@ -77,7 +79,10 @@ export async function buildImpactReport(proxyPort = 8787) {
     const proxyHistoric = proxyEvents.reduce((s, e) => s + (e.saved ?? 0), 0) + carried.proxySaved;
     const proxySaved = proxyHistoric + (proxy?.tokensSaved ?? 0);
     // -- Headline: what context-doctor has saved ----------------------------------
-    const totalSaved = proxySaved + optimizeSaved + totalReduction;
+    // Only what context-doctor itself removed. Sessions also shrink when Claude
+    // Code auto-compacts or the user runs /compact; counting that as our saving
+    // overclaimed (until 0.24 it was in this total), so it is shown apart.
+    const totalSaved = proxySaved + optimizeSaved;
     lines.push("Tokens context-doctor saved (measured)");
     lines.push("─".repeat(56));
     lines.push(`TOTAL: ~${formatTokens(totalSaved)} tokens`);
@@ -97,7 +102,10 @@ export async function buildImpactReport(proxyPort = 8787) {
     lines.push(`  · optimizations applied via CLI/chat tools (exact): ${formatTokens(optimizeSaved)} over ${optimizes.length} run(s)` +
         (familyNote ? ` [${familyNote}]` : "") +
         (optimizeUsd > 0 ? ` ≈ ${formatUsd(optimizeUsd)}` : ""));
-    lines.push(`  · observed session shrinkage after hygiene warnings: ${formatTokens(totalReduction)}`);
+    lines.push("");
+    lines.push(`Sessions that got smaller after a hygiene warning: ${formatTokens(totalReduction)} tokens`);
+    lines.push("  (mostly compaction, by you or Claude Code; not counted above, because a warning");
+    lines.push("  may or may not be why it happened)");
     lines.push("");
     // -- Hook activity ------------------------------------------------------------
     lines.push("Hygiene activity (every-prompt hook)");
@@ -110,6 +118,18 @@ export async function buildImpactReport(proxyPort = 8787) {
     else {
         lines.push("No hook activity recorded yet (ledger appears after the first deep check of a heavy session).");
     }
+    const offers = ledger.filter((e) => e.ev === "cold_resume");
+    if (offers.length > 0) {
+        const paths = new Map();
+        for (const s of listSessions(10_000))
+            paths.set((s.path.split(/[\\/]/).pop() ?? "").slice(0, 12), s.path);
+        const f = coldResumeFollowThrough(offers, paths);
+        lines.push(`/compact offered on ${f.offers} return(s) to a large session after the cache expired;`);
+        lines.push(`a compaction (yours or Claude Code's) followed within the hour on ${f.compacted}.`);
+        if (f.offers >= 5 && f.compacted / f.offers < 0.2) {
+            lines.push("Rarely acted on? `context-doctor compact-window` makes Claude Code compact earlier by itself.");
+        }
+    }
     lines.push("");
     // -- Measured-now: recent session profiles ------------------------------------
     lines.push("Your recent sessions — live context and waste still recoverable");
@@ -137,7 +157,7 @@ export async function buildImpactReport(proxyPort = 8787) {
                     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);
+                const sid = (s.path.split(/[\\/]/).pop() ?? "").slice(0, 12);
                 const saved = reductionBySession.get(sid) ?? 0;
                 const warns = bySession.get(sid)?.warns ?? 0;
                 lines.push(`  ${(parsed.title ?? s.path.split("/").pop() ?? "session").slice(0, 40).padEnd(42)} ` +

package/dist/index.d.ts

@@ -25,3 +25,4 @@ export * from "./autoclear.js";
 export * from "./autopilot.js";
 export * from "./savings.js";
 export * from "./coldresume.js";
+export * from "./compactwindow.js";

package/dist/index.js

@@ -20,3 +20,4 @@ export * from "./autoclear.js";
 export * from "./autopilot.js";
 export * from "./savings.js";
 export * from "./coldresume.js";
+export * from "./compactwindow.js";

package/dist/mcp.js

@@ -49,23 +49,23 @@ 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.23.1" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.25.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({
-            turns: z.number().int().nonnegative().describe("User+assistant exchanges so far"),
+            turns: z.number().int().nonnegative().max(100_000).describe("User+assistant exchanges so far"),
             model: z.string().optional().describe("Model this chat runs as, e.g. claude-sonnet-5, gpt-5"),
             blocks: z.array(z.object({
-                turn: z.number().int().positive().describe("1-based turn the block sits in"),
+                turn: z.number().int().positive().max(100_000).describe("1-based turn the block sits in"),
                 kind: z.enum(["paste", "code", "tool_result", "image", "base64", "text"]),
                 label: z.string().describe("Short name you can refer to later, e.g. 'the nginx config'"),
-                approx_tokens: z.number().positive().optional(),
-                approx_lines: z.number().positive().optional(),
-                approx_words: z.number().positive().optional(),
-                approx_chars: z.number().positive().optional(),
-                repeated: z.number().int().positive().optional().describe("Times this same content appears (2+ = duplicate)"),
+                approx_tokens: z.number().positive().max(10_000_000).optional(),
+                approx_lines: z.number().positive().max(1_000_000).optional(),
+                approx_words: z.number().positive().max(5_000_000).optional(),
+                approx_chars: z.number().positive().max(40_000_000).optional(),
+                repeated: z.number().int().positive().max(1000).optional().describe("Times this same content appears (2+ = duplicate)"),
                 stale: z.boolean().optional().describe("Already acted on; nothing in it is still needed"),
-            })).describe("Only the blocks over ~500 tokens, repeated, or images. Plain turns need not be listed."),
+            })).max(500).describe("Only the blocks over ~500 tokens, repeated, or images. Plain turns need not be listed."),
         }).optional().describe("Coarse description of the conversation for chat apps. One size hint per block: lines for code, words for prose, chars (or tokens) for logs and tool output, which vary most per line."),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),
     }, async ({ conversation, sketch, model }) => {
@@ -85,7 +85,7 @@ function createServer() {
         conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array)"),
         strategies: z.array(z.enum(STRATEGY_IDS)).optional()
             .describe("Strategies to apply. Default: dedupe, trim-tool-results, strip-base64. Add trim-tool-calls to shrink big inline file writes, or prune-history for lossy compaction of old turns."),
-        keep_recent: z.number().int().positive().optional().describe("Messages at the tail to leave untouched (default 6)"),
+        keep_recent: z.number().int().nonnegative().optional().describe("Messages at the tail to leave untouched (default 6; 0 = none)"),
         max_tool_result_tokens: z.number().int().positive().optional().describe("Token budget for trimmed tool results (default 300)"),
     }, async ({ conversation, strategies, keep_recent, max_tool_result_tokens }) => {
         const result = optimizeConversation(conversation, {

package/dist/proxy.d.ts

@@ -47,13 +47,22 @@ 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.23.1";
+export declare const PROXY_VERSION = "0.25.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
  * so the token cannot be guessed a character at a time.
  */
 export declare function stripToken(url: string, token: string): string | undefined;
+/**
+ * Where a request goes. The endpoints we optimize are fixed; EVERY other path
+ * is forwarded untouched, because a client routed through the proxy (Claude
+ * Code under autopilot, an SDK) also lists models, uploads files, counts
+ * tokens. Until 0.24 those got a 404 and broke the feature for that client.
+ * Unknown paths go to Anthropic when the request says it is one (Anthropic
+ * clients always send anthropic-version, or x-api-key), else to OpenAI.
+ */
+export declare function upstreamFor(url: string, opts: ProxyOptions, headers?: http.IncomingHttpHeaders): string;
 export interface ProxyStats {
     startedAt: string;
     requests: number;

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.23.1";
+export const PROXY_VERSION = "0.25.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"]);
@@ -41,13 +41,22 @@ export function stripToken(url, token) {
     const rest = end === -1 ? "/" : url.slice(end);
     return rest;
 }
-function upstreamFor(url, opts) {
+/**
+ * Where a request goes. The endpoints we optimize are fixed; EVERY other path
+ * is forwarded untouched, because a client routed through the proxy (Claude
+ * Code under autopilot, an SDK) also lists models, uploads files, counts
+ * tokens. Until 0.24 those got a 404 and broke the feature for that client.
+ * Unknown paths go to Anthropic when the request says it is one (Anthropic
+ * clients always send anthropic-version, or x-api-key), else to OpenAI.
+ */
+export function upstreamFor(url, opts, headers = {}) {
+    const anthropic = opts.anthropicUpstream ?? "https://api.anthropic.com";
+    const openai = opts.openaiUpstream ?? "https://api.openai.com";
     if (url.startsWith("/v1/messages"))
-        return opts.anthropicUpstream ?? "https://api.anthropic.com";
-    if (url.startsWith("/v1/chat/completions") || url.startsWith("/v1/responses") || url.startsWith("/v1/embeddings")) {
-        return opts.openaiUpstream ?? "https://api.openai.com";
-    }
-    return undefined;
+        return anthropic;
+    if (url.startsWith("/v1/chat/completions") || url.startsWith("/v1/responses") || url.startsWith("/v1/embeddings"))
+        return openai;
+    return headers["anthropic-version"] !== undefined || headers["x-api-key"] !== undefined ? anthropic : openai;
 }
 /** Pull exact usage out of a response body — JSON or SSE, either provider. */
 function extractUsage(text) {
@@ -125,7 +134,7 @@ export function startProxy(opts = {}) {
                 res.end(JSON.stringify({ ...stats, estUsdSaved: Number(stats.estUsdSaved.toFixed(4)) }, null, 2));
                 return;
             }
-            const upstreamBase = upstreamFor(url, opts);
+            const upstreamBase = upstreamFor(url, opts, req.headers);
             if (!upstreamBase) {
                 res.statusCode = 404;
                 res.setHeader("content-type", "application/json");
@@ -135,7 +144,13 @@ export function startProxy(opts = {}) {
             const chunks = [];
             for await (const chunk of req)
                 chunks.push(chunk);
-            let body = Buffer.concat(chunks).toString("utf8");
+            // Keep the original bytes: only conversation JSON is ever rewritten, and
+            // anything else (a multipart file upload) must reach upstream byte for
+            // byte. Decoding everything as UTF-8 corrupted binary bodies.
+            const rawBody = Buffer.concat(chunks);
+            let body = rawBody.toString("utf8");
+            const originalBody = body;
+            const conversationPath = /^\/v1\/(messages|chat\/completions|responses)(\?|$)/.test(url);
             // Optimize the message history in flight. Anything unparseable (or with
             // no messages array, e.g. embeddings) passes through untouched.
             // count_tokens is measurement — optimizing it would silently change the
@@ -184,7 +199,7 @@ export function startProxy(opts = {}) {
                     }
                 }
             }
-            else if (req.method === "POST" && body && !isMeasurement) {
+            else if (req.method === "POST" && body && !isMeasurement && conversationPath) {
                 try {
                     // Per-route overrides: first modelPrefix match wins.
                     let effective = opts;
@@ -284,7 +299,7 @@ export function startProxy(opts = {}) {
             const upstream = await fetch(upstreamBase + url, {
                 method: req.method ?? "POST",
                 headers,
-                body: req.method === "GET" || req.method === "HEAD" ? undefined : body,
+                body: req.method === "GET" || req.method === "HEAD" ? undefined : body === originalBody ? rawBody : body,
             });
             console.error(`[context-doctor] ${req.method} ${url} → ${upstream.status} in ${Date.now() - upstreamStart}ms | ${note}` +
                 (stats.tokensSaved > 0 ? ` | session total: ${formatTokens(stats.tokensSaved)} tokens ≈ ${formatUsd(stats.estUsdSaved)} saved` : ""));

package/dist/savings.d.ts

@@ -58,7 +58,15 @@ export interface SavingsReport {
 /** 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;
+/** Optional third lever, computed by compactwindow.ts and passed in by the CLI. */
+export interface CompactWindowLine {
+    window: number;
+    savedUsd: number;
+    compactionsPerWeek: number;
+    nowPerWeek: number;
+    isCurrent: boolean;
+}
+export declare function renderSavings(r: SavingsReport, autopilotOn?: boolean, cw?: CompactWindowLine): 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.

package/dist/savings.js

@@ -199,7 +199,7 @@ export function estimateSavings(days = 30, options = {}, paths, onProgress) {
 }
 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) {
+export function renderSavings(r, autopilotOn = false, cw) {
     const lines = [];
     if (r.sessions.length === 0) {
         lines.push(`No Claude Code sessions with 10+ requests in the last ${r.days} days to replay.`);
@@ -236,6 +236,15 @@ export function renderSavings(r, autopilotOn = false) {
         if (!autopilotOn)
             lines.push("   Turn it on:  context-doctor autopilot on");
     }
+    if (cw) {
+        lines.push("");
+        lines.push(`${`3. Compact earlier (${Math.round(cw.window / 1000)}k window)`.padEnd(34)}${usd(Math.max(0, cw.savedUsd)).padStart(9)}${pct(Math.max(0, cw.savedUsd))}`);
+        lines.push(`   Claude Code's own auto-compact window${cw.isCurrent ? ", as you have it set" : ""}: automatic in every surface,`);
+        lines.push(`   ${cw.compactionsPerWeek.toFixed(1)} compactions a week instead of ${cw.nowPerWeek.toFixed(1)}. Each keeps a summary, not the`);
+        lines.push("   full history. Compare sizes: context-doctor compact-window");
+        if (!cw.isCurrent)
+            lines.push(`   Set it with: context-doctor compact-window ${Math.round(cw.window / 1000)}k`);
+    }
     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");

package/dist/session.js

@@ -274,6 +274,14 @@ function fromCodexLine(entry) {
             return null;
     }
 }
+/** Message content as a block array (a plain string becomes one text block). */
+function asBlocks(content) {
+    if (Array.isArray(content))
+        return content;
+    if (typeof content === "string")
+        return content ? [{ type: "text", text: content }] : [];
+    return content == null ? [] : [content];
+}
 export function parseSessionFile(path) {
     // ChatGPT exports are one big JSON array, not JSONL — and small enough to
     // read whole. Only peek first, so multi-hundred-MB JSONL is never slurped.
@@ -293,6 +301,12 @@ export function parseSessionFile(path) {
     let model;
     /** Index in `messages` of the newest compaction summary, or -1. */
     let lastCompactIndex = -1;
+    let lastReplyId;
+    /** Where each API reply (by message id) lives in `messages`. */
+    const replyIndex = new Map();
+    let lastSampledReplyId;
+    // A compaction summary marks where the live context starts; never merge into it.
+    const prevIndexAllowsMerge = (i) => i !== lastCompactIndex;
     /** Newest API-reported input size, if the transcript carries usage. */
     let reportedInputTokens;
     /** Every reported size, positioned — the basis for `context-doctor accuracy`. */
@@ -366,7 +380,16 @@ export function parseSessionFile(path) {
                 usageNumber(usage.cache_creation_input_tokens);
             if (total > 0) {
                 reportedInputTokens = total;
-                usageSamples.push({ index: messages.length, input: total });
+                // One sample per API reply: Claude Code writes a reply as several
+                // rows (one per content block) carrying the same usage. The request's
+                // input is everything before the reply's first row.
+                const replyId = typeof message.id === "string" ? message.id : undefined;
+                if (!replyId || replyId !== lastSampledReplyId) {
+                    const prevMsg = messages[messages.length - 1];
+                    const startsNew = !(prevMsg?.role === "assistant" && replyId !== undefined && replyId === lastReplyId);
+                    usageSamples.push({ index: startsNew ? messages.length : messages.length - 1, input: total });
+                    lastSampledReplyId = replyId;
+                }
             }
         }
         if (entry.isCompactSummary)
@@ -389,7 +412,34 @@ export function parseSessionFile(path) {
                 }
             }
         }
-        messages.push({ role: message.role, content: message.content });
+        // Rebuild messages the way the API saw them. Claude Code writes one row
+        // per content block, so one reply (text + two tool calls) arrived as three
+        // "assistant" messages and its results as two "user" ones: exported
+        // conversations broke tool_use/tool_result pairing, and every split added
+        // per-message overhead to the profile. The API treats consecutive
+        // same-role messages as one; so do we.
+        // Parallel tool calls are written as they stream: a reply's later
+        // tool_use rows can land after the first tool_result rows. A row that
+        // belongs to an earlier reply (same message id) joins that reply.
+        const replyId = entry.type === "assistant" && typeof message.id === "string" ? message.id : undefined;
+        const home = replyId !== undefined ? replyIndex.get(replyId) : undefined;
+        if (home !== undefined && home > lastCompactIndex && home < messages.length - 1) {
+            messages[home].content = [...asBlocks(messages[home].content), ...asBlocks(message.content)];
+            return;
+        }
+        const prev = messages[messages.length - 1];
+        if (entry.type === "assistant")
+            lastReplyId = replyId;
+        if (prev && prev.role === message.role && !entry.isCompactSummary && prevIndexAllowsMerge(messages.length - 1)) {
+            prev.content = [...asBlocks(prev.content), ...asBlocks(message.content)];
+            if (replyId !== undefined)
+                replyIndex.set(replyId, messages.length - 1);
+        }
+        else {
+            messages.push({ role: message.role, content: message.content });
+            if (replyId !== undefined)
+                replyIndex.set(replyId, messages.length - 1);
+        }
     });
     const toolTimings = [...latenciesByTool.entries()]
         .map(([tool, ms]) => {

package/dist/sketch.js

@@ -186,6 +186,8 @@ export function renderSketchProfile(p) {
 /** Profile a sketch, log it to the ledger like a hook check, and render. */
 export function runSketch(sketch) {
     const profile = profileSketch(sketch);
-    recordLedger({ ev: "check", sid: "mcp-sketch", src: "mcp", tok: profile.totalTokens, warn: profile.findings.some((f) => f.severity !== "info"), model: sketch.model });
+    // No session id: each sketch describes a different chat, and a shared id made
+    // the dashboard read "big sketch, then a smaller one" as tokens saved.
+    recordLedger({ ev: "check", src: "mcp", tok: profile.totalTokens, warn: profile.findings.some((f) => f.severity !== "info"), model: sketch.model });
     return renderSketchProfile(profile);
 }

package/dist/tokens.js

@@ -102,6 +102,8 @@ export function formatTokens(n) {
     // rather than something false.
     if (!Number.isFinite(n))
         return "0";
+    if (n >= 1_000_000_000)
+        return `${(n / 1_000_000_000).toFixed(1)}B`;
     if (n >= 1_000_000)
         return `${(n / 1_000_000).toFixed(1)}M`;
     if (n >= 10_000)

package/dist/watch.js

@@ -7,7 +7,7 @@
  * Polling (not fs.watch) is deliberate: editors/agents rewrite files in ways
  * that break watchers cross-platform, and a 2s stat is effectively free.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { listSessions, parseSessionFile } from "./session.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
@@ -31,10 +31,24 @@ export function runWatch(opts) {
             if (size === lastSize)
                 return; // nothing new — cost of this tick was one stat
             lastSize = size;
+            // A session transcript (Claude Code, Codex, ChatGPT export), or else a
+            // plain conversation file (OpenAI/Anthropic messages JSON), which is how
+            // most agent frameworks dump a trace. Until 0.24 the second kind was
+            // read as an empty session and watch printed nothing.
             const parsed = parseSessionFile(file);
-            if (parsed.messageCount === 0)
-                return;
-            const profile = profileConversation(parseConversation(parsed.conversationJson), opts.model ?? parsed.model);
+            let conversation;
+            let model = opts.model;
+            if (parsed.messageCount > 0) {
+                conversation = parseConversation(parsed.conversationJson);
+                model ??= parsed.model;
+            }
+            else {
+                conversation = parseConversation(readFileSync(file, "utf8"));
+                if (conversation.parseWarning || conversation.messages.length === 0)
+                    return;
+                model ??= conversation.model;
+            }
+            const profile = profileConversation(conversation, model);
             const delta = profile.totalTokens - lastTokens;
             lastTokens = profile.totalTokens;
             const cost = profile.cost ? ` · ${formatUsd(profile.cost.perCallUsd)}/msg` : "";

package/package.json

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