context-doctor 0.10.0 → 0.11.0

package/README.md

@@ -92,7 +92,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor optimize <file>` | Apply the safe fixes; `--strategy prune-history` for consented lossy compaction |
 | `context-doctor session [file]` | Profile a Claude Code session: live context, findings, **measured tokens and prompt-cache economics**. Also reads ChatGPT data exports (`conversations.json`) |
 | `context-doctor cursor [--list]` | Profile a chat from Cursor's local history (both storage formats) |
-| `context-doctor report` | Machine-wide impact report: exact proxy savings, hook activity, recoverable waste in recent sessions |
+| `context-doctor report` | Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, recoverable waste in recent sessions |
 | `context-doctor proxy` | Always-on local proxy that optimizes every Anthropic/OpenAI API request in flight (`/stats` for cumulative savings) |
 | `context-doctor watch [file]` | Live monitor of a growing session/agent trace: token/cost line per change, findings as they appear |
 | `context-doctor doctor` | Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes |
@@ -319,6 +319,16 @@ npx context-doctor analyze conversation.json --fail-over-budget
 
 Exits 1 when the `.contextdoctorrc` budget is breached, so a pull request can be gated on context size the same way it is gated on tests.
 
+## Sharing a profile safely
+
+A profile quotes message previews and file paths, so pasting one into an issue pastes fragments of real work. `--redact` keeps every number and the finding structure but replaces content with `[redacted]` and masks paths:
+
+```bash
+npx context-doctor session --redact
+```
+
+`context-doctor doctor` is safe to paste as-is: it reports integration status, never conversation content.
+
 ## Performance: what context-doctor itself costs
 
 A tool that promises speed must be near-free. Measured overhead per touchpoint:
@@ -329,6 +339,7 @@ A tool that promises speed must be near-free. Measured overhead per touchpoint:
 | 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 |
+| Profiling a session | On demand, and on hook growth events | ~160ms for an 8.5MB / 1,855-message transcript (near-duplicate pairs that cannot clear the similarity bar are skipped without comparison) |
 | 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.

package/dist/cli.js

@@ -64,6 +64,8 @@ Options:
   --model <name>          Model name for window-size math (e.g. claude-sonnet-5, gpt-4o)
   --exact                 (analyze) Add an exact token count: Anthropic count-tokens API for
                           Claude models (needs ANTHROPIC_API_KEY), tiktoken for GPT (if installed)
+  --redact                Mask message previews and file paths in the report, so it can be
+                          shared in a bug report without leaking conversation content
   --json                  Machine-readable output
   --fail-over-budget      (analyze/session) Exit 1 when the .contextdoctorrc budget is
                           exceeded — lets CI gate a pull request on context size
@@ -89,7 +91,7 @@ Examples:
           export OPENAI_BASE_URL=http://localhost:8787/v1
 `;
 function parseArgs(argv) {
-    const args = { json: false, strategies: [], list: false, exact: false, failOverBudget: false };
+    const args = { json: false, strategies: [], list: false, exact: false, redact: false, failOverBudget: false };
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -107,6 +109,9 @@ function parseArgs(argv) {
             case "--exact":
                 args.exact = true;
                 break;
+            case "--redact":
+                args.redact = true;
+                break;
             case "--fail-over-budget":
                 args.failOverBudget = true;
                 break;
@@ -228,7 +233,7 @@ function main() {
         }
         else {
             console.log(`Cursor chat: ${chat.title ?? "(untitled)"}\nId:          ${chat.composerId}\n`);
-            console.log(renderProfile(profile));
+            console.log(renderProfile(profile, { redact: args.redact }));
             if (parsed.reportedInputTokens) {
                 console.log("");
                 console.log(`Measured context (reported by the API on the last request): ${parsed.reportedInputTokens} tokens.\n` +
@@ -275,7 +280,7 @@ function main() {
                 console.log(`Note:    ${parsed.compactedAway} earlier message(s) were compacted away and are NOT counted below — this is the live context the model still sees.`);
             }
             console.log("");
-            console.log(renderProfile(profile));
+            console.log(renderProfile(profile, { redact: args.redact }));
             if (parsed.reportedInputTokens) {
                 console.log("");
                 console.log(`Measured context (reported by the API on the last request): ${parsed.reportedInputTokens} tokens.\n` +
@@ -339,7 +344,7 @@ function main() {
     if (args.command === "analyze") {
         const loaded = loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`));
         const profile = profileConversation(parseConversation(input), args.model ?? loaded.config.model);
-        console.log(args.json ? JSON.stringify(profile, null, 2) : renderProfile(profile));
+        console.log(args.json ? JSON.stringify(profile, null, 2) : renderProfile(profile, { redact: args.redact }));
         if (!args.json)
             applyBudgetGate(printBudgetStatus(profile, loaded), args.failOverBudget);
         else

package/dist/impact.js

@@ -68,17 +68,24 @@ export async function buildImpactReport(proxyPort = 8787) {
             optimizeUsd += inputCostUsd(e.saved, pricing);
     }
     const proxy = await fetchProxyStats(proxyPort);
-    const proxySaved = proxy?.tokensSaved ?? 0;
+    // Persisted checkpoints cover proxy runs that have since exited; the live
+    // process reports whatever it has not checkpointed yet.
+    const proxyEvents = ledger.filter((e) => e.ev === "proxy");
+    const proxyHistoric = proxyEvents.reduce((s, e) => s + (e.saved ?? 0), 0);
+    const proxySaved = proxyHistoric + (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)}`);
+        lines.push(`  · proxy (exact): ${formatTokens(proxySaved)} — ${formatTokens(proxyHistoric)} from earlier runs, ` +
+            `${formatTokens(proxy.tokensSaved)} live 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)`);
+        lines.push(proxyHistoric > 0
+            ? `  · proxy (exact, from ${proxyEvents.length} earlier run checkpoint(s)): ${formatTokens(proxyHistoric)} — not running now`
+            : `  · proxy: not running on :${proxyPort} (its exact savings appear here once it runs)`);
     }
     const familyNote = [...savedByFamily.entries()]
         .filter(([, v]) => v > 0)

package/dist/ledger.d.ts

@@ -7,14 +7,17 @@
  *   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?}
+ *   proxy    — proxy savings checkpoint      {ev: "proxy", saved, usd?, requests?}
  */
 export interface LedgerEntry {
     ts: number;
-    ev?: "check" | "optimize";
+    ev?: "check" | "optimize" | "proxy";
     sid?: string;
     tok?: number;
     warn?: boolean;
-    src?: "cli" | "mcp";
+    src?: "cli" | "mcp" | "proxy";
+    usd?: number;
+    requests?: number;
     saved?: number;
     model?: string;
 }

package/dist/ledger.js

@@ -7,6 +7,7 @@
  *   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?}
+ *   proxy    — proxy savings checkpoint      {ev: "proxy", saved, usd?, requests?}
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-hist
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.10.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.11.0" }, { instructions: SERVER_INSTRUCTIONS });
     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"),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),

package/dist/profile.js

@@ -84,6 +84,8 @@ function sampledShingles(text) {
     }
     return out;
 }
+/** Similarity at or above which two messages count as near-duplicates. */
+const SIMILARITY_THRESHOLD = 0.6;
 function jaccard(a, b) {
     if (a.size === 0 || b.size === 0)
         return 0;
@@ -149,6 +151,11 @@ export function profileConversation(conv, model) {
             .sort((a, b) => b.tokens - a.tokens)
             .slice(0, 150);
         const shingleSets = candidates.map((p) => sampledShingles(p.msg.text));
+        // Jaccard has a hard ceiling of |smaller| / |larger|: two shingle sets of
+        // very different sizes CANNOT reach the threshold, so those pairs are
+        // skipped without intersecting them. Exact, not heuristic — it changes
+        // runtime, never results.
+        const sizes = shingleSets.map((set) => set.size);
         const exactDup = new Set(findings.filter((f) => f.id === "duplicate_content").flatMap((f) => f.messages));
         for (let i = 0; i < candidates.length; i++) {
             for (let j = i + 1; j < candidates.length; j++) {
@@ -156,8 +163,12 @@ export function profileConversation(conv, model) {
                 const b = candidates[j];
                 if (exactDup.has(a.msg.index) && exactDup.has(b.msg.index))
                     continue; // already flagged exactly
+                const small = Math.min(sizes[i], sizes[j]);
+                const large = Math.max(sizes[i], sizes[j]);
+                if (large === 0 || small / large < SIMILARITY_THRESHOLD)
+                    continue; // cannot clear the bar
                 const sim = jaccard(shingleSets[i], shingleSets[j]);
-                if (sim >= 0.6) {
+                if (sim >= SIMILARITY_THRESHOLD) {
                     const smaller = Math.min(a.tokens, b.tokens);
                     const [first, second] = a.msg.index <= b.msg.index ? [a, b] : [b, a];
                     findings.push({

package/dist/proxy.js

@@ -15,6 +15,7 @@ import http from "node:http";
 import { optimizeConversation } from "./optimize.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
+import { recordLedger } from "./ledger.js";
 /** 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"]);
@@ -208,6 +209,36 @@ export function startProxy(opts = {}) {
             res.end(JSON.stringify({ error: `context-doctor proxy: ${e.message}` }));
         }
     });
+    // Savings live in memory, so a restart would erase the record the dashboard
+    // and report draw on. Checkpoint the delta to the ledger periodically and on
+    // shutdown, so the history survives the process.
+    let checkpointedTokens = 0;
+    let checkpointedUsd = 0;
+    let checkpointedRequests = 0;
+    const checkpoint = () => {
+        const savedDelta = stats.tokensSaved - checkpointedTokens;
+        if (savedDelta <= 0)
+            return;
+        recordLedger({
+            ev: "proxy",
+            src: "proxy",
+            saved: savedDelta,
+            usd: Number((stats.estUsdSaved - checkpointedUsd).toFixed(6)),
+            requests: stats.optimizedRequests - checkpointedRequests,
+        });
+        checkpointedTokens = stats.tokensSaved;
+        checkpointedUsd = stats.estUsdSaved;
+        checkpointedRequests = stats.optimizedRequests;
+    };
+    const checkpointTimer = setInterval(checkpoint, 60_000);
+    checkpointTimer.unref?.(); // never hold the process open on our account
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.once(signal, () => {
+            checkpoint();
+            process.exit(0);
+        });
+    }
+    server.on("close", checkpoint);
     const host = opts.host ?? "127.0.0.1";
     server.listen(port, host, () => {
         console.error(`context-doctor proxy listening on http://${host}:${port}`);

package/dist/report.d.ts

@@ -4,4 +4,12 @@
  * anywhere (terminals, issues, chat).
  */
 import { ContextProfile } from "./profile.js";
-export declare function renderProfile(profile: ContextProfile): string;
+export interface RenderOptions {
+    /**
+     * Replace anything quoted from the conversation with a placeholder, so a
+     * profile can be pasted into a bug report without leaking content. Numbers
+     * and structure — the parts that make a report useful — are kept.
+     */
+    redact?: boolean;
+}
+export declare function renderProfile(profile: ContextProfile, options?: RenderOptions): string;

package/dist/report.js

@@ -18,7 +18,13 @@ function bar(fraction, width = 28) {
     const filled = Math.round(fraction * width);
     return "█".repeat(filled) + "░".repeat(width - filled);
 }
-export function renderProfile(profile) {
+/** Mask filesystem paths and quoted fragments inside a finding's text. */
+function redactText(text) {
+    return text
+        .replace(/(?:\/[\w.@ -]+){2,}/g, "[path]")
+        .replace(/\b[\w.-]+\.(ts|tsx|js|jsx|py|go|rs|java|rb|md|json|ya?ml|sql|sh)\b/gi, "[file]");
+}
+export function renderProfile(profile, options = {}) {
     const lines = [];
     const p = profile;
     lines.push("CONTEXT DOCTOR — profile");
@@ -52,7 +58,9 @@ export function renderProfile(profile) {
     lines.push("─".repeat(56));
     for (const m of p.largestMessages) {
         const label = m.toolName ? `${m.kind}:${m.toolName}` : m.kind;
-        lines.push(`  #${m.index} [${label}] ~${formatTokens(m.tokens)}  ${m.preview}`);
+        // The preview is the only place raw conversation text reaches the report.
+        const body = options.redact ? "[redacted]" : m.preview;
+        lines.push(`  #${m.index} [${label}] ~${formatTokens(m.tokens)}  ${body}`);
     }
     lines.push("");
     // Findings
@@ -61,7 +69,7 @@ export function renderProfile(profile) {
         lines.push("─".repeat(56));
         for (const f of p.findings) {
             const savings = f.estSavings > 0 ? ` [save ~${formatTokens(f.estSavings)}]` : "";
-            lines.push(`${SEVERITY_MARK[f.severity]} ${f.message}${savings}`);
+            lines.push(`${SEVERITY_MARK[f.severity]} ${options.redact ? redactText(f.message) : f.message}${savings}`);
             lines.push(`   → ${f.suggestion}`);
         }
         lines.push("");

package/package.json

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