context-doctor 0.3.4 → 0.3.5

package/README.md

@@ -246,6 +246,20 @@ Everything the optimizer does is inspectable: it prints exactly which messages c
 
 `skills/context-doctor/SKILL.md` (installed by `npx context-doctor install`) teaches Claude to practice context hygiene proactively: summarize big tool results after consuming them, never re-paste duplicated content, keep stable content cache-friendly, and offer compaction when a session gets heavy — so sessions get inherently leaner without you asking.
 
+## Performance: what context-doctor itself costs
+
+A tool that promises speed must be near-free. Measured overhead per touchpoint:
+
+| Touchpoint | When it runs | Overhead |
+|---|---|---|
+| Every-prompt hook (Claude Code) | Every prompt | **~80ms** (Node startup; logic ~1ms). Lean sessions exit on a single `stat()` — the transcript is never read. Full profiling (~200ms on a 4MB session) happens only when the transcript has grown ~40% since last checked |
+| MCP server | Spawned once per app session | Tools run only when called; standing instructions cost **~110 tokens per conversation** — deliberately terse |
+| Proxy | Per API request | ~1–3ms of CPU (parse → optimize → re-serialize) against typical model latencies of hundreds of ms; responses stream through chunk-by-chunk, never buffered |
+| Skill | Loads only when relevant | ~1k tokens while active; its always-present description is ~60 tokens |
+| CLI / library | Only when you run it | Not in any hot path |
+
+Net effect is strongly negative overhead: the tokens these touchpoints save on every subsequent call dwarf what they cost.
+
 ## Why token counts are "~"
 
 Exact counts require each provider's private tokenizer. `context-doctor` uses a calibrated chars-per-token heuristic (denser for code/JSON) that lands within ~10% — plenty accurate for finding what's heavy and measuring savings, and it keeps the tool fully offline with zero configuration.

package/dist/hook.js

@@ -10,7 +10,7 @@
  * Registered by `context-doctor install` under hooks.UserPromptSubmit in
  * ~/.claude/settings.json; removed by `context-doctor uninstall`.
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseConversation } from "./parse.js";
@@ -22,6 +22,13 @@ import { formatUsd } from "./pricing.js";
 const WARN_TOKENS = 80_000;
 /** Re-nudge only after the context grows another 40% — one reminder, not a nag. */
 const REGROWTH_FACTOR = 1.4;
+/**
+ * Fast-path gate: text tokens are at least ~4 bytes each and the transcript
+ * carries JSON overhead on top, so a file smaller than this cannot possibly
+ * hold WARN_TOKENS of context. Lean sessions cost one stat() call — the
+ * transcript is never even read.
+ */
+const MIN_BYTES_FOR_WARN = WARN_TOKENS * 4;
 function statePath() {
     return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
 }
@@ -38,13 +45,15 @@ export async function runHook() {
         const transcriptPath = input.transcript_path;
         if (!transcriptPath || !existsSync(transcriptPath))
             return;
-        const parsed = parseSessionFile(transcriptPath);
-        if (parsed.messageCount === 0)
-            return;
-        const profile = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
-        if (profile.totalTokens < WARN_TOKENS)
+        // Fast path 1: a small transcript cannot exceed the threshold — exit on a
+        // single stat() without reading the file. This is the every-prompt cost
+        // for lean sessions: ~1ms.
+        const sizeBytes = statSync(transcriptPath).size;
+        if (sizeBytes < MIN_BYTES_FOR_WARN)
             return;
-        // Per-session rate limit so the nudge fires on growth, not on every prompt.
+        // Fast path 2: growth gate BEFORE parsing. If the file hasn't grown ~40%
+        // since the last full parse, nothing new can trigger — exit without the
+        // expensive read. Heavy-but-quiet sessions cost one stat + tiny state read.
         const sessionId = input.session_id ?? transcriptPath;
         let state = {};
         try {
@@ -53,11 +62,23 @@ export async function runHook() {
         catch {
             /* first run */
         }
-        const lastWarnedAt = state[sessionId] ?? 0;
-        if (profile.totalTokens < lastWarnedAt * REGROWTH_FACTOR)
+        const rawPrev = state[sessionId];
+        // Migrate pre-0.3.5 numeric entries ({tokens only}) to the new shape.
+        const prev = typeof rawPrev === "number" ? { t: rawPrev, b: 0 } : rawPrev ?? { t: 0, b: 0 };
+        if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR)
             return;
-        const entries = Object.entries({ ...state, [sessionId]: profile.totalTokens });
+        // Slow path (growth events only): full parse + profile.
+        const parsed = parseSessionFile(transcriptPath);
+        if (parsed.messageCount === 0)
+            return;
+        const profile = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
+        // Record this parse so the next prompts take fast path 2.
+        const shouldWarn = profile.totalTokens >= WARN_TOKENS && profile.totalTokens >= prev.t * REGROWTH_FACTOR;
+        const nextState = { t: shouldWarn ? profile.totalTokens : prev.t, b: sizeBytes };
+        const entries = Object.entries({ ...state, [sessionId]: nextState });
         writeFileSync(statePath(), JSON.stringify(Object.fromEntries(entries.slice(-100))));
+        if (!shouldWarn)
+            return;
         const lines = [
             `This session's context is at ~${formatTokens(profile.totalTokens)} tokens` +
                 (profile.usagePct ? ` (${profile.usagePct.toFixed(0)}% of the window)` : "") +

package/dist/mcp.js

@@ -26,12 +26,10 @@ import { formatTokens } from "./tokens.js";
  * This is what upgrades plain-chat apps from "tools available on request" to
  * "standing context-hygiene instructions in every chat" — no hook needed.
  */
-const SERVER_INSTRUCTIONS = `context-doctor keeps this conversation's context window lean, fast, and cheap. Standing instructions for every conversation:
-1. Practice context hygiene continuously: after consuming a large tool result or pasted document, carry forward a one-sentence summary instead of re-quoting it; reference earlier content rather than repeating it; never inline base64.
-2. When the conversation has grown long (roughly 30+ turns) or contains several large pastes, proactively offer to profile it and call profile_context — do not wait to be asked.
-3. When the user asks anything about token usage, cost, latency, or "what's eating my context", call profile_context immediately rather than estimating by eye.
-4. When optimize_context returns a pruned-turns digest, YOU write the replacement summary (dense, factual, ≤150 tokens) as instructed in the result.`;
-const server = new McpServer({ name: "context-doctor", version: "0.3.4" }, { instructions: SERVER_INSTRUCTIONS });
+// 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 server = new McpServer({ name: "context-doctor", version: "0.3.5" }, { instructions: SERVER_INSTRUCTIONS });
 const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-history"];
 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"),

package/package.json

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