context-doctor 0.11.0 → 0.12.1

package/README.md

@@ -34,7 +34,7 @@ Findings (4)
 npx context-doctor install
 ```
 
-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 18+):
+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
 npm install -g context-doctor && context-doctor install
@@ -89,7 +89,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; `--strategy prune-history` for consented lossy compaction |
+| `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 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 |
@@ -261,8 +261,11 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 | `dedupe` — replace repeated content with a reference | No | ✅ |
 | `trim-tool-results` — truncate stale tool outputs | Mostly no | ✅ |
 | `strip-base64` — remove inline binary blobs | No (for the model) | ✅ |
+| `trim-tool-calls` — shrink the arguments of calls that already ran | Mostly no | opt-in |
 | `prune-history` — collapse old turns into a stub for summarization | Yes | opt-in |
 
+`trim-tool-calls` is the big one for agent sessions. Writing a file through a tool call puts the entire file in context permanently, so in file-heavy work the calls outweigh every tool result combined — on a real 278k-token session, the default set reached 248k and adding `trim-tool-calls` reached 102k. It is opt-in because it edits what the model itself wrote.
+
 Everything the optimizer does is inspectable: it prints exactly which messages changed and how many tokens each change saved.
 
 **Summarization without an API key:** when `prune-history` runs through the MCP tools, context-doctor hands a digest of the pruned turns back to the model that called it (the Claude/GPT already running in your app) and asks *it* to write the replacement summary — LLM-quality compaction, zero extra cost, no keys.

package/dist/blob.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Inline base64 detection, shared by the profiler and the optimizer.
+ *
+ * A charset match alone is not enough: `"a".repeat(5000)` is valid base64
+ * alphabet, and so are long hex digests, IDs and minified identifiers. Calling
+ * those "base64" makes the profiler wrong and — far worse — makes the
+ * `strip-base64` strategy DELETE real content. So a candidate must also look
+ * like encoded binary: spanning most of the 64-symbol alphabet, with no single
+ * character dominating.
+ */
+export declare const BASE64_PLACEHOLDER = "[context-doctor: base64 blob removed \u2014 use file/image APIs instead]";
+/** True when the text carries at least one inline base64 blob. */
+export declare function hasBase64Blob(text: string): boolean;
+/** Replace real base64 blobs with a placeholder, leaving lookalikes intact. */
+export declare function stripBase64Blobs(text: string): string;

package/dist/blob.js

@@ -0,0 +1,44 @@
+/**
+ * Inline base64 detection, shared by the profiler and the optimizer.
+ *
+ * A charset match alone is not enough: `"a".repeat(5000)` is valid base64
+ * alphabet, and so are long hex digests, IDs and minified identifiers. Calling
+ * those "base64" makes the profiler wrong and — far worse — makes the
+ * `strip-base64` strategy DELETE real content. So a candidate must also look
+ * like encoded binary: spanning most of the 64-symbol alphabet, with no single
+ * character dominating.
+ */
+/** Runs of base64 alphabet long enough to be worth reporting (~375 bytes+). */
+const BASE64_RE = /(?:data:[\w/+.-]+;base64,)?[A-Za-z0-9+/]{500,}={0,2}/g;
+export const BASE64_PLACEHOLDER = "[context-doctor: base64 blob removed — use file/image APIs instead]";
+/** Distinct characters a genuine base64 payload is expected to span. */
+const MIN_DISTINCT_CHARS = 24;
+/** Above this share for one character, the run is padding or repetition. */
+const MAX_SINGLE_CHAR_SHARE = 0.35;
+function isBase64Blob(candidate) {
+    // An explicit data: URI declares its own encoding — no need to guess.
+    if (candidate.startsWith("data:"))
+        return true;
+    const counts = new Map();
+    for (const ch of candidate)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    if (counts.size < MIN_DISTINCT_CHARS)
+        return false;
+    let max = 0;
+    for (const n of counts.values())
+        if (n > max)
+            max = n;
+    return max / candidate.length < MAX_SINGLE_CHAR_SHARE;
+}
+/** True when the text carries at least one inline base64 blob. */
+export function hasBase64Blob(text) {
+    for (const m of text.matchAll(BASE64_RE)) {
+        if (isBase64Blob(m[0]))
+            return true;
+    }
+    return false;
+}
+/** Replace real base64 blobs with a placeholder, leaving lookalikes intact. */
+export function stripBase64Blobs(text) {
+    return text.replace(BASE64_RE, (m) => (isBase64Blob(m) ? BASE64_PLACEHOLDER : m));
+}

package/dist/cli.js

@@ -71,7 +71,8 @@ Options:
                           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
+                          Available: dedupe, trim-tool-results, trim-tool-calls, strip-base64,
+                          prune-history
                           Default: dedupe, trim-tool-results, strip-base64 (lossless-ish set)
   --keep-recent <n>       (optimize) Messages at the tail to leave untouched (default 6)
   --max-tool-tokens <n>   (optimize) Token budget for trimmed tool results (default 300)

package/dist/doctor.js

@@ -26,12 +26,24 @@ function checkMcpEntry(appName, configPath) {
         const entry = config.mcpServers?.["context-doctor"];
         if (!entry)
             return { label: appName, status: "fail", detail: `no context-doctor entry in ${configPath} — run: context-doctor install` };
-        // Absolute-path entries must point at a file that still exists.
-        const target = entry.command === "npx" ? null : entry.args?.[0];
+        // Absolute-path entries must point at a file that still exists. Launcher
+        // forms (npx, and Windows' cmd /c npx) resolve at spawn time, not now.
+        const launcher = entry.command === "npx" || entry.command === "cmd";
+        const target = launcher ? null : entry.args?.[0];
         if (target && !existsSync(target)) {
             return { label: appName, status: "fail", detail: `MCP entry points at missing file ${target} — re-run: context-doctor install` };
         }
-        return { label: appName, status: "ok", detail: `MCP wired (${entry.command === "npx" ? "npx, tracks npm releases" : "local build"})` };
+        // Configs written before 0.12 pinned the exact node binary, which a Node
+        // upgrade removes; the app then silently loses the tools.
+        const cmd = String(entry.command ?? "");
+        if (cmd.includes("/") && !existsSync(cmd)) {
+            return {
+                label: appName,
+                status: "fail",
+                detail: `MCP command ${cmd} no longer exists (a Node upgrade moves version-pinned paths) — re-run: context-doctor install`,
+            };
+        }
+        return { label: appName, status: "ok", detail: `MCP wired (${launcher ? "npx, tracks npm releases" : "local build"})` };
     }
     catch (e) {
         return { label: appName, status: "fail", detail: `${configPath} is not valid JSON (${e.message})` };

package/dist/install.d.ts

@@ -6,5 +6,19 @@
  * Every config edit is a careful JSON merge with a .backup file written first.
  * `context-doctor uninstall` reverses it.
  */
+/**
+ * How to invoke the published package as an MCP server on a given platform.
+ *
+ * On Windows npx is `npx.cmd` — a batch script, not an executable. MCP clients
+ * spawn their server directly, without a shell, so a bare "npx" fails with
+ * ENOENT and the app simply shows no tools and no error. Hence the cmd /c
+ * wrapper that every working Windows MCP config uses.
+ *
+ * Exported so the platform branch is testable from any host OS.
+ */
+export declare function npxLauncher(platformName: string): {
+    command: string;
+    args: string[];
+};
 export declare function runInstall(): void;
 export declare function runUninstall(): void;

package/dist/install.js

@@ -8,7 +8,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync } from "node:fs";
 import { homedir, platform } from "node:os";
-import { dirname, join } from "node:path";
+import { delimiter, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 function claudeDesktopConfigPath() {
     switch (platform()) {
@@ -28,18 +28,40 @@ function targets() {
     ];
 }
 /**
- * The server command to write into configs. When running from a published
- * install, npx keeps it auto-updating; from a local checkout, point at the
- * built file directly so it works before the package is on npm.
+ * The server command to write into configs.
+ *
+ * Never write `process.execPath`: on Homebrew, nvm and asdf that is a
+ * VERSION-PINNED path (…/node/25.6.0/bin/node), so the next Node upgrade
+ * silently breaks every config we wrote — the apps simply stop showing the
+ * tools, with no error to explain why. `node` from PATH survives upgrades.
+ *
+ * Installed from npm → npx, which also picks up package updates. Local
+ * checkout → the built file, so the repo works before/without publishing.
  */
 function serverEntry() {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     const localMcp = join(selfDir, "mcp.js");
-    const runningFromNpx = (process.env.npm_execpath ?? "").includes("npx") || selfDir.includes("_npx");
-    if (!runningFromNpx && existsSync(localMcp)) {
-        return { command: process.execPath, args: [localMcp] };
+    const fromPackage = selfDir.includes(`${sep}node_modules${sep}`) || selfDir.includes("_npx");
+    if (!fromPackage && existsSync(localMcp)) {
+        // `node` is node.exe on Windows — directly spawnable, no shell needed.
+        return { command: "node", args: [localMcp] };
     }
-    return { command: "npx", args: ["-y", "context-doctor-mcp"] };
+    return npxLauncher(platform());
+}
+/**
+ * How to invoke the published package as an MCP server on a given platform.
+ *
+ * On Windows npx is `npx.cmd` — a batch script, not an executable. MCP clients
+ * spawn their server directly, without a shell, so a bare "npx" fails with
+ * ENOENT and the app simply shows no tools and no error. Hence the cmd /c
+ * wrapper that every working Windows MCP config uses.
+ *
+ * Exported so the platform branch is testable from any host OS.
+ */
+export function npxLauncher(platformName) {
+    return platformName === "win32"
+        ? { command: "cmd", args: ["/c", "npx", "-y", "context-doctor-mcp"] }
+        : { command: "npx", args: ["-y", "context-doctor-mcp"] };
 }
 function readJson(path) {
     if (!existsSync(path))
@@ -57,17 +79,68 @@ function writeJsonWithBackup(path, data) {
         copyFileSync(path, path + ".context-doctor.backup");
     writeFileSync(path, JSON.stringify(data, null, 2));
 }
-/** Shell command used for the Claude Code every-prompt hook. */
+/**
+ * Find an executable on PATH without shelling out (works on Windows too).
+ * Used to prefer a global `context-doctor` install for the hook: a stable
+ * location that survives both package updates and Node upgrades.
+ */
+function binOnPath(name) {
+    const exts = platform() === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = join(dir, name + ext);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Shell command used for the Claude Code every-prompt hook.
+ *
+ * The hook runs on EVERY prompt, so the command must be both fast and durable.
+ * In preference order:
+ *   1. a local checkout's built cli.js — absolute, stable, zero resolution cost;
+ *   2. a global `context-doctor` binary on PATH — same, for npm -g installs;
+ *   3. `npx -y context-doctor hook` — last resort.
+ *
+ * Critically, a path inside npx's `_npx` cache is NEVER written: npm garbage-
+ * collects that directory, and the hook would then fail silently on every
+ * prompt. `node` (not process.execPath) keeps it alive across Node upgrades.
+ */
 function hookCommand() {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     const localCli = join(selfDir, "cli.js");
-    const runningFromNpx = (process.env.npm_execpath ?? "").includes("npx") || selfDir.includes("_npx");
-    if (!runningFromNpx && existsSync(localCli)) {
-        return `"${process.execPath}" "${localCli}" hook`;
-    }
+    const ephemeral = selfDir.includes("_npx");
+    if (!ephemeral && existsSync(localCli))
+        return `node "${localCli}" hook`;
+    const global = binOnPath("context-doctor");
+    if (global)
+        return `"${global}" hook`;
     return "npx -y context-doctor hook";
 }
+/** True when the hook had to fall back to npx — worth telling the user. */
+function hookUsesNpx() {
+    return hookCommand().startsWith("npx ");
+}
 const HOOK_MARKER = "context-doctor";
+/**
+ * Is this settings.json hook entry ours?
+ *
+ * Usually the command contains "context-doctor" (npx form, or a path through
+ * the package directory). A repo cloned into a differently-named folder does
+ * not, so a command ending in `cli.js hook` counts too — specific enough not
+ * to claim an unrelated hook.
+ */
+function isOurHookEntry(entry) {
+    const raw = JSON.stringify(entry ?? "");
+    if (raw.includes(HOOK_MARKER))
+        return true;
+    const command = String(entry?.hooks?.[0]?.command ?? "");
+    return /(cli\.js|context-doctor(\.cmd|\.exe|\.bat)?)"?\s+hook\s*$/.test(command);
+}
 /**
  * Register the UserPromptSubmit hook in ~/.claude/settings.json so EVERY
  * Claude Code query gets a context-size check. Idempotent.
@@ -79,12 +152,28 @@ function installHook() {
     const settings = readJson(settingsPath);
     settings.hooks = settings.hooks ?? {};
     const entries = settings.hooks.UserPromptSubmit ?? [];
-    const already = entries.some((e) => JSON.stringify(e).includes(HOOK_MARKER));
-    if (!already) {
-        entries.push({ hooks: [{ type: "command", command: hookCommand() }] });
-        settings.hooks.UserPromptSubmit = entries;
+    const want = hookCommand();
+    // Re-running install must REPAIR a stale entry, not skip it. Earlier versions
+    // wrote a version-pinned node binary; if we only checked "is it present?" an
+    // upgrade would leave that broken command in place forever.
+    const ours = entries.filter(isOurHookEntry);
+    const current = ours[0]?.hooks?.[0]?.command;
+    if (ours.length === 0) {
+        entries.push({ hooks: [{ type: "command", command: want }] });
+    }
+    else if (current !== want) {
+        // Replace every entry of ours with exactly one correct entry.
+        const others = entries.filter((e) => !isOurHookEntry(e));
+        others.push({ hooks: [{ type: "command", command: want }] });
+        settings.hooks.UserPromptSubmit = others;
         writeJsonWithBackup(settingsPath, settings);
+        return settingsPath;
     }
+    else {
+        return settingsPath; // already correct — leave the file untouched
+    }
+    settings.hooks.UserPromptSubmit = entries;
+    writeJsonWithBackup(settingsPath, settings);
     return settingsPath;
 }
 function uninstallHook() {
@@ -95,7 +184,7 @@ function uninstallHook() {
     const entries = settings.hooks?.UserPromptSubmit;
     if (!entries)
         return;
-    const filtered = entries.filter((e) => !JSON.stringify(e).includes(HOOK_MARKER));
+    const filtered = entries.filter((e) => !isOurHookEntry(e));
     if (filtered.length !== entries.length) {
         settings.hooks.UserPromptSubmit = filtered;
         if (filtered.length === 0)
@@ -128,6 +217,7 @@ export function runInstall() {
         try {
             const config = readJson(target.configPath);
             config.mcpServers = config.mcpServers ?? {};
+            // Always overwrite: re-running install is how a stale entry gets repaired.
             config.mcpServers["context-doctor"] = entry;
             writeJsonWithBackup(target.configPath, config);
             console.log(`✓ ${target.name}: MCP server added (${target.configPath})`);
@@ -140,8 +230,14 @@ export function runInstall() {
     if (skillPath)
         console.log(`✓ Agent Skill installed for Claude Code (${skillPath})`);
     const hookPath = installHook();
-    if (hookPath)
+    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.');
 }

package/dist/mcp.js

@@ -30,14 +30,14 @@ import { recordLedger } from "./ledger.js";
 // Kept deliberately terse: these ride in EVERY conversation's context, and a
 // context-saving tool must not itself be context overhead (~110 tokens).
 const SERVER_INSTRUCTIONS = `Context hygiene, always: summarize large pastes/tool results instead of carrying them verbatim; reference earlier content, don't re-quote; never inline base64. Past ~30 turns or several large pastes, proactively offer to run profile_context. Any question about tokens, cost, or latency: call profile_context, don't estimate. If optimize_context returns a pruned-turns digest, you write the ≤150-token replacement summary.`;
-const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-history"];
+const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-base64", "prune-history"];
 /**
  * Build a fully-configured server instance. A factory (not a singleton) so the
  * stateless HTTP mode can hand every request its own server, per the MCP SDK's
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.11.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.12.1" }, { 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"),
@@ -48,7 +48,7 @@ function createServer() {
     server.tool("optimize_context", "Rewrite a conversation to reclaim tokens using deterministic strategies: dedupe repeated content, trim stale tool results, strip base64 blobs, optionally prune old history. Returns the slimmed conversation JSON plus a savings summary. No LLM calls — safe and inspectable. Call this after profile_context finds recoverable waste and the user wants it fixed; add the prune-history strategy only with the user's consent, then write the replacement summary yourself as the result instructs.", {
         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 prune-history for lossy compaction of old turns."),
+            .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)"),
         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 }) => {

package/dist/optimize.d.ts

@@ -6,12 +6,12 @@
  * Strategies operate on the ORIGINAL JSON structure (not the normalized view)
  * so the output is a drop-in replacement for the input conversation.
  */
-export type StrategyId = "dedupe" | "trim-tool-results" | "prune-history" | "strip-base64";
+export type StrategyId = "dedupe" | "trim-tool-results" | "trim-tool-calls" | "prune-history" | "strip-base64";
 export interface OptimizeOptions {
     strategies?: StrategyId[];
     /** Tool results older than this many messages from the end get trimmed. */
     keepRecent?: number;
-    /** Max tokens a trimmed tool result keeps. */
+    /** Max tokens a trimmed tool result — or tool-call argument set — keeps. */
     maxToolResultTokens?: number;
 }
 export interface AppliedChange {

package/dist/optimize.js

@@ -8,12 +8,36 @@
  */
 import { createHash } from "node:crypto";
 import { estimateTokens } from "./tokens.js";
+import { hasBase64Blob, stripBase64Blobs } from "./blob.js";
 const DEFAULTS = {
     strategies: ["dedupe", "trim-tool-results", "strip-base64"],
     keepRecent: 6,
     maxToolResultTokens: 300,
 };
-const BASE64_RE = /(?:data:[\w/+.-]+;base64,)?[A-Za-z0-9+/]{500,}={0,2}/g;
+/**
+ * Shrink the arguments of a tool call that has already run.
+ *
+ * In file-heavy agent sessions the biggest single items in context are not
+ * tool RESULTS but tool CALLS: a Write or a `cat > file <<EOF` carries the
+ * whole file inline, forever. Once the call has returned, the live context
+ * only needs enough of the arguments to identify what was done.
+ *
+ * Keys are preserved (so the call still reads as itself) and only long string
+ * values are cut, with an explicit marker so nothing looks silently complete.
+ */
+function trimCallArguments(input, maxTokens) {
+    const budgetChars = maxTokens * 4;
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (typeof value === "string" && value.length > budgetChars) {
+            out[key] = value.slice(0, budgetChars) + `\n[context-doctor: ${value.length - budgetChars} more chars trimmed — this call already ran]`;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
 function hash(text) {
     return createHash("sha1").update(text.replace(/\s+/g, " ").trim()).digest("hex");
 }
@@ -109,11 +133,10 @@ export function optimizeConversation(input, options = {}) {
     if (opts.strategies.includes("strip-base64")) {
         messages.forEach((m, i) => {
             const text = textOf(m.content);
-            if (!BASE64_RE.test(text))
+            if (!hasBase64Blob(text))
                 return;
-            BASE64_RE.lastIndex = 0;
             const before = estimateTokens(text);
-            const cleaned = text.replace(BASE64_RE, "[context-doctor: base64 blob removed — use file/image APIs instead]");
+            const cleaned = stripBase64Blobs(text);
             const saved = before - estimateTokens(cleaned);
             if (saved > 50) {
                 m.content = replaceText(m.content, cleaned);
@@ -159,6 +182,46 @@ export function optimizeConversation(input, options = {}) {
             });
         });
     }
+    // -- trim-tool-calls: shrink the arguments of calls that already ran ----------
+    if (opts.strategies.includes("trim-tool-calls")) {
+        const cutoff = messages.length - opts.keepRecent;
+        messages.forEach((m, i) => {
+            if (i >= cutoff)
+                return;
+            let saved = 0;
+            // Anthropic shape: tool_use blocks with a structured `input`.
+            if (Array.isArray(m.content)) {
+                for (const b of m.content) {
+                    if (b?.type !== "tool_use" || b.input == null || typeof b.input !== "object")
+                        continue;
+                    const before = estimateTokens(JSON.stringify(b.input));
+                    if (before <= opts.maxToolResultTokens)
+                        continue;
+                    b.input = trimCallArguments(b.input, opts.maxToolResultTokens);
+                    saved += before - estimateTokens(JSON.stringify(b.input));
+                }
+            }
+            // OpenAI shape: tool_calls[].function.arguments is a JSON string.
+            for (const tc of m.tool_calls ?? []) {
+                const args = tc?.function?.arguments;
+                if (typeof args !== "string")
+                    continue;
+                const before = estimateTokens(args);
+                if (before <= opts.maxToolResultTokens)
+                    continue;
+                tc.function.arguments = truncateToTokens(args, opts.maxToolResultTokens);
+                saved += before - estimateTokens(tc.function.arguments);
+            }
+            if (saved > 0) {
+                applied.push({
+                    strategy: "trim-tool-calls",
+                    messageIndex: i,
+                    tokensSaved: saved,
+                    note: "Arguments of a completed tool call truncated",
+                });
+            }
+        });
+    }
     // -- prune-history: replace the older half with a stub ------------------------
     // Opt-in only: it is lossy, so it is not in the default strategy set.
     let prunedDigest;

package/dist/parse.d.ts

@@ -27,5 +27,11 @@ export interface NormalizedConversation {
     messages: NormalizedMessage[];
     /** Format detected, for reporting. */
     sourceFormat: "openai" | "anthropic" | "array" | "text";
+    /**
+     * Set when the input could not be read as a conversation. Silently profiling
+     * a broken file as one big "user message" produces a confident, wrong report
+     * — the caller should show this instead.
+     */
+    parseWarning?: string;
 }
 export declare function parseConversation(input: string): NormalizedConversation;

package/dist/parse.js

@@ -90,16 +90,30 @@ export function parseConversation(input) {
     try {
         data = JSON.parse(input);
     }
-    catch {
-        // Not JSON — treat the whole thing as one user message so profiling still works.
+    catch (e) {
+        // Not JSON — treat the whole thing as one user message so profiling still
+        // works for raw prompts. But if it LOOKS like JSON, the user handed us a
+        // broken conversation file and deserves to be told, not given a report
+        // about a single 9-token "message".
+        const head = input.trimStart()[0];
+        const parseWarning = input.trim() === ""
+            ? "Input is empty — nothing to profile."
+            : head === "{" || head === "["
+                ? `Input starts like JSON but does not parse (${e.message}). Profiling it as raw text, which is almost certainly not what you want.`
+                : undefined;
         return {
             sourceFormat: "text",
-            messages: [{ index: 0, role: "user", kind: "user", text: input, hasBinary: false }],
+            parseWarning,
+            // Empty input has no message: reporting "1 message, ~4 tokens" for it
+            // would be inventing content that is not there.
+            messages: input.trim() === "" ? [] : [{ index: 0, role: "user", kind: "user", text: input, hasBinary: false }],
         };
     }
     if (Array.isArray(data)) {
+        const looksLikeMessages = data.length === 0 || data.some((m) => m && typeof m === "object" && "role" in m);
         return {
             sourceFormat: "array",
+            parseWarning: looksLikeMessages ? undefined : "This is a JSON array, but no element has a `role` field — it does not look like a conversation.",
             messages: data.map((m, i) => normalizeMessage(m, i)),
         };
     }
@@ -114,5 +128,8 @@ export function parseConversation(input) {
     messages.push(...rawMessages.map((m, i) => normalizeMessage(m, i)));
     const isAnthropic = obj.system != null ||
         rawMessages.some((m) => Array.isArray(m.content) && m.content.some((b) => b?.type === "tool_use" || b?.type === "tool_result"));
-    return { sourceFormat: isAnthropic ? "anthropic" : "openai", messages };
+    const parseWarning = messages.length === 0
+        ? "This JSON has no `messages` array (and no `system`) — it does not look like a conversation. Expected {\"messages\":[{\"role\":…,\"content\":…}]}."
+        : undefined;
+    return { sourceFormat: isAnthropic ? "anthropic" : "openai", parseWarning, messages };
 }

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" | "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" | "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";
@@ -51,5 +51,7 @@ export interface ContextProfile {
     /** Present when the model has a known price. All figures are estimates. */
     cost?: CostEstimate;
     sourceFormat: string;
+    /** Propagated from parsing: input could not be read as a conversation. */
+    parseWarning?: string;
 }
 export declare function profileConversation(conv: NormalizedConversation, model?: string): ContextProfile;

package/dist/profile.js

@@ -5,6 +5,7 @@
 import { createHash } from "node:crypto";
 import { contextWindowFor, estimateTokens, MESSAGE_OVERHEAD_TOKENS, providerFor } from "./tokens.js";
 import { estimatedTtftSeconds, inputCostUsd, pricingFor } from "./pricing.js";
+import { hasBase64Blob } from "./blob.js";
 function categoryOf(m) {
     switch (m.kind) {
         case "system": return "system";
@@ -56,7 +57,6 @@ function preview(text, len = 90) {
 function contentHash(text) {
     return createHash("sha1").update(text.replace(/\s+/g, " ").trim()).digest("hex");
 }
-const BASE64_RE = /(?:data:[\w/+.-]+;base64,|[A-Za-z0-9+/]{500,}={0,2})/;
 /** FNV-1a — cheap deterministic hash for shingle sampling. */
 function fnv1a(s) {
     let h = 0x811c9dc5;
@@ -121,6 +121,24 @@ export function profileConversation(conv, model) {
             });
         }
     }
+    // -- Large individual tool calls --------------------------------------------
+    // Writing a file through a tool call puts the ENTIRE file contents in the
+    // context permanently, and in file-heavy agent sessions these outweigh every
+    // tool result put together. Unlike a result, the argument cannot be trimmed
+    // before the call — but once the call has returned, the live context only
+    // needs a reference to what was written.
+    for (const p of perMessage) {
+        if (p.msg.kind === "tool_call" && p.tokens > 2000) {
+            findings.push({
+                id: "large_tool_call",
+                severity: p.tokens > 8000 ? "high" : "warn",
+                estSavings: Math.round(p.tokens * 0.8),
+                message: `Tool call at message #${p.msg.index}${p.msg.toolName ? ` (${p.msg.toolName})` : ""} carries ~${p.tokens} tokens of arguments.`,
+                suggestion: "Usually a whole file being written inline. Once it has run, replace the arguments with a reference (\"wrote <path>\") — or write files in smaller pieces so no single call carries the entire content.",
+                messages: [p.msg.index],
+            });
+        }
+    }
     // -- Exact duplicate content ------------------------------------------------
     const seen = new Map();
     for (const p of perMessage) {
@@ -259,7 +277,7 @@ export function profileConversation(conv, model) {
     }
     // -- Base64 / binary blobs ---------------------------------------------------
     for (const p of perMessage) {
-        if (BASE64_RE.test(p.msg.text)) {
+        if (hasBase64Blob(p.msg.text)) {
             findings.push({
                 id: "base64_blob",
                 severity: "high",
@@ -359,5 +377,6 @@ export function profileConversation(conv, model) {
         totalEstSavings,
         cost,
         sourceFormat: conv.sourceFormat,
+        parseWarning: conv.parseWarning,
     };
 }

package/dist/report.js

@@ -29,6 +29,13 @@ export function renderProfile(profile, options = {}) {
     const p = profile;
     lines.push("CONTEXT DOCTOR — profile");
     lines.push("═".repeat(56));
+    // A malformed or non-conversation input still profiles (as raw text), but a
+    // report that does not say so reads as a confident answer to the wrong
+    // question. Lead with the warning.
+    if (p.parseWarning) {
+        lines.push(`⚠ ${p.parseWarning}`);
+        lines.push("");
+    }
     lines.push(`Total: ~${formatTokens(p.totalTokens)} tokens across ${p.messageCount} messages (${p.sourceFormat} format)`);
     if (p.model) {
         const windowNote = p.contextWindow
@@ -67,10 +74,32 @@ export function renderProfile(profile, options = {}) {
     if (p.findings.length > 0) {
         lines.push(`Findings (${p.findings.length})`);
         lines.push("─".repeat(56));
+        // A file-heavy session can produce a dozen findings of one kind, each with
+        // the same advice. Printing them all buries the other kinds, so show the
+        // worst few per kind and total the rest into one line.
+        const MAX_PER_KIND = 3;
+        const shownPerKind = new Map();
+        const heldPerKind = new Map();
         for (const f of p.findings) {
+            const shown = shownPerKind.get(f.id) ?? 0;
+            if (shown >= MAX_PER_KIND) {
+                const held = heldPerKind.get(f.id) ?? { count: 0, savings: 0 };
+                heldPerKind.set(f.id, { count: held.count + 1, savings: held.savings + f.estSavings });
+                continue;
+            }
+            shownPerKind.set(f.id, shown + 1);
             const savings = f.estSavings > 0 ? ` [save ~${formatTokens(f.estSavings)}]` : "";
             lines.push(`${SEVERITY_MARK[f.severity]} ${options.redact ? redactText(f.message) : f.message}${savings}`);
             lines.push(`   → ${f.suggestion}`);
+            const held = heldPerKind.get(f.id);
+            if (shown + 1 === MAX_PER_KIND && held === undefined)
+                heldPerKind.set(f.id, { count: 0, savings: 0 });
+        }
+        for (const [id, held] of heldPerKind) {
+            if (held.count === 0)
+                continue;
+            const more = held.savings > 0 ? `, ~${formatTokens(held.savings)} more recoverable` : "";
+            lines.push(`  … and ${held.count} more of the same kind (${id})${more}. Use --json for the full list.`);
         }
         lines.push("");
         if (p.totalEstSavings > 0) {

package/dist/session.js

@@ -8,7 +8,8 @@
  * where `message` is in Anthropic Messages format. Everything else
  * (titles, mode changes, hook records) is metadata and skipped.
  */
-import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { readdirSync, readFileSync, statSync, existsSync, openSync, readSync, closeSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
 import { homedir } from "node:os";
 import { join } from "node:path";
 function projectsDir() {
@@ -72,12 +73,60 @@ function parseChatGPTExport(data, path) {
         path,
     };
 }
+/**
+ * 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.
+ */
+function forEachLine(path, onLine) {
+    const fd = openSync(path, "r");
+    const decoder = new StringDecoder("utf8");
+    const buf = Buffer.allocUnsafe(4 * 1024 * 1024);
+    let pending = "";
+    try {
+        for (;;) {
+            const bytes = readSync(fd, buf, 0, buf.length, null);
+            if (bytes === 0)
+                break;
+            pending += decoder.write(buf.subarray(0, bytes));
+            let nl;
+            while ((nl = pending.indexOf("\n")) !== -1) {
+                onLine(pending.slice(0, nl));
+                pending = pending.slice(nl + 1);
+            }
+        }
+        pending += decoder.end();
+        if (pending)
+            onLine(pending);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Peek at the first bytes to tell a ChatGPT export (JSON array) from JSONL. */
+function startsWithArray(path) {
+    const fd = openSync(path, "r");
+    try {
+        const buf = Buffer.allocUnsafe(64);
+        const bytes = readSync(fd, buf, 0, 64, 0);
+        return buf.subarray(0, bytes).toString("utf8").trimStart().startsWith("[");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function parseSessionFile(path) {
-    const raw = readFileSync(path, "utf8");
-    // ChatGPT exports are one big JSON array, not JSONL.
-    if (raw.trimStart().startsWith("[")) {
+    // 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.
+    if (startsWithArray(path)) {
         try {
-            const data = JSON.parse(raw);
+            const data = JSON.parse(readFileSync(path, "utf8"));
             if (Array.isArray(data) && data.some((c) => c && typeof c.mapping === "object")) {
                 return parseChatGPTExport(data, path);
             }
@@ -93,15 +142,15 @@ export function parseSessionFile(path) {
     let lastCompactIndex = -1;
     /** Newest API-reported input size, if the transcript carries usage. */
     let reportedInputTokens;
-    for (const line of raw.split("\n")) {
+    forEachLine(path, (line) => {
         if (!line.trim())
-            continue;
+            return;
         let entry;
         try {
             entry = JSON.parse(line);
         }
         catch {
-            continue;
+            return;
         }
         // Titles are metadata lines; the last one wins.
         if (entry.type === "custom-title" && entry.customTitle)
@@ -109,12 +158,12 @@ export function parseSessionFile(path) {
         if (entry.type === "ai-title" && entry.aiTitle && !title)
             title = entry.aiTitle;
         if ((entry.type !== "user" && entry.type !== "assistant") || !entry.message)
-            continue;
+            return;
         if (entry.isSidechain)
-            continue; // subagent traffic has its own context window
+            return; // subagent traffic has its own context window
         const message = entry.message;
         if (!message.role || message.content == null)
-            continue;
+            return;
         if (typeof message.model === "string")
             model = message.model;
         const usage = message.usage;
@@ -126,7 +175,7 @@ export function parseSessionFile(path) {
         if (entry.isCompactSummary)
             lastCompactIndex = messages.length;
         messages.push({ role: message.role, content: message.content });
-    }
+    });
     // 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "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",
@@ -36,13 +36,13 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "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 dist/test/cache.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 dist/test/session.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/skills/context-doctor/SKILL.md

@@ -27,7 +27,7 @@ Proactively (do not wait to be asked):
 
 If the `context-doctor` MCP tools are available:
 - `profile_context` — pass a conversation JSON (OpenAI or Anthropic format) or raw text; returns a token breakdown, largest messages, findings with estimated savings.
-- `optimize_context` — applies deterministic fixes (dedupe, trim stale tool results, strip base64; opt-in `prune-history`). When the result contains pruned-turn source material and asks for a summary, **you write that summary** (≤150 tokens, dense, factual) and place it where the stub indicates — this is how summarization works without any API key.
+- `optimize_context` — applies deterministic fixes (dedupe, trim stale tool results, strip base64; opt-in `trim-tool-calls` for big inline file writes and `prune-history`). When the result contains pruned-turn source material and asks for a summary, **you write that summary** (≤150 tokens, dense, factual) and place it where the stub indicates — this is how summarization works without any API key.
 - `context_best_practices` — provider-specific checklist to share with the user.
 
 If the tools are not connected, the CLI does the same: `npx context-doctor analyze <file> --model <model>` and `npx context-doctor optimize <file>`. For always-on optimization of the user's own apps: `npx context-doctor proxy` then point `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` at it.