context-doctor 0.20.0 → 0.21.0

package/README.md

@@ -15,15 +15,41 @@ Built and maintained by [gAI Ventures](https://gai.ventures).
 
 ## Quick start
 
+**See what it would save you first** (no install, reads your local Claude Code history):
+
+```bash
+npx context-doctor savings
+```
+
+```
+What autopilot would have saved you (last 30 days, 53 Claude Code sessions)
+────────────────────────────────────────────────────────
+Input you were billed for           $11,205   (from the usage your transcripts record)
+Autopilot would have cut             $1,396   12.5%, 1.2B tokens not sent
+Sessions made more expensive              0
+Biggest win                            $503   tech-Whatsit (31% of that session)
+```
+
+That is the author's machine. Yours is computed the same way: every recent session replayed request by request through the shipped autopilot code, against what your transcripts show you were actually billed.
+
+**Then install it**, whichever way suits you:
+
 ```bash
+# Everything, every app it finds (Claude Code, Cursor, Codex, Claude Desktop)
 npm install -g context-doctor
-context-doctor install          # hooks, MCP server and skill in every AI app it finds
+context-doctor install
 context-doctor autopilot on     # every new Claude Code session keeps its context lean
 ```
 
-Then start a new Claude Code session and work as usual. `context-doctor autopilot status` shows what it did; `context-doctor doctor` checks the whole setup. Everything is reversible: `context-doctor autopilot off`, `context-doctor uninstall`.
+```text
+# Or as a Claude Code plugin, from inside Claude Code
+/plugin marketplace add KushalP1/context-doctor
+/plugin install context-doctor@context-doctor
+```
+
+The plugin brings the every-prompt check, the MCP tools, and `/context-doctor:savings`, `/context-doctor:checkup` and `/context-doctor:autopilot`. It needs no npm step: the MCP server ships as one self-contained file, so it also works on Claude Code versions that do not install plugin dependencies.
 
-Just want a look first? `npx context-doctor session` profiles your latest Claude Code or Codex session in place, no install.
+`context-doctor autopilot status` shows what autopilot did; `context-doctor doctor` checks the whole setup. Everything is reversible: `context-doctor autopilot off`, `context-doctor uninstall`, or `/plugin uninstall`.
 
 ```
 Where the tokens go
@@ -62,7 +88,7 @@ What is not counted here: the proxy's full optimizer for your own API apps, the
 
 | Where you work | Automatic, every request | What you get on top |
 |---|---|---|
-| **Claude Code** (terminal, VS Code, JetBrains, desktop app's Code tab) | **Autopilot** clears stale tool output (cold cache only, never more expensive). **Hook** on every prompt warns the model with the real context size and its largest waste | Status bar context meter, `/context-doctor` skill, `session`, `watch`, `report`, dashboard |
+| **Claude Code** (terminal, VS Code, JetBrains, desktop app's Code tab) | **Autopilot** clears stale tool output (cold cache only, never more expensive). **Hook** on every prompt warns the model with the real context size and its largest waste | Install via npm or as a **plugin** (`/plugin marketplace add KushalP1/context-doctor`). Status bar context meter, `/context-doctor:savings`, `session`, `watch`, `report`, dashboard |
 | **Cursor** (agent) | Cursor runs Claude Code's hooks, so the same every-prompt check fires inside Cursor | MCP tools, editor status bar extension, `cursor` profiler. With your own OpenAI key, autopilot too via a tokened tunnel ([how](#putting-the-proxy-on-a-public-url-cursor-with-your-own-openai-key-remote-apps)) |
 | **Codex** (ChatGPT app's Codex tab, IDE extension, CLI) | Every-prompt hook with the API's own token counts | MCP tools, skill, `session` reads Codex rollouts. On an API key, autopilot too (`OPENAI_BASE_URL`) |
 | **Your own apps on the Anthropic or OpenAI API** | Autopilot on `/v1/messages`, `/v1/chat/completions` and `/v1/responses` (`ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL`), or the full optimizing proxy | Exact usage and cache hit rates in `/stats`, prompt-cache placement advice |
@@ -75,6 +101,8 @@ Not claimed, because no process on your machine sends those requests: trimming i
 ## What's new
 
 - **0.20 Autopilot**: stale tool output cleared from every Claude Code request, only when the prompt cache is cold, so it cannot cost more (measured: 9.8% less input cost, ~$1,080 a month on the author's usage, no session worse); runs as a login service on macOS, Linux and Windows; now also for GPT via OpenAI's Chat Completions and Responses APIs.
+- **0.21 See it before you install it**: `npx context-doctor savings` replays your own recent sessions through autopilot and shows what it would have saved, against what you were actually billed. Install as a **Claude Code plugin** from inside Claude Code. Ready for the official **MCP Registry** (`io.github.KushalP1/context-doctor`), which every release now publishes to; any MCP client can launch it as `npx -y context-doctor mcp`.
+- **0.20.1 Releases that finish themselves**: one tag publishes to npm and creates a GitHub release with the Claude Desktop bundle (signed when a certificate is configured); the editor extension is ready for the VS Code Marketplace and Open VSX.
 - **0.19 Measured Claude tokenizer**: estimates were 40% low for Claude; fixed from the API's own counts, with a per-model check in `accuracy`.
 - **0.18** `proxy --token` for putting the proxy on a public URL safely. **0.17** Claude Desktop: a `profile_context` the model can afford to call from chat, `.mcpb` bundle, standing preferences for web and mobile. **0.16** Codex. **0.15** Cursor.
 
@@ -137,6 +165,8 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | Command | What it does |
 |---|---|
 | `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor/Codex, the Agent Skill, the every-prompt hook |
+| `context-doctor savings [--days n]` | What autopilot saves, or would have saved, on your own recent Claude Code sessions: replayed through the shipped code, against your actual billed usage. A bare `context-doctor` in a terminal shows the same |
+| `context-doctor mcp [--http]` | The MCP server as a subcommand, for clients and registries that launch `npx -y context-doctor mcp` |
 | `context-doctor autopilot on\|off\|pause\|resume\|status` | Every new Claude Code session goes through the local proxy, which clears stale tool output only when the prompt cache is cold: measured 9.8% less input cost, no session worse |
 | `context-doctor instructions [--copy]` | The ~180-token standing rules (~120 on GPT) for claude.ai / ChatGPT preferences, for web and phones where no server runs |
 | `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates. `--fail-over-budget` exits 1 on a breach, for CI |
@@ -580,14 +610,27 @@ Contributions welcome — this project is small on purpose. Open an issue before
 
 ## Releasing (maintainers)
 
+**One-time setup.** Each row switches on one channel; any that is missing is skipped with a notice, never a failed run. Secrets go in the repo's Settings > Secrets and variables > Actions:
+
+| Secret | Turns on | Where to get it |
+|---|---|---|
+| *(no secret: npm trusted publishing)* | `npm publish` on every `v*` tag, with provenance | npmjs.com > package `context-doctor` > Settings > Trusted Publisher > GitHub Actions: owner `KushalP1`, repository `context-doctor`, workflow `publish.yml`. npm is phasing out publish tokens that bypass 2FA; an `NPM_TOKEN` secret still works as a fallback |
+| `MCPB_CERT`, `MCPB_KEY` (+ `MCPB_INTERMEDIATE`) | A signed Claude Desktop bundle, no install warning | A code-signing certificate from a trusted CA; paste the PEM text. `mcpb verify` must pass in CI or the release stops |
+| `VSCE_PAT` | VS Code Marketplace on `vscode-v*` tags | Azure DevOps PAT, scope Marketplace > Manage, for the `gai-ventures` publisher |
+| `OVSX_PAT` | Open VSX (where Cursor installs from) | open-vsx.org > Settings > Access Tokens |
+
+**Each release:**
+
 ```bash
-npm version patch        # or minor/major — bumps package.json + git tag
-npm test                 # 131 tests must pass; CI runs the same on 3 OSes x Node 20/22/24
-npm publish              # prompts for the npm 2FA code
-git push --follow-tags
-npm run build:mcpb       # context-doctor-<version>.mcpb for Claude Desktop; attach it to the GitHub release
+npm version minor        # or patch/major: bumps package.json and tags vX.Y.Z
+npm test                 # the full suite; CI runs it on 3 OSes x Node 20/22/24
+git push --follow-tags   # npm publish + GitHub release with the .mcpb attached
 ```
 
+For the editor extension: bump `vscode/package.json`, add a `vscode/CHANGELOG.md` entry, then `git tag vscode-vX.Y.Z && git push --tags`. The `.vsix` is attached to a GitHub release either way.
+
+Locally, `npm run build:mcpb` builds the bundle (`MCPB_SELF_SIGNED=1` exercises the signing path with a throwaway certificate; Desktop still warns for those).
+
 **What the npm download number measures.** `install` writes `npx -y context-doctor-mcp` into MCP configs, and npx re-fetches the tarball whenever a new version exists. So every release is downloaded once by every active install within about a day, and the daily count is almost entirely those refreshes: on this package, release days run ~170 downloads and non-release days ~27. Read it as "size of the active installed base × number of releases", not as new users — a quiet week with no releases will look like a decline while nothing has changed. Two corollaries: the release-day figure is a live count of machines running context-doctor, and a broken release reaches all of them automatically, which is why `prepublishOnly` runs the full test suite. npm's stats also lag by several days and occasionally record a day as zero; a zero on a release day is a gap in their pipeline, not in usage.
 
 Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doctor`** on a package that clearly exists, the real cause is an **expired npm login token** — npm reports unauthenticated publishes as a 404, not a 401. Check with `npm whoami`; if that errors, run `npm login` and publish again.

package/dist/autopilot.js

@@ -179,8 +179,12 @@ async function waitHealthy(port, ms) {
     }
 }
 function readConfig(paths) {
+    // readJson returns {} for a missing file; only a file with a port is a config.
+    if (!existsSync(paths.config))
+        return undefined;
     try {
-        return readJson(paths.config);
+        const cfg = readJson(paths.config);
+        return typeof cfg.port === "number" && cfg.port > 0 ? cfg : undefined;
     }
     catch {
         return undefined;
@@ -192,11 +196,11 @@ export function currentCli() {
 export async function autopilotOn(port = DEFAULT_AUTOPILOT_PORT, paths = autopilotPaths()) {
     const lines = [];
     const cli = currentCli();
-    if (isEphemeralPath(cli)) {
+    if (isEphemeralPath(cli) || /[\\/]\.claude[\\/]plugins[\\/]/.test(cli)) {
         return {
             ok: false,
             lines: [
-                "✗ Running from the npx cache, which npm deletes at will; a background service cannot point there.",
+                "✗ Running from the npx cache or a Claude Code plugin copy, which are replaced or deleted on update; a background service cannot point there.",
                 "  Install it once, then re-run:  npm install -g context-doctor && context-doctor autopilot on",
             ],
         };
@@ -318,7 +322,7 @@ export async function ensureProxyUp(paths = autopilotPaths()) {
         return;
     if ((await health(cfg.port, 300)).ok)
         return;
-    if (!existsSync(cfg.node) || !existsSync(cfg.cli))
+    if (typeof cfg.node !== "string" || typeof cfg.cli !== "string" || !existsSync(cfg.node) || !existsSync(cfg.cli))
         return;
     startDetached(serviceCommand(cfg.node, cfg.cli, cfg.port, paths), paths.log);
     await waitHealthy(cfg.port, 2500);

package/dist/cli.js

@@ -21,7 +21,8 @@ import { listSessions, parseSessionFile } from "./session.js";
 import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
 import { measureTokenizer, renderTokenizer } from "./tokenizer-measure.js";
-import { autopilotOff, autopilotOn, autopilotPause, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
+import { autopilotOff, autopilotOn, autopilotPause, autopilotPaths, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
+import { estimateSavings, renderSavings } from "./savings.js";
 import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
@@ -49,10 +50,15 @@ Usage:
   context-doctor install                        Wire the MCP server + skill into Claude Desktop,
                                                 Claude Code, and Cursor automatically
   context-doctor uninstall                      Undo install
+  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 autopilot on|off|pause|resume|status
                                                 Every new Claude Code session goes through the
                                                 local proxy, which clears stale tool output only
                                                 when the prompt cache is cold (never costs more)
+  context-doctor mcp [--http]                   The MCP server (same as context-doctor-mcp), for clients
+                                                that launch \`npx -y context-doctor mcp\`
   context-doctor instructions [--copy]          Standing context rules to paste into claude.ai or
                                                 ChatGPT preferences (works on web and mobile too)
   context-doctor session [file]                 Profile a Claude Code session transcript or a
@@ -211,6 +217,9 @@ function parseArgs(argv) {
             case "--token":
                 args.token = argv[++i];
                 break;
+            case "--days":
+                args.days = Number(argv[++i]);
+                break;
             case "--autopilot":
                 args.autopilot = true;
                 break;
@@ -266,6 +275,15 @@ function readInput(file) {
         return readFileSync(0, "utf8");
     return readFileSync(file, "utf8");
 }
+/** Any Claude Code transcript on this machine? One directory listing, no parsing. */
+function hasClaudeSessions() {
+    try {
+        return listSessions(1).some((s) => s.path.includes(".claude"));
+    }
+    catch {
+        return false;
+    }
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.command === "hook") {
@@ -459,6 +477,35 @@ async function main() {
             process.exitCode = 1;
         return;
     }
+    if (args.command === "savings" || (!args.command && process.stdout.isTTY && hasClaudeSessions())) {
+        // A bare `context-doctor` in a terminal, with Claude Code history on the
+        // machine, answers the question people install this for: what would it
+        // save me? Scripts and pipes still get the help text.
+        const progress = process.stderr.isTTY
+            ? (done, total) => process.stderr.write(`\rReplaying your Claude Code sessions through autopilot… ${done}/${total}`)
+            : undefined;
+        const report = estimateSavings(args.days ?? 30, {}, undefined, progress);
+        if (progress)
+            process.stderr.write("\r\x1b[K");
+        const on = existsSync(autopilotPaths().config);
+        if (args.json)
+            console.log(JSON.stringify(report, null, 2));
+        else {
+            console.log(renderSavings(report, on));
+            if (!args.command)
+                console.log("\nAll commands: context-doctor --help");
+        }
+        return;
+    }
+    if (args.command === "mcp") {
+        // `context-doctor mcp [--http ...]` is the MCP server, the same program as
+        // the context-doctor-mcp binary. Registries and clients that launch a
+        // package with `npx -y context-doctor <args>` can only reach the package's
+        // main binary, so the server has to be a subcommand of it too.
+        process.argv.splice(2, 1);
+        await import("./mcp.js");
+        return;
+    }
     if (args.command === "autopilot") {
         const sub = args.file ?? "status";
         const port = args.port ?? DEFAULT_AUTOPILOT_PORT;

package/dist/hook.js

@@ -12,6 +12,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { recordLedger, statePath } from "./ledger.js";
 import { parseConversation } from "./parse.js";
@@ -119,6 +120,15 @@ async function readStdin() {
         chunks.push(chunk);
     return Buffer.concat(chunks).toString("utf8");
 }
+function settingsHasOurHook() {
+    try {
+        const hooks = JSON.parse(readFileSync(join(homedir(), ".claude", "settings.json"), "utf8"))?.hooks?.UserPromptSubmit;
+        return JSON.stringify(hooks ?? "").includes("context-doctor");
+    }
+    catch {
+        return false;
+    }
+}
 export async function runHook() {
     // A hook must never break the user's prompt: any failure exits silently.
     try {
@@ -126,6 +136,12 @@ export async function runHook() {
         // so if the proxy died, start it now. One existsSync when autopilot is
         // off; a ~1ms localhost health check when it is on and healthy.
         const heal = ensureProxyUp().catch(() => undefined);
+        // Installed both ways (plugin and `context-doctor install`)? The plugin
+        // copy stays silent so the model is told once, not twice.
+        if (process.env.CLAUDE_PLUGIN_ROOT && settingsHasOurHook()) {
+            await heal;
+            return;
+        }
         const input = JSON.parse(await readStdin());
         await heal;
         const transcriptPath = input.transcript_path;

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export * from "./preferences.js";
 export * from "./tokenizer-measure.js";
 export * from "./autoclear.js";
 export * from "./autopilot.js";
+export * from "./savings.js";

package/dist/index.js

@@ -18,3 +18,4 @@ export * from "./preferences.js";
 export * from "./tokenizer-measure.js";
 export * from "./autoclear.js";
 export * from "./autopilot.js";
+export * from "./savings.js";

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.20.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.21.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.20.0";
+export declare const PROXY_VERSION = "0.21.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.20.0";
+export const PROXY_VERSION = "0.21.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

@@ -0,0 +1,42 @@
+/**
+ * `context-doctor savings`: what autopilot would have saved on YOUR recent
+ * Claude Code sessions, measured, not modelled.
+ *
+ * Each session is replayed request by request, twice: as it was sent, and as
+ * autopilot (autoclear.ts, the shipped class) would have sent it. Both arms
+ * are priced the way the prompt cache bills (reads 0.1x, writes 1.25x, a
+ * cold cache after an idle gap longer than the request's own TTL). The
+ * difference between the arms is the saving. The baseline shown to the user
+ * is not an estimate: it is the input the sessions were actually billed for,
+ * read from the usage every transcript records.
+ */
+import { type AutoClearOptions } from "./autoclear.js";
+export interface SessionSavings {
+    path: string;
+    project: string;
+    model?: string;
+    requests: number;
+    /** Cache-weighted input actually billed (usage in the transcript), in base-input-token units. */
+    billedWeighted: number;
+    billedUsd: number;
+    /** Replay difference, in the same units. */
+    savedWeighted: number;
+    savedUsd: number;
+    /** Raw input tokens autopilot would not have sent. */
+    savedTokens: number;
+    savedPct: number;
+}
+export interface SavingsReport {
+    days: number;
+    sessions: SessionSavings[];
+    billedUsd: number;
+    savedUsd: number;
+    savedTokens: number;
+    billedTokens: number;
+    savedPct: number;
+    worse: number;
+}
+/** Replay one Claude Code transcript. Undefined when it holds too few requests to mean anything. */
+export declare function replaySession(path: string, options?: AutoClearOptions): 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;

package/dist/savings.js

@@ -0,0 +1,198 @@
+/**
+ * `context-doctor savings`: what autopilot would have saved on YOUR recent
+ * Claude Code sessions, measured, not modelled.
+ *
+ * Each session is replayed request by request, twice: as it was sent, and as
+ * autopilot (autoclear.ts, the shipped class) would have sent it. Both arms
+ * are priced the way the prompt cache bills (reads 0.1x, writes 1.25x, a
+ * cold cache after an idle gap longer than the request's own TTL). The
+ * difference between the arms is the saving. The baseline shown to the user
+ * is not an estimate: it is the input the sessions were actually billed for,
+ * read from the usage every transcript records.
+ */
+import { basename, dirname } from "node:path";
+import { AutoClearer } from "./autoclear.js";
+import { forEachLine, listSessions } from "./session.js";
+import { pricingFor } from "./pricing.js";
+import { estimateTokens, formatTokens } from "./tokens.js";
+/** System prompt and tool schemas: sent on every request, identical in both arms. */
+const FIXED_TOKENS = 54_000;
+const CLAUDE_CODE_TTL_MS = 3_600_000;
+/** One arm of the replay: the history as sent, priced incrementally. */
+function arm(model, clearer) {
+    const msgs = [];
+    const tok = [];
+    let total = 0, prevLen = 0, weighted = 0, raw = 0;
+    const size = (m) => estimateTokens(JSON.stringify(m), model);
+    return {
+        push(m) { msgs.push(structuredClone(m)); const k = size(m); tok.push(k); total += k; },
+        extend(blocks) {
+            const i = msgs.length - 1;
+            msgs[i].content.push(...structuredClone(blocks));
+            total -= tok[i];
+            tok[i] = size(msgs[i]);
+            total += tok[i];
+        },
+        request(now, cold) {
+            let first = -1;
+            if (clearer) {
+                const body = { model, messages: msgs, system: [{ type: "text", text: "", cache_control: { type: "ephemeral", ttl: "1h" } }] };
+                first = clearer.apply(body, now).firstChanged;
+            }
+            if (first >= 0)
+                for (let i = first; i < msgs.length; i++) {
+                    total -= tok[i];
+                    tok[i] = size(msgs[i]);
+                    total += tok[i];
+                }
+            const k = cold ? 0 : Math.min(prevLen, first >= 0 ? first : prevLen);
+            let read = 0;
+            for (let i = 0; i < k; i++)
+                read += tok[i];
+            const write = total - read;
+            weighted += (cold ? FIXED_TOKENS * 1.25 : FIXED_TOKENS * 0.1) + read * 0.1 + write * 1.25;
+            raw += FIXED_TOKENS + total;
+            prevLen = msgs.length;
+        },
+        get weighted() { return weighted; },
+        get raw() { return raw; },
+    };
+}
+/** Replay one Claude Code transcript. Undefined when it holds too few requests to mean anything. */
+export function replaySession(path, options = {}) {
+    let model;
+    let base = arm(undefined, null), auto = arm(undefined, new AutoClearer(options));
+    let baseW = 0, autoW = 0, baseRaw = 0, autoRaw = 0;
+    let billed = 0, billedRaw = 0, requests = 0, lastId, lastTs = null;
+    const flush = () => { baseW += base.weighted; autoW += auto.weighted; baseRaw += base.raw; autoRaw += auto.raw; };
+    forEachLine(path, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (e.type === "system" && e.subtype === "compact_boundary") {
+            // Compaction replaces the history in both arms alike: start fresh.
+            flush();
+            base = arm(model, null);
+            auto = arm(model, new AutoClearer(options));
+            return;
+        }
+        if (e.type === "assistant" && e.message) {
+            const m = e.message;
+            model = model ?? m.model;
+            const blocks = (Array.isArray(m.content) ? m.content : []).filter((b) => b?.type !== "thinking" && b?.type !== "redacted_thinking");
+            if (m.id !== lastId) {
+                lastId = m.id;
+                const u = m.usage ?? {};
+                const read = u.cache_read_input_tokens ?? 0, write = u.cache_creation_input_tokens ?? 0, fresh = u.input_tokens ?? 0;
+                if (read + write + fresh > 0) {
+                    billed += fresh + read * 0.1 + write * 1.25;
+                    billedRaw += fresh + read + write;
+                    requests++;
+                    const now = Date.parse(e.timestamp) || 0;
+                    const cold = lastTs === null || now - lastTs > CLAUDE_CODE_TTL_MS;
+                    base.request(now, cold);
+                    auto.request(now, cold);
+                    lastTs = now;
+                }
+                base.push({ role: "assistant", content: blocks });
+                auto.push({ role: "assistant", content: blocks });
+            }
+            else {
+                base.extend(blocks);
+                auto.extend(blocks);
+            }
+        }
+        else if (e.type === "user" && e.message) {
+            const c = e.message.content;
+            const msg = { role: "user", content: Array.isArray(c) ? c : [{ type: "text", text: String(c ?? "") }] };
+            base.push(msg);
+            auto.push(msg);
+        }
+    });
+    flush();
+    if (requests < 10 || billed <= 0)
+        return undefined;
+    // The replay decides the SHARE saved (both arms priced the same way); that
+    // share is applied to what was actually billed, so the dollars and tokens
+    // shown are fractions of the user's real usage, not of an estimate.
+    const perM = pricingFor(model)?.inputPerM ?? 0;
+    const pct = baseW > 0 ? (baseW - autoW) / baseW : 0;
+    const rawPct = baseRaw > 0 ? (baseRaw - autoRaw) / baseRaw : 0;
+    const dir = basename(dirname(path));
+    return {
+        path,
+        project: dir.replace(/^-Users-[^-]+-/, "").replace(/^-/, "") || dir,
+        model,
+        requests,
+        billedWeighted: billed,
+        billedUsd: (billed / 1e6) * perM,
+        savedWeighted: pct * billed,
+        savedUsd: ((pct * billed) / 1e6) * perM,
+        savedTokens: rawPct * billedRaw,
+        savedPct: pct,
+    };
+}
+export function estimateSavings(days = 30, options = {}, paths, onProgress) {
+    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 sessions = [];
+    for (const [i, p] of targets.entries()) {
+        onProgress?.(i, targets.length);
+        try {
+            const s = replaySession(p, options);
+            if (s)
+                sessions.push(s);
+        }
+        catch {
+            /* one unreadable transcript must not sink the report */
+        }
+    }
+    const sum = (k) => sessions.reduce((n, s) => n + s[k], 0);
+    const billedUsd = sum("billedUsd"), savedUsd = sum("savedUsd");
+    const billedW = sum("billedWeighted");
+    const savedPct = billedW > 0 ? sum("savedWeighted") / billedW : 0;
+    return {
+        days,
+        sessions: sessions.sort((a, b) => b.savedUsd - a.savedUsd),
+        billedUsd,
+        savedUsd,
+        savedTokens: sum("savedTokens"),
+        billedTokens: sessions.reduce((n, s) => n + s.billedWeighted, 0),
+        savedPct,
+        worse: sessions.filter((s) => s.savedPct < -1e-9).length,
+    };
+}
+const tokens = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(1)}B` : formatTokens(n));
+const usd = (n) => (n >= 100 ? `$${Math.round(n).toLocaleString("en-US")}` : `$${n.toFixed(2)}`);
+export function renderSavings(r, autopilotOn = false) {
+    const lines = [];
+    if (r.sessions.length === 0) {
+        lines.push(`No Claude Code sessions with 10+ requests in the last ${r.days} days to replay.`);
+        lines.push("Use Claude Code for a while, then run this again: `context-doctor savings`.");
+        return lines.join("\n");
+    }
+    const title = autopilotOn ? "What autopilot saves on your sessions" : "What autopilot would have saved you";
+    lines.push(`${title} (last ${r.days} days, ${r.sessions.length} Claude Code session${r.sessions.length === 1 ? "" : "s"})`);
+    lines.push("─".repeat(56));
+    lines.push(`Input you were billed for     ${usd(r.billedUsd).padStart(10)}   (from the usage your transcripts record)`);
+    lines.push(`Autopilot would have cut      ${usd(r.savedUsd).padStart(10)}   ${(r.savedPct * 100).toFixed(1)}%, ${tokens(r.savedTokens)} tokens not sent`);
+    lines.push(`Sessions made more expensive  ${String(r.worse).padStart(10)}`);
+    const best = r.sessions[0];
+    if (best && best.savedUsd > 0)
+        lines.push(`Biggest win                   ${usd(best.savedUsd).padStart(10)}   ${best.project} (${(best.savedPct * 100).toFixed(0)}% of that session)`);
+    lines.push("");
+    lines.push("Replayed request by request through the shipped autopilot code and priced as");
+    lines.push("the prompt cache bills. List prices; on a subscription the same tokens come");
+    lines.push("out of your usage limit instead.");
+    if (!autopilotOn) {
+        lines.push("");
+        lines.push("Turn it on for every new session:  context-doctor autopilot on");
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Keep AI coding sessions lean automatically: clears stale tool output from every Claude Code and GPT API request, only when it costs nothing extra (measured 9.8% less input, no session worse). Token profiler, hooks and MCP tools for Claude Code, Cursor, Codex and Claude Desktop.",
   "keywords": [
     "agent",
@@ -46,6 +46,7 @@
   "files": [
     "dist",
     "!dist/test",
+    "!dist/mcp.bundle.js",
     "skills",
     "README.md",
     "LICENSE"
@@ -54,11 +55,12 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
+    "build": "tsc && node scripts/bundle-mcp.mjs && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
     "prepublishOnly": "npm test",
     "dev": "tsc --watch",
     "test": "npm run build && node scripts/test.mjs",
-    "build:mcpb": "npm run build && node scripts/build-mcpb.mjs"
+    "build:mcpb": "npm run build && node scripts/build-mcpb.mjs",
+    "version": "node scripts/sync-versions.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -66,10 +68,12 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "esbuild": "^0.25.12",
     "typescript": "^5.5.0"
   },
   "homepage": "https://github.com/KushalP1/context-doctor#readme",
   "bugs": {
     "url": "https://github.com/KushalP1/context-doctor/issues"
-  }
+  },
+  "mcpName": "io.github.KushalP1/context-doctor"
 }