context-doctor 0.14.1 → 0.14.3

package/README.md

@@ -92,7 +92,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor, the Agent Skill, the every-prompt hook |
 | `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates. `--fail-over-budget` exits 1 on a breach, for CI |
 | `context-doctor optimize <file>` | Apply the safe fixes; add `--strategy trim-tool-calls` for big inline file writes, `--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**, and **where the wall clock went** per tool (from transcript timestamps, permission waits included and said so). Also reads ChatGPT data exports (`conversations.json`) |
+| `context-doctor session [file]` | Profile a Claude Code session: live context, findings, **measured tokens and prompt-cache economics**, **where the wall clock went** per tool, and **what its subagents cost** (their own windows, your bill; never in the parent's profile). Also reads ChatGPT data exports (`conversations.json`) |
 | `context-doctor init [preset]` | Write a `.contextdoctorrc` from a preset (`chat`, `agent`, `batch`) — a budget you can adopt in one command and tune later |
 | `context-doctor experiment --task "…"` | Run one task twice from the same commit, in a fresh session and forked from an `--existing` one, same model and tools; compare bill, cache split, wall clock, and whether `--check` passed. The only command here that spends money, so it caps spend per arm and refuses a dirty tree |
 | `context-doctor diff <before> <after>` | Compare two profiles: what moved by category, which findings were resolved or introduced, and what it saves in money and latency |
@@ -248,6 +248,38 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 });
 ```
 
+## Subagents: their own windows, your bill
+
+A subagent has its own context window, so its tokens are correctly absent from the parent's profile. They are not absent from the bill. Claude Code writes each one to `<session>/subagents/agent-<id>.jsonl`, and `session` now reads them:
+
+```
+Subagents (their own windows, your bill)
+────────────────────────────────────────────────────────
+49 subagent(s) made 4560 API calls: 626.0M input billed, 1.0M output, ~$608.51.
+That is 10% on top of the parent session's own input cost ($5846.45), and none of it appears in the profile above.
+    $42.52   51 calls  ctx   319k    6m  You are auditing part of a FastAPI backend at /Users/kp/tech
+    $37.48  107 calls  ctx   229k    6m  You are auditing the Turtle AI backend (FastAPI, Python) at
+  … and 44 more
+18 subagent(s) ended above 200k tokens of context. A subagent that big is doing a main session's job; give it a narrower brief, or split the task.
+```
+
+Per subagent: what it was asked, how many calls it made, the context it ended with, how long it ran, and its cost at list price with cache reads and writes priced correctly. Models without a price on file are counted but marked unpriced rather than costed at zero. On this machine that was 195 subagents across 19 sessions and about $1,844 at list price that no profile had ever shown.
+
+## The same number inside VS Code and Cursor
+
+An extension in [`vscode/`](vscode/) puts context health in the editor's own status bar:
+
+```
+⌁ ctx 848k · 85% · cache 100% ⚠
+```
+
+It reads the newest Claude Code transcript for the open workspace folder, shows live context, share of window and cache share, turns to the warning colour past 70% (configurable), and opens a terminal running `context-doctor session` when clicked. Nothing leaves the machine; it only reads files Claude Code already writes. Until it is on the marketplace, build and install it locally:
+
+```bash
+cd vscode && npm ci && npm run package
+code --install-extension context-doctor-vscode-0.1.0.vsix     # or: cursor --install-extension …
+```
+
 ## Context health in Claude Code's status bar
 
 ```bash

package/dist/cli.js

@@ -26,6 +26,7 @@ import { measureAccuracy, renderAccuracy } from "./accuracy.js";
 import { renderDiff } from "./diff.js";
 import { renderExperiment, runExperiment } from "./experiment.js";
 import { runStatusLine } from "./statusline.js";
+import { renderSubagents, subagentReport } from "./subagents.js";
 import { findPreset, PRESETS, RC_FILENAME } from "./config.js";
 import { runWatch } from "./watch.js";
 import { exactTokenCount } from "./exact.js";
@@ -387,7 +388,7 @@ function main() {
         }
         const profile = profileConversation(parseConversation(parsed.conversationJson), args.model ?? parsed.model);
         if (args.json) {
-            console.log(JSON.stringify({ session: { path: parsed.path, title: parsed.title, toolTimings: parsed.toolTimings ?? [] }, profile }, null, 2));
+            console.log(JSON.stringify({ session: { path: parsed.path, title: parsed.title, toolTimings: parsed.toolTimings ?? [], subagents: subagentReport(path) }, profile }, null, 2));
         }
         else {
             console.log(`Session: ${parsed.title ?? "(untitled)"}\nFile:    ${parsed.path}`);
@@ -403,7 +404,8 @@ function main() {
                     "transcript does not record — so it is larger than the breakdown above, which covers\n" +
                     "conversation messages only. Findings and savings apply to the messages.");
             }
-            const cache = renderCacheReport(analyzeCacheUsage(path));
+            const cacheUsage = analyzeCacheUsage(path);
+            const cache = renderCacheReport(cacheUsage);
             if (cache) {
                 console.log("");
                 console.log(cache);
@@ -413,6 +415,11 @@ function main() {
                 console.log("");
                 console.log(timing);
             }
+            const subs = renderSubagents(subagentReport(path), cacheUsage?.paidUsd);
+            if (subs) {
+                console.log("");
+                console.log(subs);
+            }
             applyBudgetGate(printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`))), args.failOverBudget);
         }
         return;

package/dist/index.d.ts

@@ -17,3 +17,4 @@ export { pricingFor, inputCostUsd, estimatedTtftSeconds, formatUsd } from "./pri
 export type { ModelPricing } from "./pricing.js";
 export { estimateTokens, contextWindowFor, providerFor, formatTokens } from "./tokens.js";
 export type { Provider } from "./tokens.js";
+export { renderStatusLine, tailUsage } from "./statusline.js";

package/dist/index.js

@@ -10,3 +10,6 @@ export { startProxy } from "./proxy.js";
 export { listSessions, parseSessionFile } from "./session.js";
 export { pricingFor, inputCostUsd, estimatedTtftSeconds, formatUsd } from "./pricing.js";
 export { estimateTokens, contextWindowFor, providerFor, formatTokens } from "./tokens.js";
+// Status-line building blocks, for editor integrations (the VS Code / Cursor
+// extension in ./vscode) that show the same number in their own status bar.
+export { renderStatusLine, tailUsage } from "./statusline.js";

package/dist/mcp.js

@@ -37,7 +37,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.14.1" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.14.3" }, { 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/session.d.ts

@@ -72,4 +72,16 @@ export interface ParsedSession {
 }
 /** All session transcripts on this machine, newest first. */
 export declare function listSessions(limit?: number): SessionInfo[];
+/**
+ * Read a JSONL transcript line by line without ever materializing the whole
+ * file as one string.
+ *
+ * Agent sessions with large tool results reach hundreds of MB, and those are
+ * exactly the sessions that most need analysis — but V8 refuses to build a
+ * string past ~512MB, so readFileSync would throw on them (and in the hook,
+ * throw *silently*). Streaming has no such ceiling and keeps peak memory at
+ * one chunk. StringDecoder carries partial UTF-8 sequences across chunk
+ * boundaries so multi-byte characters are never corrupted.
+ */
+export declare function forEachLine(path: string, onLine: (line: string) => void): void;
 export declare function parseSessionFile(path: string): ParsedSession;

package/dist/session.js

@@ -119,7 +119,7 @@ function parseChatGPTExport(data, path) {
  * one chunk. StringDecoder carries partial UTF-8 sequences across chunk
  * boundaries so multi-byte characters are never corrupted.
  */
-function forEachLine(path, onLine) {
+export function forEachLine(path, onLine) {
     const fd = openSync(path, "r");
     const decoder = new StringDecoder("utf8");
     const buf = Buffer.allocUnsafe(4 * 1024 * 1024);

package/dist/subagents.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Subagent accounting.
+ *
+ * Every session profile here excludes subagent traffic, correctly: a subagent
+ * has its own context window, so its tokens are not in the parent's context.
+ * But they are on the parent's bill. Claude Code writes each subagent to its
+ * own transcript under `<session>/subagents/agent-<id>.jsonl`, next to the
+ * parent's `<session>.jsonl` — which is why scanning the parent for
+ * `isSidechain` entries found nothing for weeks. On this machine: 195
+ * subagents across 19 sessions whose final contexts sum to 28 million tokens,
+ * none of it ever shown.
+ *
+ * Reads only the lines that matter (usage, first user turn, timestamps) and
+ * never the whole content, so a session with 49 subagents stays fast.
+ */
+export interface SubagentSummary {
+    id: string;
+    model?: string;
+    /** What the parent asked it to do: first user message, trimmed. */
+    task: string;
+    /** API calls the subagent made (assistant turns carrying usage). */
+    calls: number;
+    /** Context size on its last call: what each further turn would have cost. */
+    finalContextTokens: number;
+    /** Input billed across all its calls, including cache reads and writes. */
+    inputBilledTokens: number;
+    cacheReadTokens: number;
+    outputTokens: number;
+    /** Cost across all calls at list price with cache-read discount. */
+    estCostUsd?: number;
+    durationMs?: number;
+}
+export interface SubagentReport {
+    agents: SubagentSummary[];
+    totalInputBilled: number;
+    totalOutput: number;
+    totalCostUsd: number;
+    /** Agents whose model has no price on file, so the total undercounts. */
+    unpriced: number;
+}
+/** Where Claude Code keeps a session's subagents: beside the transcript, under its id. */
+export declare function subagentDir(transcriptPath: string): string;
+/** Account for every subagent of a session, or null when there are none. */
+export declare function subagentReport(transcriptPath: string): SubagentReport | null;
+/**
+ * @param parentInputUsd what the PARENT session's input actually cost across
+ *   all its calls (from the cache analysis), so the comparison is total against
+ *   total. Comparing against a per-call figure produced nonsense like "159x".
+ */
+export declare function renderSubagents(report: SubagentReport | null, parentInputUsd?: number, top?: number): string | null;

package/dist/subagents.js

@@ -0,0 +1,175 @@
+/**
+ * Subagent accounting.
+ *
+ * Every session profile here excludes subagent traffic, correctly: a subagent
+ * has its own context window, so its tokens are not in the parent's context.
+ * But they are on the parent's bill. Claude Code writes each subagent to its
+ * own transcript under `<session>/subagents/agent-<id>.jsonl`, next to the
+ * parent's `<session>.jsonl` — which is why scanning the parent for
+ * `isSidechain` entries found nothing for weeks. On this machine: 195
+ * subagents across 19 sessions whose final contexts sum to 28 million tokens,
+ * none of it ever shown.
+ *
+ * Reads only the lines that matter (usage, first user turn, timestamps) and
+ * never the whole content, so a session with 49 subagents stays fast.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { formatTokens } from "./tokens.js";
+import { formatUsd, pricingFor } from "./pricing.js";
+import { forEachLine } from "./session.js";
+/** Where Claude Code keeps a session's subagents: beside the transcript, under its id. */
+export function subagentDir(transcriptPath) {
+    return join(transcriptPath.replace(/\.jsonl$/, ""), "subagents");
+}
+function n(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0;
+}
+function summarize(path) {
+    const s = {
+        id: basename(path, ".jsonl").replace(/^agent-/, ""),
+        task: "",
+        calls: 0,
+        finalContextTokens: 0,
+        inputBilledTokens: 0,
+        cacheReadTokens: 0,
+        outputTokens: 0,
+    };
+    let first;
+    let last;
+    let cost = 0;
+    let priced = true;
+    forEachLine(path, (line) => {
+        // Cheap pre-filter: most lines are content we do not need to parse.
+        if (!line.includes('"usage"') && !line.includes('"timestamp"') && !s.task)
+            return;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const at = Date.parse(String(e.timestamp ?? ""));
+        if (Number.isFinite(at)) {
+            first = first === undefined ? at : Math.min(first, at);
+            last = last === undefined ? at : Math.max(last, at);
+        }
+        const m = e.message;
+        if (!m)
+            return;
+        if (e.type === "user" && !s.task) {
+            const c = m.content;
+            const text = typeof c === "string" ? c : Array.isArray(c) ? c.map((b) => (typeof b === "string" ? b : b?.text ?? "")).join(" ") : "";
+            s.task = text.replace(/\s+/g, " ").trim().slice(0, 140);
+        }
+        if (e.type === "assistant" && m.usage) {
+            const u = m.usage;
+            const input = n(u.input_tokens);
+            const read = n(u.cache_read_input_tokens);
+            const write = n(u.cache_creation_input_tokens);
+            const out = n(u.output_tokens);
+            if (input + read + write === 0)
+                return;
+            if (typeof m.model === "string")
+                s.model = m.model;
+            s.calls++;
+            s.finalContextTokens = input + read + write;
+            s.inputBilledTokens += input + read + write;
+            s.cacheReadTokens += read;
+            s.outputTokens += out;
+            const p = pricingFor(s.model);
+            if (p) {
+                // Cache writes bill at 1.25x input; reads at the cache-read rate.
+                cost += ((input + write * 1.25) * p.inputPerM + read * p.cacheReadPerM + out * p.outputPerM) / 1_000_000;
+            }
+            else {
+                priced = false;
+            }
+        }
+    });
+    if (first !== undefined && last !== undefined)
+        s.durationMs = last - first;
+    if (priced && s.calls > 0)
+        s.estCostUsd = cost;
+    return s;
+}
+/** Account for every subagent of a session, or null when there are none. */
+export function subagentReport(transcriptPath) {
+    const dir = subagentDir(transcriptPath);
+    if (!existsSync(dir))
+        return null;
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.startsWith("agent-") && f.endsWith(".jsonl"));
+    }
+    catch {
+        return null;
+    }
+    if (files.length === 0)
+        return null;
+    const agents = files
+        .map((f) => join(dir, f))
+        .filter((p) => {
+        try {
+            return statSync(p).size > 0;
+        }
+        catch {
+            return false;
+        }
+    })
+        .map(summarize)
+        .filter((a) => a.calls > 0)
+        .sort((a, b) => (b.estCostUsd ?? 0) - (a.estCostUsd ?? 0) || b.inputBilledTokens - a.inputBilledTokens);
+    if (agents.length === 0)
+        return null;
+    return {
+        agents,
+        totalInputBilled: agents.reduce((t, a) => t + a.inputBilledTokens, 0),
+        totalOutput: agents.reduce((t, a) => t + a.outputTokens, 0),
+        totalCostUsd: agents.reduce((t, a) => t + (a.estCostUsd ?? 0), 0),
+        unpriced: agents.filter((a) => a.estCostUsd === undefined).length,
+    };
+}
+function fmtDuration(ms) {
+    if (ms === undefined)
+        return "";
+    if (ms >= 3_600_000)
+        return `${(ms / 3_600_000).toFixed(1)}h`;
+    if (ms >= 60_000)
+        return `${(ms / 60_000).toFixed(0)}m`;
+    return `${(ms / 1000).toFixed(0)}s`;
+}
+/**
+ * @param parentInputUsd what the PARENT session's input actually cost across
+ *   all its calls (from the cache analysis), so the comparison is total against
+ *   total. Comparing against a per-call figure produced nonsense like "159x".
+ */
+export function renderSubagents(report, parentInputUsd, top = 5) {
+    if (!report)
+        return null;
+    const lines = [];
+    lines.push("Subagents (their own windows, your bill)");
+    lines.push("─".repeat(56));
+    const cost = report.unpriced === 0 ? formatUsd(report.totalCostUsd) : `${formatUsd(report.totalCostUsd)}+ (${report.unpriced} unpriced)`;
+    lines.push(`${report.agents.length} subagent(s) made ${report.agents.reduce((t, a) => t + a.calls, 0)} API calls: ` +
+        `${formatTokens(report.totalInputBilled)} input billed, ${formatTokens(report.totalOutput)} output, ~${cost}.`);
+    if (parentInputUsd !== undefined && parentInputUsd > 0 && report.totalCostUsd > 0) {
+        const ratio = report.totalCostUsd / parentInputUsd;
+        lines.push(ratio >= 1
+            ? `That is ${ratio.toFixed(1)}x what the parent session's own input cost (${formatUsd(parentInputUsd)}). None of it appears in the profile above.`
+            : `That is ${Math.round(ratio * 100)}% on top of the parent session's own input cost (${formatUsd(parentInputUsd)}), and none of it appears in the profile above.`);
+    }
+    for (const a of report.agents.slice(0, top)) {
+        const cost = a.estCostUsd !== undefined ? formatUsd(a.estCostUsd) : "unpriced";
+        lines.push(`  ${cost.padStart(8)}  ${String(a.calls).padStart(3)} calls  ctx ${formatTokens(a.finalContextTokens).padStart(6)}  ${fmtDuration(a.durationMs).padStart(4)}  ${a.task.slice(0, 60) || "(no task text)"}`);
+    }
+    if (report.agents.length > top)
+        lines.push(`  … and ${report.agents.length - top} more`);
+    const heavy = report.agents.filter((a) => a.finalContextTokens > 200_000);
+    if (heavy.length > 0) {
+        lines.push(`${heavy.length} subagent(s) ended above 200k tokens of context. A subagent that big is doing a main session's job; ` +
+            "give it a narrower brief, or split the task.");
+    }
+    return lines.join("\n");
+}

package/package.json

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