context-doctor 0.22.0 → 0.23.0

package/README.md

@@ -21,22 +21,9 @@ Built and maintained by [gAI Ventures](https://gai.ventures).
 npx context-doctor savings
 ```
 
-```
-What context-doctor finds in your Claude Code sessions (last 30 days, 29 sessions)
-────────────────────────────────────────────────────────────────
-Input you were billed for            $6,021   from the usage your transcripts record
-
-1. Compact when you come back        $2,492   199 returns to a session over 150k tokens
-   after the prompt cache expired. Running /compact then, net of the compaction
-   itself, would have saved this. The every-prompt hook points these moments out;
-   it works in every Claude Code surface, the desktop app included.
-
-2. Autopilot                            n/a   all 29 sessions ran in the desktop app, which
-   sets its own API address, so the autopilot proxy cannot sit in front of it.
-   (Had they run in the terminal or an IDE: $788, 12.9%.)
-```
+<img src="https://raw.githubusercontent.com/KushalP1/context-doctor/main/assets/savings.svg" alt="npx context-doctor savings: input billed, what /compact at cold resumes and autopilot would have saved" width="640">
 
-That is the author's machine: every session there runs in the desktop app, so the first line is the one that applies. Yours is computed the same way, from your own transcripts: every session replayed request by request through the shipped code, against what you were actually billed.
+That is the author's machine: every session there runs in the desktop app, so the first line is the one that applies. Yours is computed the same way, from your own transcripts: every session replayed request by request through the shipped code, against what you were actually billed. `context-doctor savings --share` prints a few lines with totals only (no project names or paths) if you want to post your number.
 
 **Then install it**, whichever way suits you:
 

package/dist/autoclear.js

@@ -54,7 +54,9 @@ export const CLEARABLE_TOOLS = new Set([
 const IMAGE_TOKENS = 1600;
 const HOUR = 3_600_000;
 export function clearedNote(tokens) {
-    return `[context-doctor: old tool output cleared to keep context lean (~${tokens} tokens). Run the tool again if you need it.]`;
+    // Not "run it again": a cleared Bash result may come from a command with
+    // side effects (a push, a delete), and repeating that would be wrong.
+    return `[context-doctor: old tool output cleared to keep context lean (~${tokens} tokens). The call above shows what ran; repeat it only if it is read-only, otherwise ask the user.]`;
 }
 function resultTokens(content, model) {
     if (typeof content === "string")

package/dist/cli.js

@@ -22,7 +22,7 @@ import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
 import { measureTokenizer, renderTokenizer } from "./tokenizer-measure.js";
 import { autopilotOff, autopilotOn, autopilotPause, autopilotPaths, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
-import { estimateSavings, renderSavings } from "./savings.js";
+import { estimateSavings, renderSavings, renderShare } from "./savings.js";
 import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
@@ -51,9 +51,11 @@ Usage:
                                                 Claude Code, and Cursor automatically
   context-doctor uninstall                      Undo install
   context-doctor --version                      Print the installed version
-  context-doctor savings [--days n]              What autopilot saves (or would have) on YOUR recent
-                                                Claude Code sessions: replayed, priced as billed.
-                                                Also what a bare \`context-doctor\` shows
+  context-doctor savings [--days n] [--share [--copy]]
+                                                What your recent Claude Code sessions cost, and what
+                                                /compact at cold resumes and autopilot would save,
+                                                replayed and priced as billed. --share: totals only,
+                                                to paste. Also what a bare \`context-doctor\` shows
   context-doctor autopilot on|off|pause|resume|status
                                                 Every new Claude Code session goes through the
                                                 local proxy, which clears stale tool output only
@@ -178,19 +180,19 @@ function parseArgs(argv) {
                 args.strategies.push(argv[++i]);
                 break;
             case "--keep-recent":
-                args.keepRecent = Number(argv[++i]);
+                args.keepRecent = numArg("--keep-recent", argv[++i], { min: 0, integer: true });
                 break;
             case "--max-tool-tokens":
-                args.maxToolTokens = Number(argv[++i]);
+                args.maxToolTokens = numArg("--max-tool-tokens", argv[++i], { min: 1, integer: true });
                 break;
             case "--port":
-                args.port = Number(argv[++i]);
+                args.port = numArg("--port", argv[++i], { min: 0, max: 65535, integer: true });
                 break;
             case "--interval-ms":
-                args.intervalMs = Number(argv[++i]);
+                args.intervalMs = numArg("--interval-ms", argv[++i], { min: 100, integer: true });
                 break;
             case "--limit":
-                args.limit = Number(argv[++i]);
+                args.limit = numArg("--limit", argv[++i], { min: 1, integer: true });
                 break;
             case "--task":
                 args.task = argv[++i];
@@ -202,7 +204,7 @@ function parseArgs(argv) {
                 args.existing = argv[++i];
                 break;
             case "--budget":
-                args.budgetUsd = Number(argv[++i]);
+                args.budgetUsd = numArg("--budget", argv[++i], { min: 0 });
                 break;
             case "--dry-run":
                 args.dryRun = true;
@@ -210,6 +212,9 @@ function parseArgs(argv) {
             case "--copy":
                 args.copy = true;
                 break;
+            case "--share":
+                args.share = true;
+                break;
             case "--allow-dirty":
                 args.allowDirty = true;
                 break;
@@ -223,7 +228,7 @@ function parseArgs(argv) {
                 args.token = argv[++i];
                 break;
             case "--days":
-                args.days = Number(argv[++i]);
+                args.days = numArg("--days", argv[++i], { min: 1 });
                 break;
             case "--autopilot":
                 args.autopilot = true;
@@ -289,6 +294,21 @@ function packageVersion() {
         return "unknown";
     }
 }
+/**
+ * A numeric flag's value, or exit 1 with a message naming the flag. Number()
+ * alone turned `--days abc` into "the last NaN days" and a bad --port into a
+ * random port.
+ */
+function numArg(flag, raw, { min, max, integer } = {}) {
+    const n = Number(raw);
+    const ok = raw !== undefined && raw.trim() !== "" && Number.isFinite(n) && (!integer || Number.isInteger(n)) && (min === undefined || n >= min) && (max === undefined || n <= max);
+    if (!ok) {
+        const range = min !== undefined && max !== undefined ? ` between ${min} and ${max}` : min !== undefined ? ` of at least ${min}` : "";
+        console.error(`${flag} needs ${integer ? "a whole number" : "a number"}${range}; got ${raw === undefined ? "nothing" : JSON.stringify(raw)}.`);
+        process.exit(1);
+    }
+    return n;
+}
 /** Any Claude Code transcript on this machine? One directory listing, no parsing. */
 function hasClaudeSessions() {
     try {
@@ -504,6 +524,12 @@ async function main() {
         const on = existsSync(autopilotPaths().config);
         if (args.json)
             console.log(JSON.stringify(report, null, 2));
+        else if (args.share) {
+            const text = renderShare(report);
+            console.log(text);
+            if (args.copy)
+                console.log(copyToClipboard(text) ? "\n(copied to the clipboard)" : "\n(no clipboard tool found; copy the lines above)");
+        }
         else {
             console.log(renderSavings(report, on));
             if (!args.command)
@@ -582,6 +608,11 @@ async function main() {
         return; // server keeps the process alive
     }
     if (!args.command || !args.file) {
+        const known = ["analyze", "optimize"];
+        if (args.command && !known.includes(args.command)) {
+            console.error(`Unknown command "${args.command}". Run \`context-doctor --help\` for the list.`);
+            process.exit(1);
+        }
         console.log(HELP);
         process.exit(args.command ? 1 : 0);
     }

package/dist/coldresume.js

@@ -60,6 +60,12 @@ export function detectColdResume(path, now = Date.now(), idleMs = COLD_IDLE_MS,
             catch {
                 continue;
             }
+            // Compacted since the last reply: the old usage no longer describes the
+            // context, and there is nothing large left to warn about.
+            if (e?.type === "system" && e.subtype === "compact_boundary")
+                return undefined;
+            if (e?.isCompactSummary)
+                return undefined;
             if (e?.type !== "assistant" || e.isSidechain)
                 continue;
             const u = e.message?.usage;

package/dist/mcp.js

@@ -49,7 +49,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.22.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.23.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~120 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({

package/dist/proxy.d.ts

@@ -47,7 +47,7 @@ export interface ProxyOptions extends OptimizeOptions {
     openaiUpstream?: string;
 }
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export declare const PROXY_VERSION = "0.22.0";
+export declare const PROXY_VERSION = "0.23.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.22.0";
+export const PROXY_VERSION = "0.23.0";
 /** Connection-level headers that must not be forwarded. */
 const SKIP_REQUEST_HEADERS = new Set(["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
 const SKIP_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);

package/dist/savings.d.ts

@@ -59,3 +59,8 @@ export interface SavingsReport {
 export declare function replaySession(path: string, options?: AutoClearOptions, since?: number): SessionSavings | undefined;
 export declare function estimateSavings(days?: number, options?: AutoClearOptions, paths?: string[], onProgress?: (done: number, total: number) => void): SavingsReport;
 export declare function renderSavings(r: SavingsReport, autopilotOn?: boolean): string;
+/**
+ * `savings --share`: a few lines people can paste or screenshot. Totals only:
+ * no project names, paths or session ids, so sharing it leaks nothing.
+ */
+export declare function renderShare(r: SavingsReport): string;

package/dist/savings.js

@@ -208,31 +208,56 @@ export function renderSavings(r, autopilotOn = false) {
     }
     const n = r.sessions.length;
     const allDesktop = r.unreachableSessions === n;
-    lines.push(`What context-doctor finds in your Claude Code sessions (last ${r.days} days, ${n} session${n === 1 ? "" : "s"})`);
-    lines.push("─".repeat(64));
-    lines.push(`Input you were billed for        ${usd(r.billedUsd).padStart(10)}   from the usage your transcripts record`);
+    const pct = (x) => (r.billedUsd > 0 ? ` (${Math.round((x / r.billedUsd) * 100)}%)` : "");
+    // Kept within 80 columns: this is most people's first screen of the tool.
+    lines.push("What context-doctor finds in your Claude Code sessions");
+    lines.push(`Last ${r.days} days, ${n} session${n === 1 ? "" : "s"}, priced at list prices`);
+    lines.push("─".repeat(60));
+    lines.push(`Input you were billed for         ${usd(r.billedUsd).padStart(9)}   from your transcripts' usage`);
     lines.push("");
-    lines.push(`1. Compact when you come back    ${usd(Math.max(0, r.coldResumeNetUsd)).padStart(10)}   ${r.coldResumes} return${r.coldResumes === 1 ? "" : "s"} to a session over 150k tokens`);
-    lines.push("   after the prompt cache expired. Running /compact then, net of the compaction");
-    lines.push("   itself, would have saved this. The every-prompt hook points these moments out;");
-    lines.push("   it works in every Claude Code surface, the desktop app included.");
+    lines.push(`1. Compact when you come back     ${usd(Math.max(0, r.coldResumeNetUsd)).padStart(9)}${pct(Math.max(0, r.coldResumeNetUsd))}`);
+    lines.push(`   ${r.coldResumes} return${r.coldResumes === 1 ? "" : "s"} to a session over 150k tokens after the prompt cache`);
+    lines.push("   expired. Running /compact then, net of the compaction itself, would");
+    lines.push("   have saved this. The every-prompt hook points these moments out, in");
+    lines.push("   every Claude Code surface, the desktop app included.");
     lines.push("");
     if (allDesktop) {
-        lines.push(`2. Autopilot                     ${"n/a".padStart(10)}   all ${n} sessions ran in the desktop app, which`);
-        lines.push("   sets its own API address, so the autopilot proxy cannot sit in front of it.");
-        lines.push(`   (Had they run in the terminal or an IDE: ${usd(r.savedUsd)}, ${(r.savedPct * 100).toFixed(1)}%.)`);
+        lines.push(`2. Autopilot                      ${"n/a".padStart(9)}`);
+        lines.push(`   All ${n} sessions ran in the desktop app, which sets its own API`);
+        lines.push("   address, so the autopilot proxy cannot sit in front of them. In a");
+        lines.push(`   terminal or an IDE they would have saved ${usd(r.savedUsd)} (${(r.savedPct * 100).toFixed(1)}%).`);
     }
     else {
-        lines.push(`2. Autopilot                     ${usd(r.reachableUsd).padStart(10)}   stale tool output cleared only when the cache`);
-        lines.push(`   is cold (never costs more; ${r.worse} session${r.worse === 1 ? "" : "s"} made more expensive), ${tokens(r.savedTokens)} tokens not sent.`);
+        lines.push(`2. Autopilot                      ${usd(r.reachableUsd).padStart(9)}${pct(r.reachableUsd)}`);
+        lines.push("   Stale tool output cleared only when the cache is cold, so it never");
+        lines.push(`   costs more (${r.worse} session${r.worse === 1 ? "" : "s"} made more expensive); ${tokens(r.savedTokens)} tokens not sent.`);
         if (r.unreachableSessions > 0)
-            lines.push(`   Counts terminal and IDE sessions only; ${r.unreachableSessions} desktop-app session${r.unreachableSessions === 1 ? "" : "s"} excluded (not reachable).`);
+            lines.push(`   Terminal and IDE sessions only; ${r.unreachableSessions} desktop-app session${r.unreachableSessions === 1 ? "" : "s"} not reachable.`);
         if (!autopilotOn)
             lines.push("   Turn it on:  context-doctor autopilot on");
     }
     lines.push("");
-    lines.push("Replayed request by request through the shipped code and priced as the prompt");
-    lines.push("cache bills, at list prices. On a subscription the same tokens come out of your");
-    lines.push("usage limit instead.");
+    lines.push("Replayed request by request through the shipped code and priced as the");
+    lines.push("prompt cache bills. On a subscription the same tokens come out of your");
+    lines.push("usage limit instead. Share yours: context-doctor savings --share");
+    return lines.join("\n");
+}
+/**
+ * `savings --share`: a few lines people can paste or screenshot. Totals only:
+ * no project names, paths or session ids, so sharing it leaks nothing.
+ */
+export function renderShare(r) {
+    if (r.sessions.length === 0)
+        return "context-doctor found no Claude Code sessions to measure yet.";
+    const lines = [
+        `My Claude Code input, last ${r.days} days: ${usd(r.billedUsd)} at list price (${r.sessions.length} sessions).`,
+    ];
+    if (r.coldResumeNetUsd > 0) {
+        lines.push(`Running /compact when I came back to a big session after the cache expired would have saved ${usd(r.coldResumeNetUsd)} (${Math.round((r.coldResumeNetUsd / r.billedUsd) * 100)}%, ${r.coldResumes} times).`);
+    }
+    if (r.reachableUsd > 0) {
+        lines.push(`Clearing stale tool output only when the cache is cold would have cut another ${usd(r.reachableUsd)}, with no session made more expensive.`);
+    }
+    lines.push("Measured from my own transcripts with context-doctor: npx context-doctor savings");
     return lines.join("\n");
 }

package/dist/sketch.js

@@ -128,7 +128,7 @@ export function profileSketch(sketch) {
             severity: totalTokens > 100_000 ? "high" : "warn",
             estSavings: Math.max(0, totalTokens - afterHandoff),
             message: `${turns} turns: every new message re-reads ~${formatTokens(totalTokens)}.`,
-            action: `Offer a handoff: write a ≤${HANDOFF_SUMMARY_TOKENS}-token summary (decisions, current state, open items, key identifiers) for the user to start a new chat with. A fresh chat re-reads ~${formatTokens(afterHandoff)} instead.`,
+            action: `Offer a handoff: write a ≤${HANDOFF_SUMMARY_TOKENS}-token summary (decisions, current state, open items, key identifiers) for the user to start a new chat with. A fresh chat re-reads ~${formatTokens(afterHandoff)} of conversation instead, plus the app's own system prompt, which every chat carries.`,
         });
     }
     const contextWindow = contextWindowFor(sketch.model);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "See what your Claude Code sessions cost and cut it: offers /compact when you return to a large session after the cache expired (every surface, desktop app included), and a cache-safe autopilot for terminal, IDE and API traffic. Token profiler, hooks, MCP tools and a Claude Code plugin.",
   "keywords": [
     "agent",