context-doctor 0.13.3 → 0.13.5

package/README.md

@@ -34,6 +34,8 @@ Findings (4)
 npx context-doctor install
 ```
 
+`install` configures every app it detects and does not stop at the first problem: a corrupt Claude Desktop config still gets you Claude Code and Cursor. It does not pretend either. Any target that failed is named with a ✗ line, the summary reads "Done with N problem(s)" instead of "Done.", and the **exit code is 1**, so dotfiles and onboarding scripts can react. A broken config file is never overwritten; fix it and re-run.
+
 That single command is also all it takes to **set up context-doctor on anyone else's machine**. Prefer a global install, or want the unreleased `main`? Both work (Node 20+):
 
 ```bash
@@ -90,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**. 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**, 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 init [preset]` | Write a `.contextdoctorrc` from a preset (`chat`, `agent`, `batch`) — a budget you can adopt in one command and tune later |
 | `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 |
 | `context-doctor accuracy` | How much of what you are billed for is visible in your transcript — the fixed harness baseline and the per-turn injected content neither you nor the profiler can see |
@@ -252,7 +254,7 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 - **Near-duplicates** — the same doc re-pasted with different surrounding words (shingle similarity, ≥60%)
 - **Repeated file reads** — the same file pulled in three or more times, every copy still in context. Counts shell reads too (`cat`, `head`, `tail`, `less`), which is where most of them hide in agent sessions
 - **Retained error output** — stack traces and failed commands kept verbatim long after the fix landed
-- **Repeated identical tool calls** — a signal your agent forgot earlier results
+- **Repeated identical tool calls**, split into the two things they can mean: a **retry** (the same call after a failure, where the fix is in the error text, and three or more is a loop) and a **re-read** (the same call after a success, where the model forgot it already had the answer). Across 42 local sessions that was 15 retries against 151 re-reads, so the old combined advice was wrong for most of them
 - **Base64 / binary blobs** in text content — checked by character distribution, not just alphabet, so hex digests and long identifiers are not mistaken for encoded binary
 - **Long history** past the point where models track the middle
 - **Cache-hostile ordering** — volatile content before stable content breaks prompt caching (Anthropic `cache_control`, OpenAI automatic prefix caching)

package/dist/cli.js

@@ -31,6 +31,7 @@ import { checkBudget, loadConfig } from "./config.js";
 import { startDashboard } from "./dashboard.js";
 import { listCursorChats, parseCursorChat } from "./cursor.js";
 import { analyzeCacheUsage, renderCacheReport } from "./cache.js";
+import { renderToolTimings } from "./timing.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -333,7 +334,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 }, profile }, null, 2));
+            console.log(JSON.stringify({ session: { path: parsed.path, title: parsed.title, toolTimings: parsed.toolTimings ?? [] }, profile }, null, 2));
         }
         else {
             console.log(`Session: ${parsed.title ?? "(untitled)"}\nFile:    ${parsed.path}`);
@@ -354,12 +355,20 @@ function main() {
                 console.log("");
                 console.log(cache);
             }
+            const timing = renderToolTimings(parsed.toolTimings ?? []);
+            if (timing) {
+                console.log("");
+                console.log(timing);
+            }
             applyBudgetGate(printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`))), args.failOverBudget);
         }
         return;
     }
     if (args.command === "install") {
-        runInstall();
+        // Partial success is still installed, but not silent: any failed target
+        // makes the exit code non-zero so automation can react.
+        if (runInstall().failures.length > 0)
+            process.exitCode = 1;
         return;
     }
     if (args.command === "uninstall") {

package/dist/install.d.ts

@@ -20,5 +20,20 @@ export declare function npxLauncher(platformName: string): {
     command: string;
     args: string[];
 };
-export declare function runInstall(): void;
+/** Outcome of an install run, so the CLI can set a truthful exit code. */
+export interface InstallResult {
+    /** Detected targets that could not be configured, with the reason. */
+    failures: string[];
+}
+/**
+ * Install into every detected app.
+ *
+ * A failure in one app must not stop the others: someone with a corrupt
+ * Claude Desktop config still wants Claude Code and Cursor wired. But it
+ * must not be reported as success either — automation (dotfiles, CI,
+ * onboarding scripts) reads the exit code, and a "Done." with exit 0 over a
+ * failed target is a lie that surfaces later as "the tools never showed up".
+ * So: keep going, summarize, and return the failures for a non-zero exit.
+ */
+export declare function runInstall(): InstallResult;
 export declare function runUninstall(): void;

package/dist/install.js

@@ -214,6 +214,16 @@ function installSkill() {
     copyFileSync(skillSource, join(skillDest, "SKILL.md"));
     return join(skillDest, "SKILL.md");
 }
+/**
+ * Install into every detected app.
+ *
+ * A failure in one app must not stop the others: someone with a corrupt
+ * Claude Desktop config still wants Claude Code and Cursor wired. But it
+ * must not be reported as success either — automation (dotfiles, CI,
+ * onboarding scripts) reads the exit code, and a "Done." with exit 0 over a
+ * failed target is a lie that surfaces later as "the tools never showed up".
+ * So: keep going, summarize, and return the failures for a non-zero exit.
+ */
 export function runInstall() {
     const entry = serverEntry();
     const found = targets().filter((t) => t.detect());
@@ -221,8 +231,9 @@ export function runInstall() {
         console.log("No supported AI apps detected (Claude Desktop, Claude Code, Cursor).");
         console.log("Manual setup — add to your app's MCP config:");
         console.log(JSON.stringify({ mcpServers: { "context-doctor": entry } }, null, 2));
-        return;
+        return { failures: [] };
     }
+    const failures = [];
     for (const target of found) {
         try {
             const config = readJson(target.configPath);
@@ -234,22 +245,44 @@ export function runInstall() {
         }
         catch (e) {
             console.error(`✗ ${target.name}: ${e.message}`);
+            failures.push(target.name);
         }
     }
-    const skillPath = installSkill();
-    if (skillPath)
-        console.log(`✓ Agent Skill installed for Claude Code (${skillPath})`);
-    const hookPath = installHook();
-    if (hookPath) {
-        console.log(`✓ Claude Code every-prompt hook installed (${hookPath}) — heavy sessions get automatic hygiene guidance`);
-        // npx resolves the package on every single prompt; a global install makes
-        // the hook a plain exec instead, which is both faster and update-proof.
-        if (hookUsesNpx()) {
-            console.log("  note: the hook falls back to npx. For a faster, permanent hook: npm i -g context-doctor && context-doctor install");
+    try {
+        const skillPath = installSkill();
+        if (skillPath)
+            console.log(`✓ Agent Skill installed for Claude Code (${skillPath})`);
+    }
+    catch (e) {
+        console.error(`✗ Agent Skill: ${e.message}`);
+        failures.push("Agent Skill");
+    }
+    try {
+        const hookPath = installHook();
+        if (hookPath) {
+            console.log(`✓ Claude Code every-prompt hook installed (${hookPath}) — heavy sessions get automatic hygiene guidance`);
+            // npx resolves the package on every single prompt; a global install makes
+            // the hook a plain exec instead, which is both faster and update-proof.
+            if (hookUsesNpx()) {
+                console.log("  note: the hook falls back to npx. For a faster, permanent hook: npm i -g context-doctor && context-doctor install");
+            }
         }
     }
-    console.log("\nDone. Restart the apps to pick up the new tools, then try:");
-    console.log('  "What\'s eating my context?" — or paste a conversation and ask for a profile.');
+    catch (e) {
+        // An unreadable settings.json used to escape as a stack trace and abort
+        // the run; it is a failed target like any other.
+        console.error(`✗ Claude Code every-prompt hook: ${e.message}`);
+        failures.push("Claude Code hook");
+    }
+    if (failures.length > 0) {
+        console.log(`\nDone with ${failures.length} problem(s): ${failures.join(", ")}. See the ✗ lines above.`);
+        console.log("Everything else was installed. Exit code is 1 so scripts can tell; fix the file(s) and re-run install.");
+    }
+    else {
+        console.log("\nDone. Restart the apps to pick up the new tools, then try:");
+        console.log('  "What\'s eating my context?" — or paste a conversation and ask for a profile.');
+    }
+    return { failures };
 }
 export function runUninstall() {
     for (const target of targets().filter((t) => t.detect())) {

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

@@ -22,6 +22,13 @@ export interface NormalizedMessage {
     toolCallText?: string;
     /** True when the content contained non-text blocks (images, documents). */
     hasBinary: boolean;
+    /**
+     * For tool results: the tool reported failure (Anthropic `is_error`).
+     * What separates a retry from a re-read: the same call after an error is
+     * the model trying again; the same call after a success is the model having
+     * forgotten it already had the answer. Different problems, different fixes.
+     */
+    isError?: boolean;
 }
 export interface NormalizedConversation {
     messages: NormalizedMessage[];

package/dist/parse.js

@@ -18,6 +18,7 @@ function flattenContent(content) {
     let toolName;
     let kind;
     let toolCallText = "";
+    let isError;
     for (const block of content) {
         if (block == null || typeof block !== "object") {
             text += String(block ?? "");
@@ -41,6 +42,8 @@ function flattenContent(content) {
                 const inner = flattenContent(b.content);
                 hasBinary = hasBinary || inner.hasBinary;
                 text += inner.text;
+                if (b.is_error === true)
+                    isError = true;
                 break;
             }
             case "image":
@@ -60,7 +63,7 @@ function flattenContent(content) {
                 text += JSON.stringify(b);
         }
     }
-    return { text, hasBinary, toolName, kind, toolCallText: toolCallText || undefined };
+    return { text, hasBinary, toolName, kind, toolCallText: toolCallText || undefined, isError };
 }
 function normalizeMessage(rawInput, index) {
     // A null or non-object entry appears in truncated and hand-edited files.
@@ -88,7 +91,7 @@ function normalizeMessage(rawInput, index) {
         text += calls;
         toolCallText = (toolCallText ?? "") + calls;
     }
-    return { index, role, kind, text, toolName, toolCallText, hasBinary: flat.hasBinary };
+    return { index, role, kind, text, toolName, toolCallText, hasBinary: flat.hasBinary, isError: flat.isError };
 }
 export function parseConversation(input) {
     let data;

package/dist/profile.d.ts

@@ -12,7 +12,7 @@ export interface MessageProfile {
     preview: string;
     toolName?: string;
 }
-export type FindingId = "large_tool_result" | "large_tool_call" | "duplicate_content" | "near_duplicate" | "repeated_tool_call" | "repeated_file_read" | "retained_error_output" | "base64_blob" | "long_history" | "large_system_prompt" | "cache_ordering" | "near_window_limit";
+export type FindingId = "large_tool_result" | "large_tool_call" | "duplicate_content" | "near_duplicate" | "repeated_tool_call" | "retried_tool_call" | "repeated_file_read" | "retained_error_output" | "base64_blob" | "long_history" | "large_system_prompt" | "cache_ordering" | "near_window_limit";
 export interface Finding {
     id: FindingId;
     severity: "info" | "warn" | "high";

package/dist/profile.js

@@ -259,14 +259,38 @@ export function profileConversation(conv, model) {
         list.push(p.msg.index);
         callSeen.set(key, list);
     }
+    // Identical calls come in two kinds that look the same and mean the
+    // opposite. If the previous attempt FAILED, the repeat is a retry: the fix is
+    // in the error text, and hammering the same command is the waste. If the
+    // previous attempt SUCCEEDED, the repeat is a re-read: the model forgot it
+    // already had the answer, and the earlier result is what should have stayed
+    // in view. Lumping them together gave the wrong advice to both.
+    const resultAfter = (callIndex) => perMessage.find((p) => p.msg.index > callIndex && p.msg.kind === "tool_result")?.msg;
     for (const [, idxs] of callSeen) {
-        if (idxs.length > 1) {
+        if (idxs.length < 2)
+            continue;
+        // Each repeat is classified by what happened to the attempt just before it.
+        const retries = idxs.slice(1).filter((_, i) => resultAfter(idxs[i])?.isError === true).length;
+        const rereads = idxs.length - 1 - retries;
+        if (retries > 0) {
+            findings.push({
+                id: "retried_tool_call",
+                severity: retries >= 3 ? "warn" : "info",
+                estSavings: 0,
+                message: `The same tool call was retried ${retries} time(s) after it failed (messages #${idxs.join(", #")}).`,
+                suggestion: retries >= 3
+                    ? "Three or more identical retries of a failing command is a loop. Each attempt keeps its error output in context; the answer is in the first error, not in the fourth attempt."
+                    : "A retry after a failure is normal once. The failed attempt's output stays in context though, so once the fix is understood the earlier error can go.",
+                messages: idxs,
+            });
+        }
+        if (rereads > 0) {
             findings.push({
                 id: "repeated_tool_call",
                 severity: "info",
                 estSavings: 0,
-                message: `The same tool call (with identical arguments) appears ${idxs.length} times (messages #${idxs.join(", #")}).`,
-                suggestion: "Repeated identical calls usually mean the earlier result scrolled out of the model's attention — cache results or surface them in a compact recap instead of re-calling.",
+                message: `The same tool call (with identical arguments) was repeated ${rereads} time(s) after it had already succeeded (messages #${idxs.join(", #")}).`,
+                suggestion: "Repeating a call that already succeeded means the earlier result scrolled out of the model's attention — keep results in a compact recap instead of re-calling.",
                 messages: idxs,
             });
         }

package/dist/session.d.ts

@@ -14,6 +14,14 @@ export interface SessionInfo {
     modifiedAt: Date;
     sizeBytes: number;
 }
+/** Wall-clock spent inside one tool, aggregated across a session. */
+export interface ToolTiming {
+    tool: string;
+    calls: number;
+    totalMs: number;
+    medianMs: number;
+    maxMs: number;
+}
 /** One API-reported input size, positioned in the message array. */
 export interface UsageSample {
     /** Index into the live `messages` array of the assistant message reporting it. */
@@ -46,6 +54,15 @@ export interface ParsedSession {
      * comparable to what the heuristic estimates for those same messages.
      */
     usageSamples?: UsageSample[];
+    /**
+     * Time between each tool_use and its tool_result, per tool, from the
+     * timestamps every transcript entry carries. This is the other half of the
+     * cost picture: tokens are what a call puts INTO context, this is how long
+     * it made you wait. Caveat that must travel with the number: the gap also
+     * contains any time spent waiting on a permission prompt, so an
+     * unattended run reads cleaner than an interactive one.
+     */
+    toolTimings?: ToolTiming[];
     /** Conversation JSON string in Anthropic-ish format, ready for parseConversation(). */
     conversationJson: string;
     title?: string;

package/dist/session.js

@@ -179,6 +179,9 @@ export function parseSessionFile(path) {
     let reportedInputTokens;
     /** Every reported size, positioned — the basis for `context-doctor accuracy`. */
     const usageSamples = [];
+    /** Open tool calls awaiting their result, by tool_use id. */
+    const pendingCalls = new Map();
+    const latenciesByTool = new Map();
     forEachLine(path, (line) => {
         if (!line.trim())
             return;
@@ -219,8 +222,39 @@ export function parseSessionFile(path) {
         }
         if (entry.isCompactSummary)
             lastCompactIndex = messages.length;
+        // Pair every tool_use with its tool_result by id and record the gap.
+        const at = Date.parse(String(entry.timestamp ?? ""));
+        if (Number.isFinite(at) && Array.isArray(message.content)) {
+            for (const block of message.content) {
+                if (block?.type === "tool_use" && typeof block.id === "string") {
+                    pendingCalls.set(block.id, { tool: String(block.name ?? "unknown"), at });
+                }
+                else if (block?.type === "tool_result" && typeof block.tool_use_id === "string") {
+                    const call = pendingCalls.get(block.tool_use_id);
+                    if (call) {
+                        pendingCalls.delete(block.tool_use_id);
+                        const ms = at - call.at;
+                        if (ms >= 0)
+                            latenciesByTool.set(call.tool, [...(latenciesByTool.get(call.tool) ?? []), ms]);
+                    }
+                }
+            }
+        }
         messages.push({ role: message.role, content: message.content });
     });
+    const toolTimings = [...latenciesByTool.entries()]
+        .map(([tool, ms]) => {
+        const sorted = [...ms].sort((a, b) => a - b);
+        const mid = Math.floor(sorted.length / 2);
+        return {
+            tool,
+            calls: ms.length,
+            totalMs: ms.reduce((a, b) => a + b, 0),
+            medianMs: sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2,
+            maxMs: sorted[sorted.length - 1],
+        };
+    })
+        .sort((a, b) => b.totalMs - a.totalMs);
     // A compaction replaces everything before it: the summary entry IS the live
     // history from that point on. Counting the pre-compaction turns would
     // overstate context, cost per message and window fill — sometimes hugely.
@@ -238,6 +272,7 @@ export function parseSessionFile(path) {
         usageSamples: usageSamples
             .filter((u) => u.index >= compactedAway)
             .map((u) => ({ index: u.index - compactedAway, input: u.input })),
+        toolTimings,
         path,
     };
 }

package/dist/timing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Where the wall clock went: per-tool latency from transcript timestamps.
+ *
+ * Tokens say what a tool call put INTO the context; this says how long it made
+ * the user wait. Both are needed to decide what to fix first: a Read that
+ * costs 9k tokens but returns instantly is a different problem from a Bash
+ * call that costs 200 tokens and takes 40 seconds.
+ */
+import type { ToolTiming } from "./session.js";
+export declare function renderToolTimings(timings: ToolTiming[], top?: number): string | null;

package/dist/timing.js

@@ -0,0 +1,42 @@
+/**
+ * Where the wall clock went: per-tool latency from transcript timestamps.
+ *
+ * Tokens say what a tool call put INTO the context; this says how long it made
+ * the user wait. Both are needed to decide what to fix first: a Read that
+ * costs 9k tokens but returns instantly is a different problem from a Bash
+ * call that costs 200 tokens and takes 40 seconds.
+ */
+function fmtMs(ms) {
+    if (ms >= 60_000)
+        return `${(ms / 60_000).toFixed(1)}m`;
+    if (ms >= 1_000)
+        return `${(ms / 1_000).toFixed(1)}s`;
+    return `${Math.round(ms)}ms`;
+}
+export function renderToolTimings(timings, top = 6) {
+    if (timings.length === 0)
+        return null;
+    const total = timings.reduce((s, t) => s + t.totalMs, 0);
+    if (total <= 0)
+        return null;
+    const lines = [];
+    lines.push("Where the time goes (tool wall clock)");
+    lines.push("─".repeat(56));
+    lines.push(`Tool calls waited ${fmtMs(total)} in total across ${timings.reduce((s, t) => s + t.calls, 0)} calls.`);
+    // MCP tool names run long (mcp__server__tool); fit the column to what is
+    // shown, capped so one long name cannot push the numbers off the screen.
+    const shown = timings.slice(0, top);
+    const width = Math.min(32, Math.max(...shown.map((t) => t.tool.length)));
+    const name = (tool) => (tool.length > width ? tool.slice(0, width - 1) + "…" : tool).padEnd(width);
+    for (const t of shown) {
+        const share = Math.round((t.totalMs / total) * 100);
+        lines.push(`  ${name(t.tool)} ${fmtMs(t.totalMs).padStart(7)}  ${String(share).padStart(3)}%  ` +
+            `${String(t.calls).padStart(4)} calls · median ${fmtMs(t.medianMs)} · slowest ${fmtMs(t.maxMs)}`);
+    }
+    if (timings.length > top)
+        lines.push(`  … and ${timings.length - top} more tool(s)`);
+    // The caveat has to travel with the number or the number lies.
+    lines.push("Measured from tool_use to tool_result timestamps. Includes any time spent waiting on a");
+    lines.push("permission prompt, so interactive sessions read slower than unattended ones.");
+    return lines.join("\n");
+}

package/package.json

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