context-doctor 0.13.5 → 0.14.2

package/dist/statusline.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `context-doctor statusline` — live context health in Claude Code's status bar.
+ *
+ * Claude Code's `statusLine` setting runs a command on every refresh and shows
+ * its first line of stdout. That is "context health where the work happens"
+ * without an editor extension: the number that matters, visible while typing.
+ *
+ * It has to be fast and silent. Fast: the status payload on stdin carries the
+ * live context size in recent versions; when it does not, only the tail of the
+ * transcript is read (last 256KB, ~1ms on a 20MB file). Silent: any failure
+ * prints nothing at all, because a status line that shows an error is worse
+ * than one that shows nothing.
+ */
+/** The parts of Claude Code's status payload this reads. All optional. */
+interface StatusInput {
+    transcript_path?: string;
+    model?: {
+        id?: string;
+        display_name?: string;
+    };
+    cost?: {
+        total_cost_usd?: number;
+    };
+    context_window?: {
+        total_input_tokens?: number;
+        context_window_size?: number;
+        current_usage?: {
+            input_tokens?: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+        };
+    };
+}
+interface LiveUsage {
+    tokens: number;
+    cacheShare?: number;
+    model?: string;
+}
+/** Newest assistant usage from the END of a transcript, without reading the file. */
+export declare function tailUsage(path: string, tailBytes?: number): LiveUsage | undefined;
+/** Build the status line, or null when there is nothing trustworthy to show. */
+export declare function renderStatusLine(input: StatusInput): string | null;
+export declare function runStatusLine(): Promise<void>;
+export {};

package/dist/statusline.js

@@ -0,0 +1,104 @@
+/**
+ * `context-doctor statusline` — live context health in Claude Code's status bar.
+ *
+ * Claude Code's `statusLine` setting runs a command on every refresh and shows
+ * its first line of stdout. That is "context health where the work happens"
+ * without an editor extension: the number that matters, visible while typing.
+ *
+ * It has to be fast and silent. Fast: the status payload on stdin carries the
+ * live context size in recent versions; when it does not, only the tail of the
+ * transcript is read (last 256KB, ~1ms on a 20MB file). Silent: any failure
+ * prints nothing at all, because a status line that shows an error is worse
+ * than one that shows nothing.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { contextWindowFor, formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+/** Newest assistant usage from the END of a transcript, without reading the file. */
+export function tailUsage(path, tailBytes = 256 * 1024) {
+    try {
+        const size = statSync(path).size;
+        const n = Math.min(size, tailBytes);
+        const fd = openSync(path, "r");
+        const buf = Buffer.alloc(n);
+        try {
+            readSync(fd, buf, 0, n, size - n);
+        }
+        finally {
+            closeSync(fd);
+        }
+        for (const line of buf.toString("utf8").split("\n").reverse()) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue; // the first line of a tail is usually a partial one
+            }
+            const usage = entry.type === "assistant" ? entry.message?.usage : undefined;
+            if (!usage)
+                continue;
+            const read = usage.cache_read_input_tokens ?? 0;
+            const tokens = (usage.input_tokens ?? 0) + read + (usage.cache_creation_input_tokens ?? 0);
+            if (tokens > 0)
+                return { tokens, cacheShare: read / tokens, model: entry.message?.model };
+        }
+    }
+    catch {
+        /* unreadable: the caller shows nothing */
+    }
+    return undefined;
+}
+/** Ten-cell bar; the visual half of the number. */
+function bar(pct) {
+    const filled = Math.max(0, Math.min(10, Math.round(pct / 10)));
+    return "▮".repeat(filled) + "░".repeat(10 - filled);
+}
+/** Build the status line, or null when there is nothing trustworthy to show. */
+export function renderStatusLine(input) {
+    let live;
+    const cw = input.context_window;
+    const fromPayload = cw?.current_usage
+        ? (cw.current_usage.input_tokens ?? 0) + (cw.current_usage.cache_read_input_tokens ?? 0) + (cw.current_usage.cache_creation_input_tokens ?? 0)
+        : cw?.total_input_tokens;
+    if (fromPayload && fromPayload > 0) {
+        const read = cw?.current_usage?.cache_read_input_tokens;
+        live = { tokens: fromPayload, cacheShare: read !== undefined ? read / fromPayload : undefined, model: input.model?.id };
+    }
+    else if (input.transcript_path) {
+        live = tailUsage(input.transcript_path);
+    }
+    if (!live)
+        return null;
+    const window = cw?.context_window_size ?? contextWindowFor(live.model ?? input.model?.id);
+    const parts = [];
+    if (window) {
+        const pct = (live.tokens / window) * 100;
+        parts.push(`ctx ${formatTokens(live.tokens)}/${formatTokens(window)} ${bar(pct)} ${pct.toFixed(0)}%${pct >= 70 ? " ⚠" : ""}`);
+    }
+    else {
+        parts.push(`ctx ${formatTokens(live.tokens)}`);
+    }
+    if (live.cacheShare !== undefined)
+        parts.push(`cache ${Math.round(live.cacheShare * 100)}%`);
+    if (input.cost?.total_cost_usd && input.cost.total_cost_usd > 0)
+        parts.push(formatUsd(input.cost.total_cost_usd));
+    return parts.join(" · ");
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runStatusLine() {
+    try {
+        const input = JSON.parse(await readStdin());
+        const line = renderStatusLine(input);
+        if (line)
+            console.log(line);
+    }
+    catch {
+        /* silent by design */
+    }
+}

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.13.5",
+  "version": "0.14.2",
   "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",
@@ -42,7 +42,7 @@
     "build": "tsc && 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 --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/proxy-abort.test.js dist/test/hook.test.js dist/test/mcp-http.test.js dist/test/doctor.test.js dist/test/watch.test.js dist/test/chatgpt-export.test.js dist/test/config.test.js dist/test/dashboard.test.js dist/test/cursor.test.js dist/test/cache.test.js dist/test/session.test.js dist/test/accuracy.test.js dist/test/cache-stability.test.js dist/test/ledger.test.js"
+    "test": "npm run build && node scripts/test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",