context-doctor 0.3.5 → 0.3.6

package/README.md

@@ -64,7 +64,7 @@ One run of `npx context-doctor install` writes five things (each config edit mak
 **In every Claude Code / Cowork session afterward:** all of the above via MCP, plus two more layers:
 
 - the **skill** loads whenever context work is relevant, and
-- the **hook runs on every single prompt you send**: it measures the session's real size in ~100ms. Under 80k tokens it stays completely silent. Above, it injects a note the model sees with your message — actual token count, cost per message, the single largest recoverable waste — with instructions to work leaner and offer you compaction. It re-fires only after ~40% further growth, and can never break a prompt (any failure exits silently).
+- the **hook runs on every single prompt you send**: lean sessions cost a ~1ms file-size check; once a session is heavy it profiles on growth events and injects a note the model sees with your message — actual token count, cost per message, the single largest recoverable waste — with instructions to work leaner and offer you compaction. It re-fires only after ~40% further growth, can never break a prompt (any failure exits silently), and logs each deep check to a small local ledger that feeds `context-doctor report`.
 
 **What it never does:** delete or rewrite your history without asking (pruning is consent-only, and the model writes the replacement summary so nothing is lost silently), send data anywhere (everything runs on your machine), or touch an API key.
 
@@ -83,6 +83,18 @@ MCP is just one of six delivery mechanisms. It's only required when you want the
 
 Practical upshot: a developer who only wants cheaper, faster API calls never touches MCP (proxy + CLI). A Claude Code user gets the hook and skill without MCP either — the MCP server just adds in-chat tools on top. `install` sets up all of it at once precisely so you don't have to think about which mechanism is which.
 
+## All commands at a glance
+
+| Command | What it does |
+|---|---|
+| `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor, the Agent Skill, the every-prompt hook |
+| `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates |
+| `context-doctor optimize <file>` | Apply the safe fixes; `--strategy prune-history` for consented lossy compaction |
+| `context-doctor session [file]` | Profile a Claude Code session transcript (defaults to your most recent; `--list` to browse) |
+| `context-doctor report` | Machine-wide impact report: exact proxy savings, hook activity, 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 hook` | The every-prompt Claude Code hook (registered by `install`; you never run this yourself) |
+
 ## What "always-on" means, per surface
 
 | Where you run LLMs | Mechanism | Guarantee |
@@ -246,6 +258,20 @@ Everything the optimizer does is inspectable: it prints exactly which messages c
 
 `skills/context-doctor/SKILL.md` (installed by `npx context-doctor install`) teaches Claude to practice context hygiene proactively: summarize big tool results after consuming them, never re-paste duplicated content, keep stable content cache-friendly, and offer compaction when a session gets heavy — so sessions get inherently leaner without you asking.
 
+## Measuring the impact: `context-doctor report`
+
+```bash
+npx context-doctor report
+```
+
+One report for your whole machine, led by a headline of **tokens context-doctor saved**, built only from measured sources:
+
+- **exact** proxy savings (real before/after on every request),
+- **exact** savings from every optimization applied via the CLI or the in-chat tools — split by model family (Claude vs GPT), with dollar estimates,
+- **observed per-session shrinkage**: real context reductions recorded between the hook's deep checks after hygiene warnings — shown per session in the table alongside remaining waste.
+
+Honest measurement note: proxy numbers are exact. Session numbers are measured-now. What no tool can report is the counterfactual — tokens Claude *avoided* adding because of the hygiene guidance — since the same session can't be re-run without it. The report says so instead of inventing a number.
+
 ## Performance: what context-doctor itself costs
 
 A tool that promises speed must be near-free. Measured overhead per touchpoint:

package/dist/cli.js

@@ -18,6 +18,8 @@ import { startProxy } from "./proxy.js";
 import { runInstall, runUninstall } from "./install.js";
 import { listSessions, parseSessionFile } from "./session.js";
 import { runHook } from "./hook.js";
+import { buildImpactReport } from "./impact.js";
+import { recordLedger } from "./ledger.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -32,6 +34,8 @@ Usage:
                                                 (default: the most recent session; --list to browse)
   context-doctor hook                           Claude Code UserPromptSubmit hook (installed
                                                 automatically by \`install\`; reads hook JSON on stdin)
+  context-doctor report                         Impact report: exact proxy savings, hook activity,
+                                                and remaining recoverable waste in recent sessions
 
 Input: a conversation JSON file (OpenAI or Anthropic message format, or a bare
 message array). Use "-" to read from stdin.
@@ -119,6 +123,10 @@ function main() {
         void runHook();
         return;
     }
+    if (args.command === "report") {
+        void buildImpactReport(args.port).then((r) => console.log(r));
+        return;
+    }
     if (args.command === "session") {
         if (args.list) {
             const sessions = listSessions();
@@ -215,6 +223,9 @@ function main() {
             console.log(output);
         }
         const saved = result.tokensBefore - result.tokensAfter;
+        if (saved > 0) {
+            recordLedger({ ev: "optimize", src: "cli", saved, model: result.conversation?.model });
+        }
         const pct = result.tokensBefore > 0 ? Math.round((saved / result.tokensBefore) * 100) : 0;
         console.error(`\ncontext-doctor: ${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)} tokens ` +
             `(saved ~${formatTokens(saved)}, ${pct}%) via ${result.applied.length} change(s)` +

package/dist/hook.js

@@ -11,8 +11,7 @@
  * ~/.claude/settings.json; removed by `context-doctor uninstall`.
  */
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { recordLedger, statePath } from "./ledger.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
@@ -29,9 +28,6 @@ const REGROWTH_FACTOR = 1.4;
  * transcript is never even read.
  */
 const MIN_BYTES_FOR_WARN = WARN_TOKENS * 4;
-function statePath() {
-    return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
-}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -77,6 +73,7 @@ export async function runHook() {
         const nextState = { t: shouldWarn ? profile.totalTokens : prev.t, b: sizeBytes };
         const entries = Object.entries({ ...state, [sessionId]: nextState });
         writeFileSync(statePath(), JSON.stringify(Object.fromEntries(entries.slice(-100))));
+        recordLedger({ ev: "check", sid: sessionId.slice(0, 12), tok: profile.totalTokens, warn: shouldWarn });
         if (!shouldWarn)
             return;
         const lines = [

package/dist/impact.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `context-doctor report` — one impact report for this machine.
+ *
+ * Honesty rules baked in: proxy numbers are EXACT (real before/after on every
+ * request). Session numbers are MEASURED-NOW (current size + what optimization
+ * would still recover). The behavioral counterfactual — what Claude avoided
+ * wasting because of hygiene guidance — cannot be measured by anyone: the same
+ * session cannot be re-run without it. The report says so instead of inventing
+ * a number.
+ */
+export declare function buildImpactReport(proxyPort?: number): Promise<string>;

package/dist/impact.js

@@ -0,0 +1,147 @@
+/**
+ * `context-doctor report` — one impact report for this machine.
+ *
+ * Honesty rules baked in: proxy numbers are EXACT (real before/after on every
+ * request). Session numbers are MEASURED-NOW (current size + what optimization
+ * would still recover). The behavioral counterfactual — what Claude avoided
+ * wasting because of hygiene guidance — cannot be measured by anyone: the same
+ * session cannot be re-run without it. The report says so instead of inventing
+ * a number.
+ */
+import { readLedger } from "./ledger.js";
+import { listSessions, parseSessionFile } from "./session.js";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
+/** Sessions larger than this are skipped in the report (keeps it snappy). */
+const MAX_SESSION_BYTES = 30 * 1024 * 1024;
+async function fetchProxyStats(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/stats`, { signal: AbortSignal.timeout(500) });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildImpactReport(proxyPort = 8787) {
+    const lines = [];
+    lines.push("CONTEXT DOCTOR — impact report");
+    lines.push("═".repeat(56));
+    const ledger = readLedger();
+    const checks = ledger.filter((e) => e.ev === "check" || e.ev === undefined);
+    const optimizes = ledger.filter((e) => e.ev === "optimize");
+    // Observed per-session reductions: when a session SHRANK between two deep
+    // checks (compaction/cleanup after a warning), that drop is measured fact.
+    const bySession = new Map();
+    for (const c of checks) {
+        if (!c.sid || typeof c.tok !== "number")
+            continue;
+        const s = bySession.get(c.sid) ?? { toks: [], warns: 0 };
+        s.toks.push(c.tok);
+        if (c.warn)
+            s.warns++;
+        bySession.set(c.sid, s);
+    }
+    const reductionBySession = new Map();
+    for (const [sid, s] of bySession) {
+        let reduction = 0;
+        for (let i = 1; i < s.toks.length; i++) {
+            if (s.toks[i] < s.toks[i - 1])
+                reduction += s.toks[i - 1] - s.toks[i];
+        }
+        reductionBySession.set(sid, reduction);
+    }
+    const totalReduction = [...reductionBySession.values()].reduce((a, b) => a + b, 0);
+    // Optimize-event savings, split by model family (claude / gpt / other).
+    const optimizeSaved = optimizes.reduce((s, e) => s + (e.saved ?? 0), 0);
+    const savedByFamily = new Map();
+    let optimizeUsd = 0;
+    for (const e of optimizes) {
+        const family = /claude/i.test(e.model ?? "") ? "claude" : /gpt|^o\d/i.test(e.model ?? "") ? "gpt" : "other";
+        savedByFamily.set(family, (savedByFamily.get(family) ?? 0) + (e.saved ?? 0));
+        const pricing = pricingFor(e.model);
+        if (pricing && e.saved)
+            optimizeUsd += inputCostUsd(e.saved, pricing);
+    }
+    const proxy = await fetchProxyStats(proxyPort);
+    const proxySaved = proxy?.tokensSaved ?? 0;
+    // -- Headline: what context-doctor has saved ----------------------------------
+    const totalSaved = proxySaved + optimizeSaved + totalReduction;
+    lines.push("Tokens context-doctor saved (measured)");
+    lines.push("─".repeat(56));
+    lines.push(`TOTAL: ~${formatTokens(totalSaved)} tokens`);
+    if (proxy) {
+        lines.push(`  · proxy (exact, current run): ${formatTokens(proxySaved)} across ${proxy.optimizedRequests}/${proxy.requests} requests ≈ ${formatUsd(proxy.estUsdSaved)}`);
+    }
+    else {
+        lines.push(`  · proxy: not running on :${proxyPort} (its exact savings appear here while it runs)`);
+    }
+    const familyNote = [...savedByFamily.entries()]
+        .filter(([, v]) => v > 0)
+        .map(([k, v]) => `${k}: ${formatTokens(v)}`)
+        .join(", ");
+    lines.push(`  · optimizations applied via CLI/chat tools (exact): ${formatTokens(optimizeSaved)} over ${optimizes.length} run(s)` +
+        (familyNote ? ` [${familyNote}]` : "") +
+        (optimizeUsd > 0 ? ` ≈ ${formatUsd(optimizeUsd)}` : ""));
+    lines.push(`  · observed session shrinkage after hygiene warnings: ${formatTokens(totalReduction)}`);
+    lines.push("");
+    // -- Hook activity ------------------------------------------------------------
+    lines.push("Hygiene activity (every-prompt hook)");
+    lines.push("─".repeat(56));
+    if (checks.length > 0) {
+        const warnings = checks.filter((e) => e.warn).length;
+        lines.push(`${checks.length} deep context checks across ${bySession.size} session(s); ${warnings} warning(s) delivered to the model.`);
+        lines.push("(Prompt-level fast checks are not logged — they cost ~1ms and leave no trace by design.)");
+    }
+    else {
+        lines.push("No hook activity recorded yet (ledger appears after the first deep check of a heavy session).");
+    }
+    lines.push("");
+    // -- Measured-now: recent session profiles ------------------------------------
+    lines.push("Your recent sessions — waste still recoverable today");
+    lines.push("─".repeat(56));
+    const sessions = listSessions(8).filter((s) => s.sizeBytes <= MAX_SESSION_BYTES);
+    if (sessions.length === 0) {
+        lines.push("No Claude Code session transcripts found.");
+    }
+    else {
+        let totalTokens = 0;
+        let totalWaste = 0;
+        let totalWasteUsd = 0;
+        for (const s of sessions) {
+            try {
+                const parsed = parseSessionFile(s.path);
+                if (parsed.messageCount === 0)
+                    continue;
+                const p = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
+                totalTokens += p.totalTokens;
+                totalWaste += p.totalEstSavings;
+                if (p.cost)
+                    totalWasteUsd += p.cost.savingsPerCallUsd;
+                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 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)} ` +
+                    `${formatTokens(p.totalTokens).padStart(6)} tok · waste ${String(wastePct).padStart(2)}%` +
+                    (saved > 0 ? ` · saved ${formatTokens(saved)}` : warns > 0 ? ` · ${warns} warning(s)` : ""));
+            }
+            catch {
+                /* unreadable session — skip */
+            }
+        }
+        lines.push("");
+        lines.push(`Across these sessions: ~${formatTokens(totalTokens)} tokens held; ~${formatTokens(totalWaste)} still recoverable` +
+            (totalWasteUsd > 0 ? ` (≈ ${formatUsd(totalWasteUsd)} of input per message sent in them)` : ""));
+    }
+    lines.push("");
+    lines.push("What no report can show: tokens Claude AVOIDED adding thanks to the standing");
+    lines.push("hygiene guidance — the same session cannot be re-run without it. Proxy numbers");
+    lines.push("above are exact; session numbers are what optimization would still save now.");
+    return lines.join("\n");
+}

package/dist/ledger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Local activity ledger: one JSONL line per notable event, feeding
+ * `context-doctor report`. Best-effort by design — a ledger failure must
+ * never break a prompt, a tool call, or an optimize run.
+ *
+ * Event shapes (all carry ts):
+ *   check    — hook deep-parsed a session   {ev?: undefined|"check", sid, tok, warn}
+ *              (pre-0.3.6 hook entries have no `ev` field; treated as checks)
+ *   optimize — an optimization was applied  {ev: "optimize", src: "cli"|"mcp", saved, model?}
+ */
+export interface LedgerEntry {
+    ts: number;
+    ev?: "check" | "optimize";
+    sid?: string;
+    tok?: number;
+    warn?: boolean;
+    src?: "cli" | "mcp";
+    saved?: number;
+    model?: string;
+}
+export declare function statePath(): string;
+export declare function ledgerPath(): string;
+export declare function recordLedger(entry: Omit<LedgerEntry, "ts">): void;
+export declare function readLedger(): LedgerEntry[];

package/dist/ledger.js

@@ -0,0 +1,54 @@
+/**
+ * Local activity ledger: one JSONL line per notable event, feeding
+ * `context-doctor report`. Best-effort by design — a ledger failure must
+ * never break a prompt, a tool call, or an optimize run.
+ *
+ * Event shapes (all carry ts):
+ *   check    — hook deep-parsed a session   {ev?: undefined|"check", sid, tok, warn}
+ *              (pre-0.3.6 hook entries have no `ev` field; treated as checks)
+ *   optimize — an optimization was applied  {ev: "optimize", src: "cli"|"mcp", saved, model?}
+ */
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export function statePath() {
+    return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
+}
+export function ledgerPath() {
+    return join(dirname(statePath()), ".context-doctor-ledger.jsonl");
+}
+export function recordLedger(entry) {
+    const path = ledgerPath();
+    try {
+        // Cap growth: past ~256KB keep the most recent 500 entries.
+        if (existsSync(path) && statSync(path).size > 256 * 1024) {
+            const lines = readFileSync(path, "utf8").trimEnd().split("\n");
+            writeFileSync(path, lines.slice(-500).join("\n") + "\n");
+        }
+        appendFileSync(path, JSON.stringify({ ts: Date.now(), ...entry }) + "\n");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export function readLedger() {
+    const path = ledgerPath();
+    if (!existsSync(path))
+        return [];
+    try {
+        return readFileSync(path, "utf8")
+            .trimEnd()
+            .split("\n")
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/mcp.js

@@ -20,6 +20,7 @@ import { profileConversation } from "./profile.js";
 import { optimizeConversation } from "./optimize.js";
 import { renderProfile } from "./report.js";
 import { formatTokens } from "./tokens.js";
+import { recordLedger } from "./ledger.js";
 /**
  * Server instructions are injected by MCP clients (Claude Desktop, Cursor, …)
  * into the system context of EVERY conversation where this server is enabled.
@@ -29,7 +30,7 @@ import { formatTokens } from "./tokens.js";
 // Kept deliberately terse: these ride in EVERY conversation's context, and a
 // context-saving tool must not itself be context overhead (~110 tokens).
 const SERVER_INSTRUCTIONS = `Context hygiene, always: summarize large pastes/tool results instead of carrying them verbatim; reference earlier content, don't re-quote; never inline base64. Past ~30 turns or several large pastes, proactively offer to run profile_context. Any question about tokens, cost, or latency: call profile_context, don't estimate. If optimize_context returns a pruned-turns digest, you write the ≤150-token replacement summary.`;
-const server = new McpServer({ name: "context-doctor", version: "0.3.5" }, { instructions: SERVER_INSTRUCTIONS });
+const server = new McpServer({ name: "context-doctor", version: "0.3.6" }, { instructions: SERVER_INSTRUCTIONS });
 const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-history"];
 server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
     conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
@@ -51,6 +52,9 @@ server.tool("optimize_context", "Rewrite a conversation to reclaim tokens using
         maxToolResultTokens: max_tool_result_tokens,
     });
     const saved = result.tokensBefore - result.tokensAfter;
+    if (saved > 0) {
+        recordLedger({ ev: "optimize", src: "mcp", saved, model: result.conversation?.model });
+    }
     const summary = `Saved ~${formatTokens(saved)} tokens (${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)}) ` +
         `via ${result.applied.length} change(s):\n` +
         result.applied.map((c) => `- [${c.strategy}] message #${c.messageIndex}: ${c.note} (~${formatTokens(c.tokensSaved)})`).join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude, GPT, Gemini, and any MCP-capable AI app.",
   "keywords": [
     "llm",
@@ -38,7 +38,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
     "prepublishOnly": "npm run build",
     "dev": "tsc --watch",
     "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/hook.test.js"