context-doctor 0.9.0 → 0.10.0

package/README.md

@@ -88,9 +88,10 @@ 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, the Agent Skill, the every-prompt hook |
-| `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates |
+| `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; `--strategy prune-history` for consented lossy compaction |
-| `context-doctor session [file]` | Profile a Claude Code session transcript (defaults to your most recent; `--list` to browse) — 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**. Also reads ChatGPT data exports (`conversations.json`) |
+| `context-doctor cursor [--list]` | Profile a chat from Cursor's local history (both storage formats) |
 | `context-doctor report` | Machine-wide impact report: 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 |
@@ -245,6 +246,8 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 - **Oversized tool results** — the #1 context killer in agent loops
 - **Duplicate content** — the same doc/result pasted twice
 - **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
+- **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
 - **Base64 / binary blobs** in text content
 - **Long history** past the point where models track the middle
@@ -296,6 +299,26 @@ Drop a `.contextdoctorrc` in a project (or your home directory) and context-doct
 
 The nearest file wins (walking up from the working directory, then `~`). `analyze` and `session` print a budget verdict, the every-prompt hook uses `maxTokens` as its warning threshold and names the breach to the model, and `optimize`/`proxy` pick up the defaults when you do not pass flags.
 
+## Prompt-cache economics (Claude Code sessions)
+
+Caching is the largest lever on LLM cost, and transcripts record exactly how it went — so `session` reports it as fact rather than estimate:
+
+```
+Prompt cache: 95.6% of input served from cache across 1117 requests
+  read 558.6M · written 25.5M · uncached 2k
+  input cost $438.88 — caching saved $2481.89 against $2920.76 uncached (list prices)
+```
+
+A cache read bills at ~10% of input while a write bills at ~125%, so a session that keeps invalidating its prefix can cost *more* than one with no caching at all. context-doctor warns on the two failure modes: a **low hit rate** (something early in the prompt changes every request) and **cache churn** (writes rivalling reads).
+
+## Enforce a budget in CI
+
+```bash
+npx context-doctor analyze conversation.json --fail-over-budget
+```
+
+Exits 1 when the `.contextdoctorrc` budget is breached, so a pull request can be gated on context size the same way it is gated on tests.
+
 ## Performance: what context-doctor itself costs
 
 A tool that promises speed must be near-free. Measured overhead per touchpoint:
@@ -344,6 +367,10 @@ Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doc
 
 Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, and remember `dist/` is committed — run `npm run build` before committing so the CI dist-sync check passes.
 
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the six rules that keep this tool trustworthy (no API keys, nothing leaves the machine, no silent data loss, measurements not guesses, the hot path stays cheap, tests with every change) and a list of good first issues. What is planned next lives in [ROADMAP.md](./ROADMAP.md).
+
 ## License
 
 MIT © [gAI Ventures](https://gai.ventures)

package/dist/cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt-cache analysis for Claude Code sessions.
+ *
+ * Transcripts record what the API actually charged per request — including
+ * cache reads and cache writes — so cache behaviour can be reported as fact
+ * rather than estimated. This is usually the largest single lever on cost:
+ * a cached read bills at ~10% of input, while a cache write bills at ~125%,
+ * so a session that keeps invalidating its prefix pays more than one with no
+ * caching at all.
+ */
+export interface CacheUsage {
+    requests: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    uncachedTokens: number;
+    /** Share of input tokens served from cache (0-1). */
+    hitRate: number;
+    model?: string;
+    /** What the input actually cost, at list prices. */
+    paidUsd?: number;
+    /** What the same input would have cost with no caching at all. */
+    uncachedUsd?: number;
+    /** paidUsd vs uncachedUsd — positive means caching is paying off. */
+    savedUsd?: number;
+    /** USD spent on cache writes; high values mean the prefix keeps changing. */
+    writeUsd?: number;
+}
+export declare function analyzeCacheUsage(transcriptPath: string): CacheUsage | null;
+/** One-paragraph verdict for humans, or null when there is nothing to say. */
+export declare function renderCacheReport(usage: CacheUsage | null): string | null;

package/dist/cache.js

@@ -0,0 +1,97 @@
+/**
+ * Prompt-cache analysis for Claude Code sessions.
+ *
+ * Transcripts record what the API actually charged per request — including
+ * cache reads and cache writes — so cache behaviour can be reported as fact
+ * rather than estimated. This is usually the largest single lever on cost:
+ * a cached read bills at ~10% of input, while a cache write bills at ~125%,
+ * so a session that keeps invalidating its prefix pays more than one with no
+ * caching at all.
+ */
+import { readFileSync } from "node:fs";
+import { pricingFor } from "./pricing.js";
+/** Cache pricing multipliers relative to the base input rate. */
+const CACHE_WRITE_MULTIPLIER = 1.25;
+export function analyzeCacheUsage(transcriptPath) {
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let requests = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    let uncachedTokens = 0;
+    let model;
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.type !== "assistant" || !entry.message)
+            continue;
+        const usage = entry.message.usage;
+        if (!usage)
+            continue;
+        requests++;
+        cacheReadTokens += usage.cache_read_input_tokens ?? 0;
+        cacheWriteTokens += usage.cache_creation_input_tokens ?? 0;
+        uncachedTokens += usage.input_tokens ?? 0;
+        if (typeof entry.message.model === "string")
+            model = entry.message.model;
+    }
+    if (requests === 0)
+        return null;
+    const totalInput = cacheReadTokens + cacheWriteTokens + uncachedTokens;
+    const usage = {
+        requests,
+        cacheReadTokens,
+        cacheWriteTokens,
+        uncachedTokens,
+        hitRate: totalInput > 0 ? cacheReadTokens / totalInput : 0,
+        model,
+    };
+    const pricing = pricingFor(model);
+    if (pricing) {
+        const perM = (tokens, rate) => (tokens / 1_000_000) * rate;
+        const readUsd = perM(cacheReadTokens, pricing.cacheReadPerM);
+        const writeUsd = perM(cacheWriteTokens, pricing.inputPerM * CACHE_WRITE_MULTIPLIER);
+        const freshUsd = perM(uncachedTokens, pricing.inputPerM);
+        usage.paidUsd = readUsd + writeUsd + freshUsd;
+        usage.uncachedUsd = perM(totalInput, pricing.inputPerM);
+        usage.savedUsd = usage.uncachedUsd - usage.paidUsd;
+        usage.writeUsd = writeUsd;
+    }
+    return usage;
+}
+/** One-paragraph verdict for humans, or null when there is nothing to say. */
+export function renderCacheReport(usage) {
+    if (!usage)
+        return null;
+    const pct = (usage.hitRate * 100).toFixed(1);
+    const lines = [];
+    const fmt = (n) => (n >= 1 ? `$${n.toFixed(2)}` : `$${n.toFixed(3)}`);
+    const tok = (n) => n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(n);
+    lines.push(`Prompt cache: ${pct}% of input served from cache across ${usage.requests} requests`);
+    lines.push(`  read ${tok(usage.cacheReadTokens)} · written ${tok(usage.cacheWriteTokens)} · uncached ${tok(usage.uncachedTokens)}`);
+    if (usage.paidUsd !== undefined && usage.uncachedUsd !== undefined && usage.savedUsd !== undefined) {
+        lines.push(`  input cost ${fmt(usage.paidUsd)} — caching saved ${fmt(usage.savedUsd)} against ${fmt(usage.uncachedUsd)} uncached (list prices)`);
+    }
+    // A cache write costs 1.25x input while a read costs 0.1x, so writes that
+    // rival reads mean the prefix keeps changing and caching is losing money.
+    const writeShare = usage.cacheReadTokens > 0 ? usage.cacheWriteTokens / usage.cacheReadTokens : Infinity;
+    if (usage.hitRate < 0.5 && usage.requests > 5) {
+        lines.push("  ⚠ Low hit rate: something early in the prompt changes between requests. Keep the system prompt, tool list and reference docs byte-stable and put volatile content last.");
+    }
+    else if (writeShare > 0.5) {
+        lines.push("  ⚠ Cache churn: writes are large relative to reads, and a write costs 1.25x input against 0.1x for a read. The cached prefix is being rebuilt often.");
+    }
+    return lines.join("\n");
+}

package/dist/cli.js

@@ -26,6 +26,7 @@ import { exactTokenCount } from "./exact.js";
 import { checkBudget, loadConfig } from "./config.js";
 import { startDashboard } from "./dashboard.js";
 import { listCursorChats, parseCursorChat } from "./cursor.js";
+import { analyzeCacheUsage, renderCacheReport } from "./cache.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -64,6 +65,8 @@ Options:
   --exact                 (analyze) Add an exact token count: Anthropic count-tokens API for
                           Claude models (needs ANTHROPIC_API_KEY), tiktoken for GPT (if installed)
   --json                  Machine-readable output
+  --fail-over-budget      (analyze/session) Exit 1 when the .contextdoctorrc budget is
+                          exceeded — lets CI gate a pull request on context size
   --out <file>            (optimize) Write result to file instead of stdout
   --strategy <id>         (optimize) Strategy to run; repeatable.
                           Available: dedupe, trim-tool-results, strip-base64, prune-history
@@ -86,7 +89,7 @@ Examples:
           export OPENAI_BASE_URL=http://localhost:8787/v1
 `;
 function parseArgs(argv) {
-    const args = { json: false, strategies: [], list: false, exact: false };
+    const args = { json: false, strategies: [], list: false, exact: false, failOverBudget: false };
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -104,6 +107,9 @@ function parseArgs(argv) {
             case "--exact":
                 args.exact = true;
                 break;
+            case "--fail-over-budget":
+                args.failOverBudget = true;
+                break;
             case "--model":
                 args.model = argv[++i];
                 break;
@@ -148,7 +154,7 @@ function parseArgs(argv) {
 function printBudgetStatus(profile, loaded) {
     const budget = loaded.config.budget;
     if (!budget || !loaded.path)
-        return;
+        return false;
     const verdict = checkBudget(budget, profile);
     console.log("");
     if (verdict.overBudget) {
@@ -159,6 +165,14 @@ function printBudgetStatus(profile, loaded) {
     else {
         console.log(`Within budget (${loaded.path}).`);
     }
+    return verdict.overBudget;
+}
+/** Exit 1 when the caller asked CI to fail on a breach. */
+function applyBudgetGate(overBudget, failOverBudget) {
+    if (overBudget && failOverBudget) {
+        console.error("context-doctor: over budget (--fail-over-budget)");
+        process.exitCode = 1;
+    }
 }
 function readInput(file) {
     if (file === "-")
@@ -269,7 +283,12 @@ 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.");
             }
-            printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`)));
+            const cache = renderCacheReport(analyzeCacheUsage(path));
+            if (cache) {
+                console.log("");
+                console.log(cache);
+            }
+            applyBudgetGate(printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`))), args.failOverBudget);
         }
         return;
     }
@@ -322,7 +341,9 @@ function main() {
         const profile = profileConversation(parseConversation(input), args.model ?? loaded.config.model);
         console.log(args.json ? JSON.stringify(profile, null, 2) : renderProfile(profile));
         if (!args.json)
-            printBudgetStatus(profile, loaded);
+            applyBudgetGate(printBudgetStatus(profile, loaded), args.failOverBudget);
+        else
+            applyBudgetGate(checkBudget(loaded.config.budget, profile).overBudget, args.failOverBudget);
         if (args.exact) {
             void exactTokenCount(input, args.model).then((exact) => {
                 if (exact.tokens !== undefined) {

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-hist
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.9.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.10.0" }, { 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/profile.d.ts

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

package/dist/profile.js

@@ -194,6 +194,58 @@ export function profileConversation(conv, model) {
             });
         }
     }
+    // -- Same file read again and again -----------------------------------------
+    // The dominant waste in agent loops: a file re-read because its earlier
+    // contents scrolled out of attention, leaving several full copies in context.
+    {
+        const readsByPath = new Map();
+        for (const p of perMessage) {
+            if (p.msg.kind !== "tool_call" || !p.msg.toolCallText)
+                continue;
+            if (!/read|open|cat|view|get_file/i.test(p.msg.toolName ?? ""))
+                continue;
+            const match = /"(?:file_path|filePath|path|file)"\s*:\s*"([^"]{3,})"/.exec(p.msg.toolCallText);
+            if (!match)
+                continue;
+            const path = match[1];
+            readsByPath.set(path, [...(readsByPath.get(path) ?? []), p.msg.index]);
+        }
+        for (const [path, indexes] of readsByPath) {
+            if (indexes.length < 3)
+                continue;
+            // Each re-read pulls the file in again; all but the last are recoverable.
+            const resultTokens = perMessage
+                .filter((p) => p.msg.kind === "tool_result" && indexes.some((i) => p.msg.index === i + 1))
+                .reduce((sum, p) => sum + p.tokens, 0);
+            const savings = Math.round((resultTokens * (indexes.length - 1)) / indexes.length);
+            findings.push({
+                id: "repeated_file_read",
+                severity: savings > 4000 ? "high" : "warn",
+                estSavings: savings,
+                message: `${path.split("/").pop()} was read ${indexes.length} times (messages #${indexes.join(", #")}), keeping ${indexes.length} copies in context.`,
+                suggestion: "Re-read a file only after it changes; otherwise refer back to the copy already in context.",
+                messages: indexes,
+            });
+        }
+    }
+    // -- Failed tool output kept verbatim ---------------------------------------
+    // Stack traces and command failures are read once and never again, yet they
+    // are often the largest blocks in an agent transcript.
+    for (const p of perMessage) {
+        if (p.msg.kind !== "tool_result" || p.tokens < 500)
+            continue;
+        const looksFailed = /Traceback \(most recent call last\)|command not found|npm error|ERR!|\bexit code [1-9]|Exception in thread|FAILED|error TS\d+/i.test(p.msg.text);
+        if (!looksFailed)
+            continue;
+        findings.push({
+            id: "retained_error_output",
+            severity: "warn",
+            estSavings: Math.round(p.tokens * 0.85),
+            message: `Message #${p.msg.index} holds ~${p.tokens} tokens of failed tool output (errors, stack trace or non-zero exit).`,
+            suggestion: "Keep the one line that identifies the failure and drop the rest — a full trace has no value once the fix is understood.",
+            messages: [p.msg.index],
+        });
+    }
     // -- Base64 / binary blobs ---------------------------------------------------
     for (const p of perMessage) {
         if (BASE64_RE.test(p.msg.text)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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 run build",
     "dev": "tsc --watch",
-    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.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"
+    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.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"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",