context-doctor 0.30.0 → 0.31.0

package/README.md

@@ -45,6 +45,7 @@ Pick where you work. Each takes about a minute and is fully reversible.
 - `ci` and the GitHub Action: review memory-file growth like any other cost.
 
 **Remove waste automatically**
+- A compaction hook (`PreCompact`) tells each Claude Code compaction what the session cannot lose (files changed, open tasks, your instructions, failing tests), so compacting saves tokens without losing the thread. `context-doctor compactions` measures, on your own history, whether sessions work worse after compacting.
 - An every-prompt hook (Claude Code, Codex, Gemini CLI; Cursor after each tool call) tells the model its real context size and the largest waste, and offers `/compact` when you return to a big session after the cache expired.
 - `compact-window`: sets Claude Code's own auto-compact window, measured on your history first. Works in the desktop app too.
 - Autopilot: a local proxy (or SDK wrapper) that clears stale tool output only when the prompt cache is cold, so a request never costs more.
@@ -179,6 +180,7 @@ MCP servers are part of the same overhead: each one's tool definitions ride on e
 
 ## What's new
 
+- **0.31 Save tokens without losing quality**: a PreCompact hook makes every Claude Code compaction keep the session's changed files, open tasks, your instructions and still-failing tests; `context-doctor compactions` measures re-reads, tool errors and corrections before and after each compaction on your history; `compact-window` now charges the re-reads to every compaction it simulates.
 - **0.30 Where the money goes, and a self-healing service**: `context-doctor subagents` compares each subagent's bill with the same work done in the parent session; `cache-plan` places Anthropic `cache_control` breakpoints in an API request and prices them. Fixes from a local audit: the autopilot service now restarts itself onto a newly installed version, `doctor` no longer writes fake hook checks into the activity ledger, and `<synthetic>` placeholder messages no longer hide a session's model.
 - **0.29 Python, and where the work goes**: a dependency-free Python package (`python/`) with `pack_documents` for LangChain and LlamaIndex results, `pack_context`, `estimate_tokens` and `profile_messages`, held byte for byte to the TypeScript by parity tests. `context-doctor reads` shows the files read into session after session; `context-doctor tasks` shows cost per commit per project, from your own transcripts.
 - **0.28 Wider reach**: `/context-doctor:overhead` and `/context-doctor:pack` in the Claude Code plugin; `pack` reads a folder inside a git repository the way git does, so `.gitignore`'d build output and secrets stay out; `withContextDoctor` wraps Google's `@google/genai` client too; `overhead` measures the fixed start-of-session cost of Codex and Gemini CLI sessions as well as Claude Code's, priced with each provider's cache rules.

package/dist/cli.js

@@ -49,6 +49,7 @@ import { renderReads, repeatedReads } from "./reads.js";
 import { costPerTask, renderTasks } from "./tasks.js";
 import { planCache, renderCachePlan } from "./cacheplan.js";
 import { renderPayback, subagentPayback } from "./subagentpay.js";
+import { compactionQuality, renderCompactionQuality } from "./compactquality.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -109,6 +110,8 @@ Usage:
   context-doctor cache-plan <request.json> [--calls n] [--out file]
                                                 Where an Anthropic request should carry cache_control,
                                                 what it saves over n calls; --out writes it applied
+  context-doctor compactions [--days n]         Do sessions work worse right after compacting? Re-reads,
+                                                tool errors and your corrections, before vs after
   context-doctor subagents [--days n]           Which subagents paid for themselves: their bill vs
                                                 what carrying their reads would have cost the parent
   context-doctor tasks [--days n]               Cost per commit, per project: session cost at list
@@ -607,7 +610,7 @@ async function main() {
         if (progress)
             process.stderr.write("\r\x1b[K");
         const setWindow = currentCompactWindow();
-        const cwReport = estimateCompactWindows([setWindow ?? 400_000], args.days ?? 30);
+        const cwReport = estimateCompactWindows([setWindow ?? 400_000], args.days ?? 30, undefined, compactionQuality(60).extraRereadTokensPerCompaction);
         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 }
@@ -662,7 +665,8 @@ async function main() {
         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));
+        const reread = compactionQuality(60).extraRereadTokensPerCompaction;
+        console.log(renderCompactWindows(estimateCompactWindows(windows.sort((a, b) => a - b), args.days ?? 30, undefined, reread), current));
         return;
     }
     if (args.command === "autopilot") {
@@ -727,6 +731,12 @@ async function main() {
         });
         return; // server keeps the process alive
     }
+    if (args.command === "compactions") {
+        const days = args.days ?? 60;
+        const q = compactionQuality(days);
+        console.log(args.json ? JSON.stringify(q, null, 2) : renderCompactionQuality(q, days));
+        return;
+    }
     if (args.command === "subagents") {
         const report = subagentPayback(args.days ?? 30);
         console.log(args.json ? JSON.stringify(report, null, 2) : renderPayback(report, args.limit ?? 8));

package/dist/compactquality.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `context-doctor compactions`: does a session work worse right after it
+ * compacts? Measured on the user's own history, so the decision to compact
+ * earlier (compact-window) rests on evidence about quality, not only cost.
+ *
+ * For every compaction in recent Claude Code transcripts, the requests just
+ * before it are compared with the same number just after, on three signals a
+ * transcript records:
+ *  - re-reads: Read of a file the session had already read before the
+ *    compaction (the summary lost it, so the model goes back for it);
+ *  - tool errors: tool results marked as errors, per tool call;
+ *  - corrections: user messages that push back ("no", "wrong", "revert",
+ *    "you forgot", "I said"), per user message.
+ * A compaction that costs quality shows up as all three rising after it.
+ * Compactions shaped by context-doctor's PreCompact hook are reported apart,
+ * so its effect can be seen as it accumulates.
+ */
+interface Signals {
+    requests: number;
+    rereads: number;
+    /** Tokens of the re-reads: what forgetting a file costs to fetch again. */
+    rereadTokens: number;
+    reads: number;
+    calls: number;
+    errors: number;
+    userMsgs: number;
+    corrections: number;
+}
+export interface CompactionQuality {
+    compactions: number;
+    /** Tokens re-read after a compaction beyond the before-window rate, per compaction. */
+    extraRereadTokensPerCompaction: number;
+    sessions: number;
+    before: Signals;
+    after: Signals;
+    /** The same, for compactions context-doctor's PreCompact hook shaped. */
+    shaped?: {
+        compactions: number;
+        before: Signals;
+        after: Signals;
+    };
+}
+export declare function compactionQuality(days?: number, paths?: string[]): CompactionQuality;
+export declare function renderCompactionQuality(q: CompactionQuality, days?: number): string;
+export {};

package/dist/compactquality.js

@@ -0,0 +1,176 @@
+/**
+ * `context-doctor compactions`: does a session work worse right after it
+ * compacts? Measured on the user's own history, so the decision to compact
+ * earlier (compact-window) rests on evidence about quality, not only cost.
+ *
+ * For every compaction in recent Claude Code transcripts, the requests just
+ * before it are compared with the same number just after, on three signals a
+ * transcript records:
+ *  - re-reads: Read of a file the session had already read before the
+ *    compaction (the summary lost it, so the model goes back for it);
+ *  - tool errors: tool results marked as errors, per tool call;
+ *  - corrections: user messages that push back ("no", "wrong", "revert",
+ *    "you forgot", "I said"), per user message.
+ * A compaction that costs quality shows up as all three rising after it.
+ * Compactions shaped by context-doctor's PreCompact hook are reported apart,
+ * so its effect can be seen as it accumulates.
+ */
+import { forEachLine, listSessions } from "./session.js";
+import { readLedger } from "./ledger.js";
+import { estimateTokens, formatTokens } from "./tokens.js";
+const WINDOW = 15;
+const CORRECTION = /^(no\b|nope\b|wrong\b|that'?s (not|wrong)|not what i|you forgot|i (said|told you|asked)|revert\b|undo\b|stop\b|again\??$|why did you)/i;
+const empty = () => ({ requests: 0, rereads: 0, rereadTokens: 0, reads: 0, calls: 0, errors: 0, userMsgs: 0, corrections: 0 });
+function add(s, reqs, readBefore) {
+    for (const r of reqs) {
+        s.requests++;
+        s.calls += r.calls;
+        s.errors += r.errors;
+        s.userMsgs += r.userMsgs;
+        s.corrections += r.corrections;
+        r.reads.forEach((p, i) => {
+            s.reads++;
+            if (readBefore.has(p)) {
+                s.rereads++;
+                s.rereadTokens += r.readTokens[i] ?? 0;
+            }
+        });
+    }
+}
+export function compactionQuality(days = 60, paths) {
+    const since = Date.now() - days * 86_400_000;
+    const files = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
+    const shapedAt = readLedger().filter((e) => e.ev === "precompact").map((e) => e.ts);
+    const q = { compactions: 0, extraRereadTokensPerCompaction: 0, sessions: 0, before: empty(), after: empty() };
+    const shaped = { compactions: 0, before: empty(), after: empty() };
+    for (const path of files) {
+        const reqs = [];
+        const boundaries = [];
+        let cur;
+        // User messages between a compaction and the next request belong to the "after" side.
+        let pendingUser = 0, pendingCorrections = 0;
+        const readIds = new Map();
+        let lastId;
+        forEachLine(path, (line) => {
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!e || e.isSidechain)
+                return;
+            const at = Date.parse(e.timestamp);
+            if (e.type === "system" && e.subtype === "compact_boundary") {
+                boundaries.push({ index: reqs.length, at: Number.isFinite(at) ? at : 0 });
+                cur = undefined;
+                return;
+            }
+            const c = e.message?.content;
+            if (e.type === "assistant") {
+                if (e.message?.id !== lastId && e.message?.usage) {
+                    lastId = e.message.id;
+                    cur = { at, reads: [], readTokens: [], calls: 0, errors: 0, userMsgs: pendingUser, corrections: pendingCorrections };
+                    pendingUser = pendingCorrections = 0;
+                    reqs.push(cur);
+                }
+                if (cur && Array.isArray(c)) {
+                    for (const b of c) {
+                        if (b?.type !== "tool_use")
+                            continue;
+                        cur.calls++;
+                        if (b.name === "Read" && typeof b.input?.file_path === "string")
+                            readIds.set(b.id, b.input.file_path);
+                    }
+                }
+            }
+            else if (e.type === "user") {
+                if (typeof c === "string" && !e.isMeta && !e.isCompactSummary) {
+                    const corr = CORRECTION.test(c.trim()) ? 1 : 0;
+                    if (cur) {
+                        cur.userMsgs++;
+                        cur.corrections += corr;
+                    }
+                    else {
+                        pendingUser++;
+                        pendingCorrections += corr;
+                    }
+                }
+                else if (cur && Array.isArray(c)) {
+                    for (const b of c) {
+                        if (b?.type !== "tool_result")
+                            continue;
+                        if (b.is_error)
+                            cur.errors++;
+                        const p = readIds.get(b.tool_use_id);
+                        if (p && !b.is_error) {
+                            cur.reads.push(p);
+                            const text = typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? "");
+                            cur.readTokens.push(estimateTokens(text, "claude-opus-5"));
+                        }
+                    }
+                }
+            }
+        });
+        let counted = false;
+        for (const b of boundaries) {
+            const before = reqs.slice(Math.max(0, b.index - WINDOW), b.index);
+            const after = reqs.slice(b.index, b.index + WINDOW);
+            if (before.length < 5 || after.length < 5)
+                continue;
+            // Files read before the compaction: re-reading them afterwards means the summary lost them.
+            const readBefore = new Set(reqs.slice(0, b.index).flatMap((r) => r.reads));
+            // Before the compaction, a "re-read" is a read of a file already read earlier in that stretch.
+            const earlier = new Set(reqs.slice(0, Math.max(0, b.index - WINDOW)).flatMap((r) => r.reads));
+            add(q.before, before, earlier);
+            add(q.after, after, readBefore);
+            q.compactions++;
+            counted = true;
+            if (shapedAt.some((t) => Math.abs(t - b.at) < 10 * 60_000)) {
+                shaped.compactions++;
+                add(shaped.before, before, earlier);
+                add(shaped.after, after, readBefore);
+            }
+        }
+        if (counted)
+            q.sessions++;
+    }
+    if (shaped.compactions)
+        q.shaped = shaped;
+    // Only the rise counts against compacting: some re-reading happens anyway.
+    const baseline = q.before.reads ? q.before.rereadTokens / Math.max(1, q.before.rereads) * (q.before.rereads / q.before.reads) * q.after.reads : 0;
+    q.extraRereadTokensPerCompaction = q.compactions ? Math.max(0, q.after.rereadTokens - baseline) / q.compactions : 0;
+    return q;
+}
+function rates(s) {
+    return {
+        reread: s.reads ? s.rereads / s.reads : 0,
+        error: s.calls ? s.errors / s.calls : 0,
+        correction: s.userMsgs ? s.corrections / s.userMsgs : 0,
+    };
+}
+export function renderCompactionQuality(q, days = 60) {
+    const out = ["DO SESSIONS WORK WORSE AFTER COMPACTING?", "═".repeat(56)];
+    if (!q.compactions)
+        return [...out, `No compactions with enough work on both sides in the last ${days} days.`].join("\n");
+    const b = rates(q.before), a = rates(q.after);
+    const pct = (x) => `${(x * 100).toFixed(1)}%`;
+    const row = (label, x, y) => `  ${label.padEnd(36)} ${pct(x).padStart(7)}  ${pct(y).padStart(7)}   ${y - x > 0.0005 ? "+" : y - x < -0.0005 ? "−" : " "}${pct(Math.abs(y - x))}`;
+    const thin = q.before.reads + q.after.reads < 50;
+    out.push(`${q.compactions} compactions in ${q.sessions} sessions, last ${days} days; ${WINDOW} requests before vs after each.`, `Sample: ${q.before.reads} file reads before, ${q.after.reads} after; ${q.before.calls} and ${q.after.calls} tool calls; ${q.before.userMsgs} and ${q.after.userMsgs} of your messages.${thin ? " Few reads: the re-read figure is a weak signal." : ""}`, "", `  ${"".padEnd(36)} ${"before".padStart(7)}  ${"after".padStart(7)}   change`, row("files re-read (forgotten)", b.reread, a.reread), row("tool calls that errored", b.error, a.error), row("your messages correcting course", b.correction, a.correction));
+    if (q.shaped) {
+        const sb = rates(q.shaped.before), sa = rates(q.shaped.after);
+        out.push("", `Shaped by context-doctor's PreCompact hook (${q.shaped.compactions}): re-reads ${pct(sb.reread)} → ${pct(sa.reread)}, errors ${pct(sb.error)} → ${pct(sa.error)}, corrections ${pct(sb.correction)} → ${pct(sa.correction)}.`);
+    }
+    const forgets = a.reread - b.reread > 0.05;
+    const worse = a.error - b.error > 0.03 || a.correction - b.correction > 0.05;
+    out.push("");
+    if (forgets) {
+        out.push(`Compacting forgets files: each compaction is followed by ~${formatTokens(q.extraRereadTokensPerCompaction)} tokens of extra re-reads. compact-window charges that to every compaction it simulates.`);
+    }
+    out.push(worse
+        ? "Sessions also work worse after compacting (more tool errors or corrections): compact less often, and let the PreCompact hook tell each summary what to keep."
+        : "No sign of worse work after compacting: tool errors and corrections are no higher. The cost of compacting here is tokens, not quality.");
+    return out.join("\n");
+}

package/dist/compactwindow.d.ts

@@ -34,8 +34,10 @@ export interface CompactWindowReport {
     /** Compactions that actually happened over the period (Claude Code's own, or /compact). */
     actualCompactions: number;
     estimates: WindowEstimate[];
+    /** Re-read tokens charged to each simulated compaction (0 when not measured). */
+    rereadTokens?: number;
 }
-export declare function estimateCompactWindows(windows: number[], days?: number, paths?: string[]): CompactWindowReport;
+export declare function estimateCompactWindows(windows: number[], days?: number, paths?: string[], rereadTokens?: number): 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;

package/dist/compactwindow.js

@@ -70,7 +70,12 @@ function readRequests(path) {
  * idle: 1.25x for everything); each simulated compaction also pays its own
  * request and summary.
  */
-function replay(reqs, window, since) {
+/**
+ * `reread`: tokens a session fetches again after a compaction because the
+ * summary dropped them (measured by `context-doctor compactions`). Each
+ * simulated compaction writes them to the cache and carries them onward.
+ */
+function replay(reqs, window, since, reread = 0) {
     let base = 0, sim = 0, extra = 0, actual = 0;
     let removed = 0, prevActual, prevSim, prevAt;
     for (const r of reqs) {
@@ -104,11 +109,11 @@ function replay(reqs, window, since) {
         let simPrev = prevSim;
         if (ctx >= TRIGGER_SHARE * window) {
             if (counted) {
-                sim += 0.1 * ctx + OUTPUT_RATIO * SUMMARY_OUTPUT;
+                sim += 0.1 * ctx + OUTPUT_RATIO * SUMMARY_OUTPUT + 1.25 * reread;
                 extra++;
             }
-            removed = r.prompt - AFTER_COMPACT;
-            ctx = AFTER_COMPACT;
+            removed = r.prompt - AFTER_COMPACT - reread;
+            ctx = AFTER_COMPACT + reread;
             simPrev = undefined; // everything after a compaction is new to the cache
         }
         if (counted)
@@ -119,7 +124,7 @@ function replay(reqs, window, since) {
     }
     return { base, sim, extra, actual };
 }
-export function estimateCompactWindows(windows, days = 30, paths) {
+export function estimateCompactWindows(windows, days = 30, paths, rereadTokens = 0) {
     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 }));
@@ -138,7 +143,7 @@ export function estimateCompactWindows(windows, days = 30, paths) {
         sessions++;
         actualCompactions += replay(parsed.reqs, Number.MAX_SAFE_INTEGER, since).actual;
         for (const a of acc) {
-            const r = replay(parsed.reqs, a.window, since);
+            const r = replay(parsed.reqs, a.window, since, rereadTokens);
             a.base += (r.base * perM) / 1e6;
             a.sim += (r.sim * perM) / 1e6;
             a.extra += r.extra;
@@ -148,6 +153,7 @@ export function estimateCompactWindows(windows, days = 30, paths) {
         days,
         sessions,
         actualCompactions,
+        rereadTokens,
         estimates: acc.map((a) => ({
             window: a.window,
             baselineUsd: a.base,
@@ -215,6 +221,10 @@ export function renderCompactWindows(r, current) {
     }
     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("");
+    if (r.rereadTokens) {
+        lines.push(`Each simulated compaction also pays for ~${Math.round(r.rereadTokens / 100) / 10}k tokens of files read again afterwards`);
+        lines.push("(measured on your compactions: context-doctor compactions).");
+    }
     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");

package/dist/desktopusage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How Claude Desktop's chat actually uses the MCP server, from Desktop's own
+ * log. Desktop gives an MCP server no hook and no transcript, so its
+ * per-server log (mcp-server-context-doctor.log: initialize, tools/list,
+ * tools/call) is the only evidence that the tools are offered and called.
+ * Desktop does not log which pages are opened, so chat activity itself cannot
+ * be measured locally; Code-tab sessions can (Claude Code transcripts record
+ * the desktop app as their entrypoint), and those reach context-doctor
+ * through Claude Code's hook and MCP config, not through this server.
+ */
+export interface DesktopUsage {
+    launches: number;
+    toolLists: number;
+    toolCalls: number;
+    lastCall?: string;
+}
+export declare function desktopLogDir(home?: string): string;
+export declare function desktopUsage(dir?: string): DesktopUsage | undefined;
+/** One line for `doctor`: the numbers, and what to do with them. `codeTabSessions`: this week's Claude Code sessions run in Desktop's Code tab. */
+export declare function describeDesktopUsage(u: DesktopUsage, codeTabSessions?: number): string;

package/dist/desktopusage.js

@@ -0,0 +1,35 @@
+/**
+ * How Claude Desktop's chat actually uses the MCP server, from Desktop's own
+ * log. Desktop gives an MCP server no hook and no transcript, so its
+ * per-server log (mcp-server-context-doctor.log: initialize, tools/list,
+ * tools/call) is the only evidence that the tools are offered and called.
+ * Desktop does not log which pages are opened, so chat activity itself cannot
+ * be measured locally; Code-tab sessions can (Claude Code transcripts record
+ * the desktop app as their entrypoint), and those reach context-doctor
+ * through Claude Code's hook and MCP config, not through this server.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+export function desktopLogDir(home = homedir()) {
+    switch (platform()) {
+        case "darwin": return join(home, "Library", "Logs", "Claude");
+        case "win32": return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "logs");
+        default: return join(home, ".config", "Claude", "logs");
+    }
+}
+export function desktopUsage(dir = desktopLogDir()) {
+    const server = join(dir, "mcp-server-context-doctor.log");
+    if (!existsSync(server))
+        return undefined;
+    const text = readFileSync(server, "utf8");
+    const count = (m) => text.split(`method="${m}"`).length - 1;
+    const calls = [...text.matchAll(/^(\d{4}-\d\d-\d\d)T[^\n]*method="tools\/call"/gm)];
+    return { launches: count("initialize"), toolLists: count("tools/list"), toolCalls: count("tools/call"), lastCall: calls.at(-1)?.[1] };
+}
+/** One line for `doctor`: the numbers, and what to do with them. `codeTabSessions`: this week's Claude Code sessions run in Desktop's Code tab. */
+export function describeDesktopUsage(u, codeTabSessions = 0) {
+    const base = `tools offered in ${u.toolLists} of ${u.launches} launches, called ${u.toolCalls} time(s)${u.lastCall ? ` (last ${u.lastCall})` : ""}`;
+    const code = codeTabSessions > 0 ? `; your ${codeTabSessions} Code-tab sessions this week use the hook instead` : "";
+    return `${base}${code}. In a chat the model decides when to call them: the + menu's context_checkup prompt runs one on demand`;
+}

package/dist/doctor.js

@@ -14,6 +14,7 @@ import { fileURLToPath } from "node:url";
 import { ledgerPath } from "./ledger.js";
 import { loadConfig } from "./config.js";
 import { geminiCliPresent, geminiSettingsPath } from "./install.js";
+import { describeDesktopUsage, desktopUsage } from "./desktopusage.js";
 function claudeDesktopConfigPath() {
     switch (platform()) {
         case "darwin": return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
@@ -108,6 +109,10 @@ function checkMcpHandshake() {
 export async function runDoctor() {
     const checks = [];
     checks.push(checkMcpEntry("Claude Desktop", claudeDesktopConfigPath()));
+    // Desktop chat has no hook or transcript; its own logs are the only evidence the tools are used.
+    const desktop = desktopUsage();
+    if (desktop)
+        checks.push({ label: "Desktop chat tool use", status: "ok", detail: describeDesktopUsage(desktop, recentSurfaces(7).get("claude-desktop") ?? 0) });
     checks.push(checkMcpEntry("Claude Code", join(homedir(), ".claude.json")));
     checks.push(checkMcpEntry("Cursor", join(homedir(), ".cursor", "mcp.json")));
     // Hook registration
@@ -128,6 +133,11 @@ export async function runDoctor() {
                 checks.push(missing
                     ? { label: "Every-prompt hook", status: "fail", detail: `registered, but ${missing} no longer exists — re-run: context-doctor install` }
                     : { label: "Every-prompt hook", status: "ok", detail: "registered in ~/.claude/settings.json; command resolves" });
+                const pre = settings.hooks?.PreCompact ?? [];
+                const preOurs = pre.some((e) => /context-doctor|cli\.js"?\s+hook/.test(e.hooks?.[0]?.command ?? ""));
+                checks.push(preOurs
+                    ? { label: "Compaction hook", status: "ok", detail: "PreCompact: each compaction's summary keeps the session's files, open tasks, your instructions and failing commands" }
+                    : { label: "Compaction hook", status: "warn", detail: "not registered: compactions use generic instructions; run context-doctor install" });
             }
         }
         catch (e) {

package/dist/hook.js

@@ -24,6 +24,7 @@ import { ensureProxyUp } from "./autopilot.js";
 import { detectColdResume, renderColdResume, renderColdResumeNotice } from "./coldresume.js";
 import { formatUsd, pricingFor } from "./pricing.js";
 import { checkBudget, loadConfig } from "./config.js";
+import { compactFacts, compactInstructions } from "./precompact.js";
 /** Default nudge threshold; a project budget or env var can lower/raise it. */
 const DEFAULT_WARN_TOKENS = 80_000;
 /**
@@ -146,6 +147,19 @@ export async function runHook() {
         }
         const input = JSON.parse(await readStdin());
         await heal;
+        // Before a compaction: tell the summary what this session cannot lose.
+        // Claude Code adds a PreCompact hook's plain-text output to the
+        // compaction's instructions (auto and manual alike).
+        if (input.hook_event_name === "PreCompact") {
+            if (input.transcript_path && existsSync(input.transcript_path)) {
+                const text = compactInstructions(compactFacts(input.transcript_path));
+                if (text) {
+                    process.stdout.write(text + "\n");
+                    recordLedger({ ev: "precompact", sid: (input.session_id ?? "").slice(0, 12), tok: text.length });
+                }
+            }
+            return;
+        }
         // Cursor runs this hook twice over: Claude Code's UserPromptSubmit as its
         // beforeSubmitPrompt (which cannot add context, so there is nothing to do),
         // and natively after each tool call, where `additional_context` reaches

package/dist/index.d.ts

@@ -36,3 +36,5 @@ export * from "./reads.js";
 export * from "./tasks.js";
 export * from "./cacheplan.js";
 export * from "./subagentpay.js";
+export * from "./compactquality.js";
+export * from "./precompact.js";

package/dist/index.js

@@ -31,3 +31,5 @@ export * from "./reads.js";
 export * from "./tasks.js";
 export * from "./cacheplan.js";
 export * from "./subagentpay.js";
+export * from "./compactquality.js";
+export * from "./precompact.js";

package/dist/install.js

@@ -207,7 +207,12 @@ function isOurHookEntry(entry) {
  * Claude Code query gets a context-size check. Idempotent.
  */
 function installHook() {
-    return installHookInto(join(homedir(), ".claude", "settings.json"), join(homedir(), ".claude"));
+    const settings = join(homedir(), ".claude", "settings.json");
+    const path = installHookInto(settings, join(homedir(), ".claude"));
+    // The same command also answers PreCompact: what each compaction's summary must keep.
+    if (path)
+        installHookInto(settings, join(homedir(), ".claude"), "PreCompact");
+    return path;
 }
 /**
  * Register the UserPromptSubmit hook in a hooks file. Claude Code's
@@ -247,6 +252,7 @@ function installHookInto(settingsPath, gateDir, event = "UserPromptSubmit") {
 }
 function uninstallHook() {
     uninstallHookFrom(join(homedir(), ".claude", "settings.json"), "Claude Code every-prompt hook");
+    uninstallHookFrom(join(homedir(), ".claude", "settings.json"), "Claude Code compaction hook", "PreCompact");
     uninstallHookFrom(join(homedir(), ".codex", "hooks.json"), "Codex every-prompt hook");
     uninstallHookFrom(geminiSettingsPath(), "Gemini CLI every-prompt hook", "BeforeAgent");
     uninstallCursorHook();

package/dist/ledger.d.ts

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

package/dist/mcp.js

@@ -52,7 +52,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer({ fileAccess = true } = {}) {
-    const server = new McpServer({ name: "context-doctor", version: "0.30.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.31.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/precompact.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PreCompact: tell Claude Code's compaction what this session cannot lose.
+ *
+ * A compaction replaces the session's history with a summary written by the
+ * model, guided by generic instructions. Whatever a PreCompact hook prints is
+ * added to those instructions (Claude Code merges it as custom instructions,
+ * for automatic and manual compactions alike; checked in 2.1.295). So the
+ * summary can be told, from the transcript itself, which files were changed,
+ * what is still open, what the user insisted on, and which commands are still
+ * failing: the things whose loss makes a session re-read, re-ask and repeat
+ * mistakes after compacting. Facts only, short, and nothing invented: every
+ * line comes from the transcript.
+ */
+export interface CompactFacts {
+    edited: string[];
+    todos: string[];
+    directives: string[];
+    failing: string[];
+}
+/** Facts from the session since the last compaction (the summary before it already carries the earlier ones). */
+export declare function compactFacts(transcriptPath: string): CompactFacts;
+/** The custom instructions a PreCompact hook prints; empty when the transcript holds nothing to pin. */
+export declare function compactInstructions(f: CompactFacts): string;

package/dist/precompact.js

@@ -0,0 +1,118 @@
+/**
+ * PreCompact: tell Claude Code's compaction what this session cannot lose.
+ *
+ * A compaction replaces the session's history with a summary written by the
+ * model, guided by generic instructions. Whatever a PreCompact hook prints is
+ * added to those instructions (Claude Code merges it as custom instructions,
+ * for automatic and manual compactions alike; checked in 2.1.295). So the
+ * summary can be told, from the transcript itself, which files were changed,
+ * what is still open, what the user insisted on, and which commands are still
+ * failing: the things whose loss makes a session re-read, re-ask and repeat
+ * mistakes after compacting. Facts only, short, and nothing invented: every
+ * line comes from the transcript.
+ */
+import { forEachLine } from "./session.js";
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+/** A user line that sets a rule or corrects course. */
+const DIRECTIVE = /\b(don'?t|do not|never|always|instead|make sure|must|should not|shouldn'?t|stop|wrong|not what|revert|undo|keep|prefer|use )\b/i;
+const MAX_CHARS = 2400;
+/** Build, test and lint runs: the commands whose failure is state worth keeping (not a grep that found nothing). */
+const CHECK_COMMAND = /\b(npm|pnpm|yarn|bun)\s+(run\s+)?(test|build|lint|typecheck|check)\b|\b(pytest|tox|cargo\s+(test|build|check|clippy)|go\s+(test|build|vet)|make(\s+\w+)?|tsc|eslint|ruff|mypy|gradle\w*\s+\w+|mvn\s+\w+|swift\s+(build|test)|xcodebuild|dotnet\s+(build|test)|jest|vitest|phpunit|rspec)\b/;
+/** What kind of check a command runs ("npm test", "pytest", "cargo build"): a later success of the same kind clears an earlier failure. */
+function checkKind(cmd) {
+    return CHECK_COMMAND.exec(cmd)?.[0].replace(/\s+run\s+/, " ").replace(/\s+/g, " ");
+}
+function clip(s, n) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+/** Facts from the session since the last compaction (the summary before it already carries the earlier ones). */
+export function compactFacts(transcriptPath) {
+    const edited = [];
+    let todos = [];
+    const directives = [];
+    const commands = new Map(); // tool_use id -> a build/test/lint command
+    const failing = new Map(); // kind -> "command → last error line", removed when that kind later succeeds
+    forEachLine(transcriptPath, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (e.type === "system" && e.subtype === "compact_boundary") {
+            edited.length = 0;
+            todos = [];
+            directives.length = 0;
+            commands.clear();
+            failing.clear();
+            return;
+        }
+        const c = e.message?.content;
+        if (e.type === "assistant" && Array.isArray(c)) {
+            for (const b of c) {
+                if (b?.type !== "tool_use")
+                    continue;
+                const path = b.input?.file_path ?? b.input?.notebook_path;
+                if (EDIT_TOOLS.has(b.name) && typeof path === "string") {
+                    const i = edited.indexOf(path);
+                    if (i >= 0)
+                        edited.splice(i, 1);
+                    edited.push(path);
+                }
+                else if (b.name === "TodoWrite" && Array.isArray(b.input?.todos)) {
+                    todos = b.input.todos.filter((t) => t?.status !== "completed").map((t) => `${t.status === "in_progress" ? "[in progress] " : ""}${clip(String(t.content ?? ""), 140)}`);
+                }
+                else if (b.name === "Bash" && typeof b.input?.command === "string") {
+                    const kind = checkKind(b.input.command);
+                    if (kind)
+                        commands.set(b.id, { cmd: clip(b.input.command, 120), kind });
+                }
+            }
+        }
+        else if (e.type === "user") {
+            if (typeof c === "string" && !e.isMeta && !e.isCompactSummary) {
+                const text = c.replace(/<[^>]+>[\s\S]*?<\/[^>]+>/g, " ").trim();
+                if (text && text.length < 2000 && DIRECTIVE.test(text))
+                    directives.push(clip(text, 200));
+            }
+            else if (Array.isArray(c)) {
+                for (const b of c) {
+                    if (b?.type !== "tool_result" || !commands.has(b.tool_use_id))
+                        continue;
+                    const { cmd, kind } = commands.get(b.tool_use_id);
+                    if (b.is_error) {
+                        const out = typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? "");
+                        failing.set(kind, `${cmd} → ${clip((out.split("\n").find((l) => /error|exception/i.test(l)) ?? out.split("\n").find((l) => /fail/i.test(l)) ?? out.split("\n")[0] ?? ""), 160)}`);
+                    }
+                    else {
+                        failing.delete(kind);
+                    }
+                }
+            }
+        }
+    });
+    return { edited: edited.slice(-25).reverse(), todos: todos.slice(0, 15), directives: directives.slice(-8), failing: [...failing.values()].slice(-5) };
+}
+/** The custom instructions a PreCompact hook prints; empty when the transcript holds nothing to pin. */
+export function compactInstructions(f) {
+    const sections = [];
+    const list = (title, items) => items.length && sections.push(`${title}:\n${items.map((i) => `- ${i}`).join("\n")}`);
+    list("Files changed in this session (keep every path exactly)", f.edited);
+    list("Open tasks (keep them, with their status)", f.todos);
+    list("The user's own instructions and corrections (keep their substance, they still apply)", f.directives);
+    list("Commands still failing at this point (keep the command and the error)", f.failing);
+    if (!sections.length)
+        return "";
+    let out = [
+        "context-doctor, from this session's transcript: the summary must carry the following, so the work continues without re-reading files, re-asking the user, or repeating a failed approach.",
+        ...sections,
+        "Keep exact identifiers (paths, function names, commands, versions, IDs, URLs). Leave out raw tool output already acted on; one line on what it showed is enough.",
+    ].join("\n\n");
+    if (out.length > MAX_CHARS)
+        out = out.slice(0, MAX_CHARS - 1) + "…";
+    return out;
+}

package/dist/proxy.d.ts

@@ -48,7 +48,7 @@ export interface ProxyOptions extends OptimizeOptions {
     googleUpstream?: string;
 }
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export declare const PROXY_VERSION = "0.30.0";
+export declare const PROXY_VERSION = "0.31.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.30.0";
+export const PROXY_VERSION = "0.31.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Cut your Claude Code bill, measured on your own sessions: `npx context-doctor savings` shows what each lever saves, then the hook, autopilot and an earlier auto-compact window do it. Also Cursor, Codex, Claude Desktop and any Anthropic or OpenAI API app. MCP server and Claude Code plugin.",
   "keywords": [
     "agent",