context-doctor 0.24.0 → 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,6 +116,7 @@ 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.
@@ -170,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] [--share [--copy]]` | What your recent Claude Code sessions cost, and what `/compact` at cold resumes and autopilot 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 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 |
@@ -182,7 +197,7 @@ 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 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 |
@@ -241,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.
 

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/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) {
@@ -117,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");
@@ -144,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,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.24.0" }, { 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({

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.24.0";
+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

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.24.0";
+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"]);

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/package.json

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