context-doctor 0.23.1 → 0.24.0

package/README.md

@@ -104,6 +104,7 @@ 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.24 A full audit, fixed**: the session parser now rebuilds API messages from Claude Code's one-row-per-block transcripts (it had split each reply into several messages, breaking tool pairing in exported conversations and inflating profiles); the proxy forwards every non-conversation endpoint and never re-encodes bodies it does not rewrite (model listing and file uploads failed or were corrupted through it); `report` and the dashboard no longer count compaction as tokens context-doctor saved, and MCP sketches no longer inflate them; `watch` follows plain conversation files; MCP inputs are bounded. 0.23: four dependency vulnerabilities patched, no false `/compact` alarm after compacting, `savings --share`.
 - **0.22 Honest about where each lever works, and a new one that works everywhere**: the every-prompt hook now offers `/compact` when you return to a large session after the cache expired (measured: ~$914 a month on the author's history), including in the desktop app. Found and fixed: autopilot cannot reach the desktop app's Code tab, and `doctor` now says so instead of reporting ✓; `savings` counted whole-file history as "last 30 days"; the hook quoted per-message cost at the uncached rate (10x too high). `--version` added.
 - **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.
@@ -169,7 +170,7 @@ 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 savings [--days n] [--share [--copy]]` | What your recent Claude Code sessions cost, and what `/compact` at cold resumes and autopilot would save, replayed through the shipped code against your actual billed usage. `--share` prints totals only (no project names or paths) to post. 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 |
@@ -183,7 +184,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor cursor [--list]` | Profile a chat from Cursor's local history (both storage formats) |
 | `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 watch [file]` | Live monitor of a growing session transcript or agent trace (Claude Code / Codex JSONL, or a plain OpenAI/Anthropic conversation JSON file): token/cost line per change, findings as they appear |
 | `context-doctor doctor` | Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes |
 | `context-doctor dashboard` | Local savings dashboard on 127.0.0.1: tokens saved per day, sessions by context in use vs recoverable, budget status |
 | `context-doctor statusline` | Claude Code status bar: live context vs window, cache share, cost. Wired by `install --statusline`; never overwrites a statusLine you already have |
@@ -281,6 +282,8 @@ The proxy dedupes repeated content, trims stale tool results, and strips base64
 [context-doctor] POST /v1/messages → 200 in 842ms | optimized 7.3k → 518 tokens (2 changes) | session total: 6.9k tokens ≈ $0.021 saved
 ```
 
+Only conversation requests (`/v1/messages`, `/v1/chat/completions`, `/v1/responses`) are ever rewritten. Every other endpoint a client uses through the proxy (listing models, uploading files, counting tokens) is forwarded untouched, to Anthropic when the request carries `anthropic-version` or `x-api-key` and to OpenAI otherwise, and request bodies the proxy does not rewrite reach upstream byte for byte.
+
 `GET http://localhost:8787/stats` returns cumulative savings (requests, tokens, estimated USD), **exact upstream usage** read from every response (JSON and SSE), and **prompt-cache advisories** — the proxy watches your real traffic and flags big stable prefixes missing `cache_control` or prefix churn that silently re-bills the cache. Per-model behavior via `--config`: The advisor now says *where*: for a large system/tools prefix it names the block to mark (the last tool definition, or the last system block), and when the older messages were byte-identical to the previous request it names the exact message to put `cache_control` on, with the token count that run is re-billing each turn. Anyone who already placed breakpoints is left alone.
 
 ```json
@@ -521,7 +524,7 @@ One report for your whole machine, led by a headline of **tokens context-doctor
 
 - **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.
+- and, **on its own line, not in the total**: sessions that got smaller after a hygiene warning. That is mostly compaction, by you or by Claude Code, and a warning may or may not be why it happened, so it is not credited to context-doctor (until 0.24 it was, which overclaimed). The dashboard keeps the same split.
 
 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.
 

package/dist/dashboard.d.ts

@@ -9,12 +9,14 @@
 import http from "node:http";
 export interface DashboardData {
     generatedAt: string;
+    /** tokensSaved: removed by context-doctor itself. shrinkage: sessions that got smaller after a warning (mostly compaction), shown apart. */
     totals: {
         tokensSaved: number;
         usdSaved: number;
         checks: number;
         warnings: number;
         optimizeRuns: number;
+        shrinkage: number;
     };
     daily: Array<{
         date: string;

package/dist/dashboard.js

@@ -37,7 +37,8 @@ export async function collectDashboardData(proxyPort = 8787) {
     // real reduction, so it counts alongside explicit optimize runs.
     const perSession = new Map();
     for (const c of checks) {
-        if (!c.sid || typeof c.tok !== "number")
+        // "mcp-sketch" was a shared id for unrelated chats (fixed in 0.24); never a session.
+        if (!c.sid || c.sid === "mcp-sketch" || typeof c.tok !== "number")
             continue;
         perSession.set(c.sid, [...(perSession.get(c.sid) ?? []), c.tok]);
     }
@@ -94,7 +95,10 @@ export async function collectDashboardData(proxyPort = 8787) {
     return {
         generatedAt: new Date().toISOString(),
         totals: {
-            tokensSaved: optimizeSaved + shrinkage + (proxy?.tokensSaved ?? 0),
+            // What context-doctor removed itself; compaction shrinkage is reported
+            // separately (it was counted here until 0.24, which overclaimed).
+            tokensSaved: optimizeSaved + (proxy?.tokensSaved ?? 0),
+            shrinkage,
             usdSaved: usdSaved + (proxy?.estUsdSaved ?? 0),
             checks: checks.length + carried.checks,
             warnings: checks.filter((c) => c.warn).length + carried.warnings,

package/dist/impact.js

@@ -41,7 +41,8 @@ export async function buildImpactReport(proxyPort = 8787) {
     // 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")
+        // "mcp-sketch" was a shared id for unrelated chats (fixed in 0.24); never a session.
+        if (!c.sid || c.sid === "mcp-sketch" || typeof c.tok !== "number")
             continue;
         const s = bySession.get(c.sid) ?? { toks: [], warns: 0 };
         s.toks.push(c.tok);
@@ -77,7 +78,10 @@ export async function buildImpactReport(proxyPort = 8787) {
     const proxyHistoric = proxyEvents.reduce((s, e) => s + (e.saved ?? 0), 0) + carried.proxySaved;
     const proxySaved = proxyHistoric + (proxy?.tokensSaved ?? 0);
     // -- Headline: what context-doctor has saved ----------------------------------
-    const totalSaved = proxySaved + optimizeSaved + totalReduction;
+    // Only what context-doctor itself removed. Sessions also shrink when Claude
+    // Code auto-compacts or the user runs /compact; counting that as our saving
+    // overclaimed (until 0.24 it was in this total), so it is shown apart.
+    const totalSaved = proxySaved + optimizeSaved;
     lines.push("Tokens context-doctor saved (measured)");
     lines.push("─".repeat(56));
     lines.push(`TOTAL: ~${formatTokens(totalSaved)} tokens`);
@@ -97,7 +101,10 @@ export async function buildImpactReport(proxyPort = 8787) {
     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("");
+    lines.push(`Sessions that got smaller after a hygiene warning: ${formatTokens(totalReduction)} tokens`);
+    lines.push("  (mostly compaction, by you or Claude Code; not counted above, because a warning");
+    lines.push("  may or may not be why it happened)");
     lines.push("");
     // -- Hook activity ------------------------------------------------------------
     lines.push("Hygiene activity (every-prompt hook)");

package/dist/mcp.js

@@ -49,23 +49,23 @@ 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.23.1" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.24.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({
-            turns: z.number().int().nonnegative().describe("User+assistant exchanges so far"),
+            turns: z.number().int().nonnegative().max(100_000).describe("User+assistant exchanges so far"),
             model: z.string().optional().describe("Model this chat runs as, e.g. claude-sonnet-5, gpt-5"),
             blocks: z.array(z.object({
-                turn: z.number().int().positive().describe("1-based turn the block sits in"),
+                turn: z.number().int().positive().max(100_000).describe("1-based turn the block sits in"),
                 kind: z.enum(["paste", "code", "tool_result", "image", "base64", "text"]),
                 label: z.string().describe("Short name you can refer to later, e.g. 'the nginx config'"),
-                approx_tokens: z.number().positive().optional(),
-                approx_lines: z.number().positive().optional(),
-                approx_words: z.number().positive().optional(),
-                approx_chars: z.number().positive().optional(),
-                repeated: z.number().int().positive().optional().describe("Times this same content appears (2+ = duplicate)"),
+                approx_tokens: z.number().positive().max(10_000_000).optional(),
+                approx_lines: z.number().positive().max(1_000_000).optional(),
+                approx_words: z.number().positive().max(5_000_000).optional(),
+                approx_chars: z.number().positive().max(40_000_000).optional(),
+                repeated: z.number().int().positive().max(1000).optional().describe("Times this same content appears (2+ = duplicate)"),
                 stale: z.boolean().optional().describe("Already acted on; nothing in it is still needed"),
-            })).describe("Only the blocks over ~500 tokens, repeated, or images. Plain turns need not be listed."),
+            })).max(500).describe("Only the blocks over ~500 tokens, repeated, or images. Plain turns need not be listed."),
         }).optional().describe("Coarse description of the conversation for chat apps. One size hint per block: lines for code, words for prose, chars (or tokens) for logs and tool output, which vary most per line."),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),
     }, async ({ conversation, sketch, model }) => {
@@ -85,7 +85,7 @@ function createServer() {
         conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array)"),
         strategies: z.array(z.enum(STRATEGY_IDS)).optional()
             .describe("Strategies to apply. Default: dedupe, trim-tool-results, strip-base64. Add trim-tool-calls to shrink big inline file writes, or prune-history for lossy compaction of old turns."),
-        keep_recent: z.number().int().positive().optional().describe("Messages at the tail to leave untouched (default 6)"),
+        keep_recent: z.number().int().nonnegative().optional().describe("Messages at the tail to leave untouched (default 6; 0 = none)"),
         max_tool_result_tokens: z.number().int().positive().optional().describe("Token budget for trimmed tool results (default 300)"),
     }, async ({ conversation, strategies, keep_recent, max_tool_result_tokens }) => {
         const result = optimizeConversation(conversation, {

package/dist/proxy.d.ts

@@ -47,13 +47,22 @@ 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.23.1";
+export declare const PROXY_VERSION = "0.24.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
  * so the token cannot be guessed a character at a time.
  */
 export declare function stripToken(url: string, token: string): string | undefined;
+/**
+ * Where a request goes. The endpoints we optimize are fixed; EVERY other path
+ * is forwarded untouched, because a client routed through the proxy (Claude
+ * Code under autopilot, an SDK) also lists models, uploads files, counts
+ * tokens. Until 0.24 those got a 404 and broke the feature for that client.
+ * Unknown paths go to Anthropic when the request says it is one (Anthropic
+ * clients always send anthropic-version, or x-api-key), else to OpenAI.
+ */
+export declare function upstreamFor(url: string, opts: ProxyOptions, headers?: http.IncomingHttpHeaders): string;
 export interface ProxyStats {
     startedAt: string;
     requests: number;

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.23.1";
+export const PROXY_VERSION = "0.24.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"]);
@@ -41,13 +41,22 @@ export function stripToken(url, token) {
     const rest = end === -1 ? "/" : url.slice(end);
     return rest;
 }
-function upstreamFor(url, opts) {
+/**
+ * Where a request goes. The endpoints we optimize are fixed; EVERY other path
+ * is forwarded untouched, because a client routed through the proxy (Claude
+ * Code under autopilot, an SDK) also lists models, uploads files, counts
+ * tokens. Until 0.24 those got a 404 and broke the feature for that client.
+ * Unknown paths go to Anthropic when the request says it is one (Anthropic
+ * clients always send anthropic-version, or x-api-key), else to OpenAI.
+ */
+export function upstreamFor(url, opts, headers = {}) {
+    const anthropic = opts.anthropicUpstream ?? "https://api.anthropic.com";
+    const openai = opts.openaiUpstream ?? "https://api.openai.com";
     if (url.startsWith("/v1/messages"))
-        return opts.anthropicUpstream ?? "https://api.anthropic.com";
-    if (url.startsWith("/v1/chat/completions") || url.startsWith("/v1/responses") || url.startsWith("/v1/embeddings")) {
-        return opts.openaiUpstream ?? "https://api.openai.com";
-    }
-    return undefined;
+        return anthropic;
+    if (url.startsWith("/v1/chat/completions") || url.startsWith("/v1/responses") || url.startsWith("/v1/embeddings"))
+        return openai;
+    return headers["anthropic-version"] !== undefined || headers["x-api-key"] !== undefined ? anthropic : openai;
 }
 /** Pull exact usage out of a response body — JSON or SSE, either provider. */
 function extractUsage(text) {
@@ -125,7 +134,7 @@ export function startProxy(opts = {}) {
                 res.end(JSON.stringify({ ...stats, estUsdSaved: Number(stats.estUsdSaved.toFixed(4)) }, null, 2));
                 return;
             }
-            const upstreamBase = upstreamFor(url, opts);
+            const upstreamBase = upstreamFor(url, opts, req.headers);
             if (!upstreamBase) {
                 res.statusCode = 404;
                 res.setHeader("content-type", "application/json");
@@ -135,7 +144,13 @@ export function startProxy(opts = {}) {
             const chunks = [];
             for await (const chunk of req)
                 chunks.push(chunk);
-            let body = Buffer.concat(chunks).toString("utf8");
+            // Keep the original bytes: only conversation JSON is ever rewritten, and
+            // anything else (a multipart file upload) must reach upstream byte for
+            // byte. Decoding everything as UTF-8 corrupted binary bodies.
+            const rawBody = Buffer.concat(chunks);
+            let body = rawBody.toString("utf8");
+            const originalBody = body;
+            const conversationPath = /^\/v1\/(messages|chat\/completions|responses)(\?|$)/.test(url);
             // Optimize the message history in flight. Anything unparseable (or with
             // no messages array, e.g. embeddings) passes through untouched.
             // count_tokens is measurement — optimizing it would silently change the
@@ -184,7 +199,7 @@ export function startProxy(opts = {}) {
                     }
                 }
             }
-            else if (req.method === "POST" && body && !isMeasurement) {
+            else if (req.method === "POST" && body && !isMeasurement && conversationPath) {
                 try {
                     // Per-route overrides: first modelPrefix match wins.
                     let effective = opts;
@@ -284,7 +299,7 @@ export function startProxy(opts = {}) {
             const upstream = await fetch(upstreamBase + url, {
                 method: req.method ?? "POST",
                 headers,
-                body: req.method === "GET" || req.method === "HEAD" ? undefined : body,
+                body: req.method === "GET" || req.method === "HEAD" ? undefined : body === originalBody ? rawBody : body,
             });
             console.error(`[context-doctor] ${req.method} ${url} → ${upstream.status} in ${Date.now() - upstreamStart}ms | ${note}` +
                 (stats.tokensSaved > 0 ? ` | session total: ${formatTokens(stats.tokensSaved)} tokens ≈ ${formatUsd(stats.estUsdSaved)} saved` : ""));

package/dist/session.js

@@ -274,6 +274,14 @@ function fromCodexLine(entry) {
             return null;
     }
 }
+/** Message content as a block array (a plain string becomes one text block). */
+function asBlocks(content) {
+    if (Array.isArray(content))
+        return content;
+    if (typeof content === "string")
+        return content ? [{ type: "text", text: content }] : [];
+    return content == null ? [] : [content];
+}
 export function parseSessionFile(path) {
     // ChatGPT exports are one big JSON array, not JSONL — and small enough to
     // read whole. Only peek first, so multi-hundred-MB JSONL is never slurped.
@@ -293,6 +301,12 @@ export function parseSessionFile(path) {
     let model;
     /** Index in `messages` of the newest compaction summary, or -1. */
     let lastCompactIndex = -1;
+    let lastReplyId;
+    /** Where each API reply (by message id) lives in `messages`. */
+    const replyIndex = new Map();
+    let lastSampledReplyId;
+    // A compaction summary marks where the live context starts; never merge into it.
+    const prevIndexAllowsMerge = (i) => i !== lastCompactIndex;
     /** Newest API-reported input size, if the transcript carries usage. */
     let reportedInputTokens;
     /** Every reported size, positioned — the basis for `context-doctor accuracy`. */
@@ -366,7 +380,16 @@ export function parseSessionFile(path) {
                 usageNumber(usage.cache_creation_input_tokens);
             if (total > 0) {
                 reportedInputTokens = total;
-                usageSamples.push({ index: messages.length, input: total });
+                // One sample per API reply: Claude Code writes a reply as several
+                // rows (one per content block) carrying the same usage. The request's
+                // input is everything before the reply's first row.
+                const replyId = typeof message.id === "string" ? message.id : undefined;
+                if (!replyId || replyId !== lastSampledReplyId) {
+                    const prevMsg = messages[messages.length - 1];
+                    const startsNew = !(prevMsg?.role === "assistant" && replyId !== undefined && replyId === lastReplyId);
+                    usageSamples.push({ index: startsNew ? messages.length : messages.length - 1, input: total });
+                    lastSampledReplyId = replyId;
+                }
             }
         }
         if (entry.isCompactSummary)
@@ -389,7 +412,34 @@ export function parseSessionFile(path) {
                 }
             }
         }
-        messages.push({ role: message.role, content: message.content });
+        // Rebuild messages the way the API saw them. Claude Code writes one row
+        // per content block, so one reply (text + two tool calls) arrived as three
+        // "assistant" messages and its results as two "user" ones: exported
+        // conversations broke tool_use/tool_result pairing, and every split added
+        // per-message overhead to the profile. The API treats consecutive
+        // same-role messages as one; so do we.
+        // Parallel tool calls are written as they stream: a reply's later
+        // tool_use rows can land after the first tool_result rows. A row that
+        // belongs to an earlier reply (same message id) joins that reply.
+        const replyId = entry.type === "assistant" && typeof message.id === "string" ? message.id : undefined;
+        const home = replyId !== undefined ? replyIndex.get(replyId) : undefined;
+        if (home !== undefined && home > lastCompactIndex && home < messages.length - 1) {
+            messages[home].content = [...asBlocks(messages[home].content), ...asBlocks(message.content)];
+            return;
+        }
+        const prev = messages[messages.length - 1];
+        if (entry.type === "assistant")
+            lastReplyId = replyId;
+        if (prev && prev.role === message.role && !entry.isCompactSummary && prevIndexAllowsMerge(messages.length - 1)) {
+            prev.content = [...asBlocks(prev.content), ...asBlocks(message.content)];
+            if (replyId !== undefined)
+                replyIndex.set(replyId, messages.length - 1);
+        }
+        else {
+            messages.push({ role: message.role, content: message.content });
+            if (replyId !== undefined)
+                replyIndex.set(replyId, messages.length - 1);
+        }
     });
     const toolTimings = [...latenciesByTool.entries()]
         .map(([tool, ms]) => {

package/dist/sketch.js

@@ -186,6 +186,8 @@ export function renderSketchProfile(p) {
 /** Profile a sketch, log it to the ledger like a hook check, and render. */
 export function runSketch(sketch) {
     const profile = profileSketch(sketch);
-    recordLedger({ ev: "check", sid: "mcp-sketch", src: "mcp", tok: profile.totalTokens, warn: profile.findings.some((f) => f.severity !== "info"), model: sketch.model });
+    // No session id: each sketch describes a different chat, and a shared id made
+    // the dashboard read "big sketch, then a smaller one" as tokens saved.
+    recordLedger({ ev: "check", src: "mcp", tok: profile.totalTokens, warn: profile.findings.some((f) => f.severity !== "info"), model: sketch.model });
     return renderSketchProfile(profile);
 }

package/dist/tokens.js

@@ -102,6 +102,8 @@ export function formatTokens(n) {
     // rather than something false.
     if (!Number.isFinite(n))
         return "0";
+    if (n >= 1_000_000_000)
+        return `${(n / 1_000_000_000).toFixed(1)}B`;
     if (n >= 1_000_000)
         return `${(n / 1_000_000).toFixed(1)}M`;
     if (n >= 10_000)

package/dist/watch.js

@@ -7,7 +7,7 @@
  * Polling (not fs.watch) is deliberate: editors/agents rewrite files in ways
  * that break watchers cross-platform, and a 2s stat is effectively free.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { listSessions, parseSessionFile } from "./session.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
@@ -31,10 +31,24 @@ export function runWatch(opts) {
             if (size === lastSize)
                 return; // nothing new — cost of this tick was one stat
             lastSize = size;
+            // A session transcript (Claude Code, Codex, ChatGPT export), or else a
+            // plain conversation file (OpenAI/Anthropic messages JSON), which is how
+            // most agent frameworks dump a trace. Until 0.24 the second kind was
+            // read as an empty session and watch printed nothing.
             const parsed = parseSessionFile(file);
-            if (parsed.messageCount === 0)
-                return;
-            const profile = profileConversation(parseConversation(parsed.conversationJson), opts.model ?? parsed.model);
+            let conversation;
+            let model = opts.model;
+            if (parsed.messageCount > 0) {
+                conversation = parseConversation(parsed.conversationJson);
+                model ??= parsed.model;
+            }
+            else {
+                conversation = parseConversation(readFileSync(file, "utf8"));
+                if (conversation.parseWarning || conversation.messages.length === 0)
+                    return;
+                model ??= conversation.model;
+            }
+            const profile = profileConversation(conversation, model);
             const delta = profile.totalTokens - lastTokens;
             lastTokens = profile.totalTokens;
             const cost = profile.cost ? ` · ${formatUsd(profile.cost.perCallUsd)}/msg` : "";

package/package.json

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