context-doctor 0.3.4 → 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,34 @@ 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:
+
+| Touchpoint | When it runs | Overhead |
+|---|---|---|
+| Every-prompt hook (Claude Code) | Every prompt | **~80ms** (Node startup; logic ~1ms). Lean sessions exit on a single `stat()` — the transcript is never read. Full profiling (~200ms on a 4MB session) happens only when the transcript has grown ~40% since last checked |
+| MCP server | Spawned once per app session | Tools run only when called; standing instructions cost **~110 tokens per conversation** — deliberately terse |
+| Proxy | Per API request | ~1–3ms of CPU (parse → optimize → re-serialize) against typical model latencies of hundreds of ms; responses stream through chunk-by-chunk, never buffered |
+| Skill | Loads only when relevant | ~1k tokens while active; its always-present description is ~60 tokens |
+| CLI / library | Only when you run it | Not in any hot path |
+
+Net effect is strongly negative overhead: the tokens these touchpoints save on every subsequent call dwarf what they cost.
+
 ## Why token counts are "~"
 
 Exact counts require each provider's private tokenizer. `context-doctor` uses a calibrated chars-per-token heuristic (denser for code/JSON) that lands within ~10% — plenty accurate for finding what's heavy and measuring savings, and it keeps the tool fully offline with zero configuration.

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

@@ -10,9 +10,8 @@
  * Registered by `context-doctor install` under hooks.UserPromptSubmit in
  * ~/.claude/settings.json; removed by `context-doctor uninstall`.
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { recordLedger, statePath } from "./ledger.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
@@ -22,9 +21,13 @@ import { formatUsd } from "./pricing.js";
 const WARN_TOKENS = 80_000;
 /** Re-nudge only after the context grows another 40% — one reminder, not a nag. */
 const REGROWTH_FACTOR = 1.4;
-function statePath() {
-    return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
-}
+/**
+ * Fast-path gate: text tokens are at least ~4 bytes each and the transcript
+ * carries JSON overhead on top, so a file smaller than this cannot possibly
+ * hold WARN_TOKENS of context. Lean sessions cost one stat() call — the
+ * transcript is never even read.
+ */
+const MIN_BYTES_FOR_WARN = WARN_TOKENS * 4;
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -38,13 +41,15 @@ export async function runHook() {
         const transcriptPath = input.transcript_path;
         if (!transcriptPath || !existsSync(transcriptPath))
             return;
-        const parsed = parseSessionFile(transcriptPath);
-        if (parsed.messageCount === 0)
-            return;
-        const profile = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
-        if (profile.totalTokens < WARN_TOKENS)
+        // Fast path 1: a small transcript cannot exceed the threshold — exit on a
+        // single stat() without reading the file. This is the every-prompt cost
+        // for lean sessions: ~1ms.
+        const sizeBytes = statSync(transcriptPath).size;
+        if (sizeBytes < MIN_BYTES_FOR_WARN)
             return;
-        // Per-session rate limit so the nudge fires on growth, not on every prompt.
+        // Fast path 2: growth gate BEFORE parsing. If the file hasn't grown ~40%
+        // since the last full parse, nothing new can trigger — exit without the
+        // expensive read. Heavy-but-quiet sessions cost one stat + tiny state read.
         const sessionId = input.session_id ?? transcriptPath;
         let state = {};
         try {
@@ -53,11 +58,24 @@ export async function runHook() {
         catch {
             /* first run */
         }
-        const lastWarnedAt = state[sessionId] ?? 0;
-        if (profile.totalTokens < lastWarnedAt * REGROWTH_FACTOR)
+        const rawPrev = state[sessionId];
+        // Migrate pre-0.3.5 numeric entries ({tokens only}) to the new shape.
+        const prev = typeof rawPrev === "number" ? { t: rawPrev, b: 0 } : rawPrev ?? { t: 0, b: 0 };
+        if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR)
+            return;
+        // Slow path (growth events only): full parse + profile.
+        const parsed = parseSessionFile(transcriptPath);
+        if (parsed.messageCount === 0)
             return;
-        const entries = Object.entries({ ...state, [sessionId]: profile.totalTokens });
+        const profile = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
+        // Record this parse so the next prompts take fast path 2.
+        const shouldWarn = profile.totalTokens >= WARN_TOKENS && profile.totalTokens >= prev.t * REGROWTH_FACTOR;
+        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 = [
             `This session's context is at ~${formatTokens(profile.totalTokens)} tokens` +
                 (profile.usagePct ? ` (${profile.usagePct.toFixed(0)}% of the window)` : "") +

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,18 +20,17 @@ 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.
  * This is what upgrades plain-chat apps from "tools available on request" to
  * "standing context-hygiene instructions in every chat" — no hook needed.
  */
-const SERVER_INSTRUCTIONS = `context-doctor keeps this conversation's context window lean, fast, and cheap. Standing instructions for every conversation:
-1. Practice context hygiene continuously: after consuming a large tool result or pasted document, carry forward a one-sentence summary instead of re-quoting it; reference earlier content rather than repeating it; never inline base64.
-2. When the conversation has grown long (roughly 30+ turns) or contains several large pastes, proactively offer to profile it and call profile_context — do not wait to be asked.
-3. When the user asks anything about token usage, cost, latency, or "what's eating my context", call profile_context immediately rather than estimating by eye.
-4. When optimize_context returns a pruned-turns digest, YOU write the replacement summary (dense, factual, ≤150 tokens) as instructed in the result.`;
-const server = new McpServer({ name: "context-doctor", version: "0.3.4" }, { instructions: SERVER_INSTRUCTIONS });
+// 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.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"),
@@ -53,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.4",
+  "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"