context-doctor 0.2.0 → 0.3.1

package/README.md

@@ -24,14 +24,37 @@ Findings (4)
 
 ## Quick start (30 seconds)
 
-**One command sets up everything** — detects Claude Desktop, Claude Code, and Cursor on your machine, wires in the MCP server, and installs the Agent Skill:
+**One command sets up everything** — detects Claude Desktop, Claude Code, and Cursor on your machine, wires in the MCP server, installs the Agent Skill, and registers the Claude Code every-prompt hook:
 
 ```bash
 npx context-doctor install
 ```
 
+Until the package lands on npm, install straight from GitHub instead (needs Node 18+):
+
+```bash
+npm install -g github:KushalP1/context-doctor && context-doctor install
+```
+
+That pair of commands is also all it takes to **set up context-doctor on anyone else's machine**.
+
 Restart your apps, then just ask Claude: *"what's eating my context?"* (`npx context-doctor uninstall` reverses it.)
 
+**No API keys, ever.** Everything is deterministic local code; when an LLM is needed (summarizing pruned history), the model already running in your app does it. The proxy forwards *your app's* credentials untouched — context-doctor itself holds nothing.
+
+## What "always-on" means, per surface
+
+| Where you run LLMs | Mechanism | Guarantee |
+|---|---|---|
+| Your own apps/agents (API) | `context-doctor proxy` rewrites every request in flight | **Every call, automatic** |
+| Claude Code / Cowork sessions | `install` registers a **UserPromptSubmit hook**: every query measures the session; heavy sessions get injected hygiene guidance (silent when lean, rate-limited, never blocks a prompt) | **Every query checked** |
+| Claude Desktop chat / Cursor | **MCP server instructions** — standing hygiene directives injected into every conversation where the server is enabled, plus prescriptive tool triggers | **Every conversation carries the rules** |
+| claude.ai (web) / ChatGPT app | Upload `skills/context-doctor/SKILL.md` in the app's Skills settings for the same standing behavior | Manual one-time upload |
+
+Nothing runs in the background for the Claude apps — the hook, skill, MCP server, and its instructions are all delivered by the app itself at the right moment. The proxy is the only long-running piece, and only your API-calling apps need it.
+
+Optional belt-and-braces for any chat app: add one line to your profile preferences — *"Practice context hygiene: summarize large content instead of re-quoting it, and use context-doctor's tools when conversations get heavy."*
+
 Or use the CLI directly, no install needed:
 
 ```bash
@@ -88,7 +111,7 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 
 > **Note on desktop chat apps:** Claude Desktop and the ChatGPT app talk to their own backends — no tool can sit in that path. For those, use the MCP integration below and add a line to your custom instructions like: *"When a conversation gets long or includes large pasted content, proactively use context-doctor's profile_context tool and tell me what to trim."* The model will then invoke it on its own.
 
-## Use it inside your AI app (MCP)
+## Use with the Claude & ChatGPT apps
 
 `context-doctor` ships an MCP server, so the AI itself can profile and slim context on demand.
 
@@ -107,7 +130,25 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 
 **ChatGPT desktop** (developer mode), **Cursor**, **Claude Code** (`claude mcp add context-doctor -- npx -y context-doctor-mcp`), and any other MCP client: same command, their config syntax.
 
-Then just ask: *"profile this conversation with context-doctor"* or paste an exported chat and say *"what's eating my context?"*
+### How it works in Claude Desktop, step by step
+
+1. Run `npx context-doctor install` (writes the config above for you) and restart Claude Desktop.
+2. From then on, **every conversation automatically carries context-doctor's standing instructions** — the MCP server hands Claude hygiene rules on connect: summarize big pastes instead of re-quoting them, offer profiling when the chat gets long, never inline base64.
+3. Chat normally. When a conversation grows heavy, Claude proactively offers: *"this chat is getting large — want me to profile it?"* — or you ask *"what's eating my context?"* and it calls `profile_context` and shows the token/cost breakdown.
+4. Say *"optimize it"* and Claude applies the safe fixes; if you agree to pruning old history, **Claude itself writes the replacement summary** (that's the no-API-key summarization).
+
+### How it works in ChatGPT, step by step
+
+1. ChatGPT's desktop app supports MCP in **developer mode**: Settings → Connectors → Advanced → Developer mode, then add a local MCP server with command `npx` and args `-y context-doctor-mcp`.
+2. Enable the connector in a chat. GPT sees the same three tools with the same trigger guidance baked into their descriptions.
+3. Ask *"profile this conversation"* or paste an exported chat and ask *"what's eating my context?"* — GPT calls `profile_context` and reports the breakdown; *"optimize it"* works the same, including GPT writing the pruning summary itself.
+4. Caveat: how prominently standing server instructions surface varies by ChatGPT version — the tool descriptions carry the trigger rules regardless, so profiling still fires on the right questions.
+
+For ChatGPT on the web (no MCP): export the conversation and use the CLI — `npx context-doctor analyze chat.json --model gpt-5`.
+
+### claude.ai on the web
+
+Your local MCP server can't reach the website, but the behavior can: upload `skills/context-doctor/SKILL.md` under Settings → Capabilities → Skills, and web conversations gain the same standing context-hygiene habits (summarize-don't-requote, offer compaction when heavy).
 
 ### MCP tools
 
@@ -172,6 +213,19 @@ Exact counts require each provider's private tokenizer. `context-doctor` uses a
 
 Contributions welcome — this project is small on purpose. Open an issue before a big PR.
 
+## Releasing (maintainers)
+
+```bash
+npm version patch        # or minor/major — bumps package.json + git tag
+npm test                 # 14 tests must pass; CI runs the same on 3 OSes
+npm publish              # prompts for the npm 2FA code
+git push --follow-tags
+```
+
+Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doctor`** on a package that clearly exists, the real cause is an **expired npm login token** — npm reports unauthenticated publishes as a 404, not a 401. Check with `npm whoami`; if that errors, run `npm login` and publish again.
+
+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.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -17,6 +17,7 @@ import { formatTokens } from "./tokens.js";
 import { startProxy } from "./proxy.js";
 import { runInstall, runUninstall } from "./install.js";
 import { listSessions, parseSessionFile } from "./session.js";
+import { runHook } from "./hook.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -29,6 +30,8 @@ Usage:
   context-doctor uninstall                      Undo install
   context-doctor session [file]                 Profile a Claude Code session transcript
                                                 (default: the most recent session; --list to browse)
+  context-doctor hook                           Claude Code UserPromptSubmit hook (installed
+                                                automatically by \`install\`; reads hook JSON on stdin)
 
 Input: a conversation JSON file (OpenAI or Anthropic message format, or a bare
 message array). Use "-" to read from stdin.
@@ -43,6 +46,7 @@ Options:
   --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)
   --port <n>              (proxy) Port to listen on (default 8787)
+  --host <addr>           (proxy) Bind address (default 127.0.0.1; use 0.0.0.0 to expose)
   --upstream-anthropic <url>  (proxy) Override Anthropic upstream (testing)
   --upstream-openai <url>     (proxy) Override OpenAI upstream (testing)
   -h, --help              Show this help
@@ -88,6 +92,9 @@ function parseArgs(argv) {
             case "--port":
                 args.port = Number(argv[++i]);
                 break;
+            case "--host":
+                args.host = argv[++i];
+                break;
             case "--upstream-anthropic":
                 args.upstreamAnthropic = argv[++i];
                 break;
@@ -108,6 +115,10 @@ function readInput(file) {
 }
 function main() {
     const args = parseArgs(process.argv.slice(2));
+    if (args.command === "hook") {
+        void runHook();
+        return;
+    }
     if (args.command === "session") {
         if (args.list) {
             const sessions = listSessions();
@@ -154,6 +165,7 @@ function main() {
     if (args.command === "proxy") {
         startProxy({
             port: args.port,
+            host: args.host,
             anthropicUpstream: args.upstreamAnthropic,
             openaiUpstream: args.upstreamOpenai,
             strategies: args.strategies.length > 0 ? args.strategies : undefined,

package/dist/hook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Claude Code UserPromptSubmit hook: runs on EVERY query in Claude Code.
+ *
+ * Claude Code pipes hook input as JSON on stdin ({session_id, transcript_path,
+ * prompt, ...}). We profile the session transcript; when the context is lean
+ * we print nothing (zero noise, near-zero cost). When it crosses thresholds we
+ * emit additionalContext with targeted hygiene guidance — so every query in a
+ * heavy session gets nudged toward a leaner context automatically.
+ *
+ * Registered by `context-doctor install` under hooks.UserPromptSubmit in
+ * ~/.claude/settings.json; removed by `context-doctor uninstall`.
+ */
+export declare function runHook(): Promise<void>;

package/dist/hook.js

@@ -0,0 +1,85 @@
+/**
+ * Claude Code UserPromptSubmit hook: runs on EVERY query in Claude Code.
+ *
+ * Claude Code pipes hook input as JSON on stdin ({session_id, transcript_path,
+ * prompt, ...}). We profile the session transcript; when the context is lean
+ * we print nothing (zero noise, near-zero cost). When it crosses thresholds we
+ * emit additionalContext with targeted hygiene guidance — so every query in a
+ * heavy session gets nudged toward a leaner context automatically.
+ *
+ * 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 { homedir } from "node:os";
+import { join } from "node:path";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { parseSessionFile } from "./session.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+/** Start nudging at 80k tokens of context. */
+const WARN_TOKENS = 80_000;
+/** Re-nudge only after the context grows another 40% — one reminder, not a nag. */
+const REGROWTH_FACTOR = 1.4;
+function statePath() {
+    return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runHook() {
+    // A hook must never break the user's prompt: any failure exits silently.
+    try {
+        const input = JSON.parse(await readStdin());
+        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)
+            return;
+        // Per-session rate limit so the nudge fires on growth, not on every prompt.
+        const sessionId = input.session_id ?? transcriptPath;
+        let state = {};
+        try {
+            state = JSON.parse(readFileSync(statePath(), "utf8"));
+        }
+        catch {
+            /* first run */
+        }
+        const lastWarnedAt = state[sessionId] ?? 0;
+        if (profile.totalTokens < lastWarnedAt * REGROWTH_FACTOR)
+            return;
+        const entries = Object.entries({ ...state, [sessionId]: profile.totalTokens });
+        writeFileSync(statePath(), JSON.stringify(Object.fromEntries(entries.slice(-100))));
+        const lines = [
+            `This session's context is at ~${formatTokens(profile.totalTokens)} tokens` +
+                (profile.usagePct ? ` (${profile.usagePct.toFixed(0)}% of the window)` : "") +
+                (profile.cost ? `, costing ~${formatUsd(profile.cost.perCallUsd)} of input per message` : "") +
+                ".",
+            "Practice context hygiene from here on: summarize large tool results instead of keeping them verbatim, reference earlier content rather than re-reading or re-quoting it, and keep responses lean.",
+        ];
+        const topFinding = profile.findings.find((f) => f.estSavings > 0);
+        if (topFinding) {
+            lines.push(`Largest recoverable waste: ${topFinding.message} (${topFinding.suggestion})`);
+        }
+        if (profile.totalTokens > WARN_TOKENS * 2) {
+            lines.push("If it fits the flow, offer the user a compaction of the older history.");
+        }
+        console.log(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "UserPromptSubmit",
+                additionalContext: `<context-doctor>\n${lines.join("\n")}\n</context-doctor>`,
+            },
+        }));
+    }
+    catch {
+        /* silent — never disturb the prompt */
+    }
+}

package/dist/install.js

@@ -57,6 +57,53 @@ 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. */
+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`;
+    }
+    return "npx -y context-doctor hook";
+}
+const HOOK_MARKER = "context-doctor";
+/**
+ * Register the UserPromptSubmit hook in ~/.claude/settings.json so EVERY
+ * Claude Code query gets a context-size check. Idempotent.
+ */
+function installHook() {
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    if (!existsSync(join(homedir(), ".claude")))
+        return null; // no Claude Code here
+    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;
+        writeJsonWithBackup(settingsPath, settings);
+    }
+    return settingsPath;
+}
+function uninstallHook() {
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    if (!existsSync(settingsPath))
+        return;
+    const settings = readJson(settingsPath);
+    const entries = settings.hooks?.UserPromptSubmit;
+    if (!entries)
+        return;
+    const filtered = entries.filter((e) => !JSON.stringify(e).includes(HOOK_MARKER));
+    if (filtered.length !== entries.length) {
+        settings.hooks.UserPromptSubmit = filtered;
+        if (filtered.length === 0)
+            delete settings.hooks.UserPromptSubmit;
+        writeJsonWithBackup(settingsPath, settings);
+        console.log("✓ Claude Code every-prompt hook removed");
+    }
+}
 function installSkill() {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     // dist/install.js → package root is one level up; skills/ ships in the package.
@@ -92,6 +139,9 @@ export function runInstall() {
     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`);
     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.');
 }
@@ -116,5 +166,6 @@ export function runUninstall() {
         rmSync(skillDir, { recursive: true });
         console.log("✓ Agent Skill removed");
     }
+    uninstallHook();
     console.log("Done.");
 }

package/dist/mcp.js

@@ -20,16 +20,27 @@ import { profileConversation } from "./profile.js";
 import { optimizeConversation } from "./optimize.js";
 import { renderProfile } from "./report.js";
 import { formatTokens } from "./tokens.js";
-const server = new McpServer({ name: "context-doctor", version: "0.2.0" });
+/**
+ * Server instructions are injected by MCP clients (Claude Desktop, Cursor, …)
+ * into the system context of EVERY conversation where this server is enabled.
+ * 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.1" }, { 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.", {
+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"),
 }, async ({ conversation, model }) => {
     const profile = profileConversation(parseConversation(conversation), model);
     return { content: [{ type: "text", text: renderProfile(profile) }] };
 });
-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.", {
+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."),
@@ -45,9 +56,20 @@ server.tool("optimize_context", "Rewrite a conversation to reclaim tokens using
     const summary = `Saved ~${formatTokens(saved)} tokens (${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)}) ` +
         `via ${result.applied.length} change(s):\n` +
         result.applied.map((c) => `- [${c.strategy}] message #${c.messageIndex}: ${c.note} (~${formatTokens(c.tokensSaved)})`).join("\n");
+    // Echoing a huge optimized conversation back inline would flood the very
+    // context this tool exists to save. Above the cap, return the summary and
+    // point at the CLI (compact JSON keeps mid-size results affordable).
+    const ECHO_CAP_CHARS = 100_000;
+    const conversationJson = JSON.stringify(result.conversation);
     const content = [
         { type: "text", text: summary },
-        { type: "text", text: JSON.stringify(result.conversation, null, 2) },
+        conversationJson.length <= ECHO_CAP_CHARS
+            ? { type: "text", text: conversationJson }
+            : {
+                type: "text",
+                text: `[optimized conversation is ${conversationJson.length} chars — too large to echo into this context. ` +
+                    `Tell the user the savings above and that \`npx context-doctor optimize <file> --out slim.json\` produces the file directly.]`,
+            },
     ];
     // Host-model summarization: instead of calling an LLM ourselves (which would
     // need an API key), hand the pruned material to the model that invoked this
@@ -74,7 +96,7 @@ const BEST_PRACTICES = {
     ],
     anthropic: [
         "Use prompt caching with cache_control breakpoints after your stable prefix — cached reads cost ~10% of base input price.",
-        "Claude models have a 200k window, but quality degrades under heavy fill; aim to stay under ~70%.",
+        "Current Claude generations have a 1M-token window (Haiku 200k), but quality degrades under heavy fill; aim to stay under ~70%.",
         "For agents: prefer compact tool-result summaries in history and re-fetch details on demand.",
     ],
     openai: [

package/dist/optimize.js

@@ -163,26 +163,36 @@ export function optimizeConversation(input, options = {}) {
     // Opt-in only: it is lossy, so it is not in the default strategy set.
     let prunedDigest;
     if (opts.strategies.includes("prune-history") && messages.length > opts.keepRecent * 2) {
-        const keepFrom = messages.length - opts.keepRecent;
-        const pruned = messages.slice(0, keepFrom);
-        const prunedTokens = pruned.reduce((s, m) => s + estimateTokens(textOf(m.content)), 0);
-        // Digest: first ~200 chars of each pruned turn — enough for a host LLM to
-        // write a faithful summary, small enough not to defeat the pruning.
-        prunedDigest = pruned
-            .map((m, i) => `[${i}:${m.role}] ${textOf(m.content).replace(/\s+/g, " ").slice(0, 200)}`)
-            .join("\n");
-        const stub = {
-            role: "user",
-            content: `[context-doctor: ${pruned.length} earlier messages (~${prunedTokens} tokens) pruned. ` +
-                `Replace this stub with an LLM-written summary of those turns for best results.]`,
-        };
-        messages.splice(0, keepFrom, stub);
-        applied.push({
-            strategy: "prune-history",
-            messageIndex: 0,
-            tokensSaved: prunedTokens - estimateTokens(stub.content),
-            note: `Pruned ${pruned.length} old messages`,
-        });
+        let keepFrom = messages.length - opts.keepRecent;
+        // Never let the kept tail START with a tool result: its matching tool_use
+        // would be pruned away and both the Anthropic and OpenAI APIs reject
+        // conversations with orphaned tool results. Advance past any leading tool
+        // messages (their calls are in the pruned half anyway).
+        while (keepFrom < messages.length && isToolResultMessage(messages[keepFrom]))
+            keepFrom++;
+        // Boundary adjustment may leave too little tail to be worth keeping —
+        // in that case skip pruning entirely rather than gutting the conversation.
+        if (messages.length - keepFrom >= 2) {
+            const pruned = messages.slice(0, keepFrom);
+            const prunedTokens = pruned.reduce((s, m) => s + estimateTokens(textOf(m.content)), 0);
+            // Digest: first ~200 chars of each pruned turn — enough for a host LLM to
+            // write a faithful summary, small enough not to defeat the pruning.
+            prunedDigest = pruned
+                .map((m, i) => `[${i}:${m.role}] ${textOf(m.content).replace(/\s+/g, " ").slice(0, 200)}`)
+                .join("\n");
+            const stub = {
+                role: "user",
+                content: `[context-doctor: ${pruned.length} earlier messages (~${prunedTokens} tokens) pruned. ` +
+                    `Replace this stub with an LLM-written summary of those turns for best results.]`,
+            };
+            messages.splice(0, keepFrom, stub);
+            applied.push({
+                strategy: "prune-history",
+                messageIndex: 0,
+                tokensSaved: prunedTokens - estimateTokens(stub.content),
+                note: `Pruned ${pruned.length} old messages`,
+            });
+        }
     }
     const tokensAfter = messages.reduce((s, m) => s + estimateTokens(textOf(m.content)), 0);
     return { conversation: data, tokensBefore, tokensAfter, applied, prunedDigest };

package/dist/pricing.js

@@ -11,6 +11,8 @@ const PRICING = [
     [/claude.*opus/i, { inputPerM: 5, outputPerM: 25, cacheReadPerM: 0.5 }],
     [/claude.*sonnet/i, { inputPerM: 3, outputPerM: 15, cacheReadPerM: 0.3 }],
     [/claude.*haiku/i, { inputPerM: 1, outputPerM: 5, cacheReadPerM: 0.1 }],
+    [/gpt-5.*(mini|nano)/i, { inputPerM: 0.25, outputPerM: 2, cacheReadPerM: 0.025 }],
+    [/gpt-5/i, { inputPerM: 1.25, outputPerM: 10, cacheReadPerM: 0.125 }],
     [/gpt-4o-mini/i, { inputPerM: 0.15, outputPerM: 0.6, cacheReadPerM: 0.075 }],
     [/gpt-4o|gpt-4\.1/i, { inputPerM: 2.5, outputPerM: 10, cacheReadPerM: 1.25 }],
     [/gpt-4-turbo/i, { inputPerM: 10, outputPerM: 30, cacheReadPerM: 10 }],

package/dist/proxy.d.ts

@@ -15,6 +15,12 @@ import http from "node:http";
 import { OptimizeOptions } from "./optimize.js";
 export interface ProxyOptions extends OptimizeOptions {
     port?: number;
+    /**
+     * Bind address. Defaults to 127.0.0.1 — the proxy relays authenticated
+     * traffic and exposes /stats, so it must not listen on the network unless
+     * the user explicitly opts in (e.g. --host 0.0.0.0 inside a container).
+     */
+    host?: string;
     anthropicUpstream?: string;
     openaiUpstream?: string;
 }

package/dist/proxy.js

@@ -63,9 +63,12 @@ export function startProxy(opts = {}) {
             let body = Buffer.concat(chunks).toString("utf8");
             // Optimize the message history in flight. Anything unparseable (or with
             // no messages array, e.g. embeddings) passes through untouched.
+            // count_tokens is measurement — optimizing it would silently change the
+            // number the caller is trying to read, so it always passes through.
             stats.requests++;
+            const isMeasurement = url.startsWith("/v1/messages/count_tokens");
             let note = "passthrough";
-            if (req.method === "POST" && body) {
+            if (req.method === "POST" && body && !isMeasurement) {
                 try {
                     const result = optimizeConversation(body, opts);
                     const saved = result.tokensBefore - result.tokensAfter;
@@ -126,8 +129,9 @@ export function startProxy(opts = {}) {
             res.end(JSON.stringify({ error: `context-doctor proxy: ${e.message}` }));
         }
     });
-    server.listen(port, () => {
-        console.error(`context-doctor proxy listening on http://localhost:${port}`);
+    const host = opts.host ?? "127.0.0.1";
+    server.listen(port, host, () => {
+        console.error(`context-doctor proxy listening on http://${host}:${port}`);
         console.error(`  Anthropic apps/SDKs: export ANTHROPIC_BASE_URL=http://localhost:${port}`);
         console.error(`  OpenAI apps/SDKs:    export OPENAI_BASE_URL=http://localhost:${port}/v1`);
         console.error(`  Every request's context is optimized in flight; savings are logged here.`);

package/dist/test/hook.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hook tests: the every-prompt Claude Code hook must stay silent on lean
+ * sessions, fire with guidance on heavy ones, and rate-limit re-fires.
+ */
+export {};

package/dist/test/hook.test.js

@@ -0,0 +1,54 @@
+/**
+ * Hook tests: the every-prompt Claude Code hook must stay silent on lean
+ * sessions, fire with guidance on heavy ones, and rate-limit re-fires.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const cliPath = join(dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
+const dir = mkdtempSync(join(tmpdir(), "ctxdoc-hook-"));
+const statePath = join(dir, "state.json");
+function transcriptLine(role, content) {
+    return JSON.stringify({ type: role, message: { role, content } });
+}
+function runHook(transcriptPath, sessionId) {
+    return new Promise((resolve, reject) => {
+        const child = execFile(process.execPath, [cliPath, "hook"], { env: { ...process.env, CONTEXT_DOCTOR_HOOK_STATE: statePath } }, (err, stdout) => (err ? reject(err) : resolve(stdout)));
+        child.stdin.end(JSON.stringify({ session_id: sessionId, transcript_path: transcriptPath }));
+    });
+}
+// Lean session: a couple of small turns.
+const leanPath = join(dir, "lean.jsonl");
+writeFileSync(leanPath, [transcriptLine("user", "hi"), transcriptLine("assistant", "hello!")].join("\n"));
+// Heavy session: ~100k tokens of transcript.
+const heavyPath = join(dir, "heavy.jsonl");
+const bigTurn = "We discussed the deployment pipeline and database migrations at length. ".repeat(80);
+writeFileSync(heavyPath, Array.from({ length: 300 }, (_, i) => transcriptLine(i % 2 ? "assistant" : "user", bigTurn)).join("\n"));
+test("hook stays silent on a lean session", async () => {
+    const out = await runHook(leanPath, "lean-session");
+    assert.equal(out.trim(), "");
+});
+test("hook fires with hygiene guidance on a heavy session", async () => {
+    const out = await runHook(heavyPath, "heavy-session");
+    const parsed = JSON.parse(out);
+    const ctx = parsed.hookSpecificOutput.additionalContext;
+    assert.equal(parsed.hookSpecificOutput.hookEventName, "UserPromptSubmit");
+    assert.ok(ctx.includes("<context-doctor>"));
+    assert.ok(/context is at ~\d/.test(ctx), "reports the measured size");
+    assert.ok(ctx.includes("context hygiene"));
+});
+test("hook rate-limits: second prompt in the same heavy session is silent", async () => {
+    const out = await runHook(heavyPath, "heavy-session");
+    assert.equal(out.trim(), "");
+});
+test("hook never errors on malformed input", async () => {
+    const out = await new Promise((resolve, reject) => {
+        const child = execFile(process.execPath, [cliPath, "hook"], (err, stdout) => err ? reject(err) : resolve(stdout));
+        child.stdin.end("this is not json");
+    });
+    assert.equal(out.trim(), "");
+});

package/dist/test/smoke.test.js

@@ -66,6 +66,28 @@ test("optimizer output for Anthropic format keeps block structure valid", () =>
     const assistantMsg = out.messages[1].content;
     assert.equal(assistantMsg[0].type, "tool_use");
 });
+test("prune-history never leaves an orphaned tool result at the head of the tail", () => {
+    // Build a conversation where the naive prune boundary would land exactly on
+    // a tool-result message (its tool_use call falling in the pruned half).
+    const filler = "some earlier discussion that will be pruned away. ".repeat(20);
+    const conv = JSON.stringify({
+        messages: [
+            ...Array.from({ length: 8 }, (_, i) => ({ role: i % 2 ? "assistant" : "user", content: `${i} ${filler}` })),
+            { role: "assistant", content: [{ type: "tool_use", id: "tX", name: "search", input: { q: "x" } }] },
+            { role: "user", content: [{ type: "tool_result", tool_use_id: "tX", content: "results here" }] }, // naive boundary lands HERE
+            { role: "assistant", content: "Summary of results." },
+            { role: "user", content: "thanks" },
+            { role: "assistant", content: "welcome" },
+        ],
+    });
+    const result = optimizeConversation(conv, { strategies: ["prune-history"], keepRecent: 4 });
+    const out = result.conversation;
+    // First kept message after the stub must NOT be a tool result.
+    const firstKept = out.messages[1].content;
+    const isToolResult = Array.isArray(firstKept) && firstKept.some((b) => b?.type === "tool_result");
+    assert.equal(isToolResult, false, "tail must not start with an orphaned tool_result");
+    assert.ok(result.applied.some((c) => c.strategy === "prune-history"), "pruning still happened");
+});
 test("raw text input still profiles", () => {
     const profile = profileConversation(parseConversation("just some prompt text"));
     assert.equal(profile.messageCount, 1);

package/dist/tokens.js

@@ -14,6 +14,7 @@ const MODEL_WINDOWS = [
     // Current-generation Claude (Fable/Mythos 5, Opus 4.6+, Sonnet 4.6+) is 1M.
     [/claude.*(fable|mythos)|claude.*opus-?(5|4-[678])|claude.*sonnet-?(5|4-6)/i, 1_000_000],
     [/claude.*sonnet|claude.*opus|claude-\d/i, 200_000],
+    [/gpt-5/i, 400_000],
     [/gpt-4o|gpt-4-turbo|gpt-4\.1|o[134](-|$)/i, 128_000],
     [/gpt-4(?!o|\.|-turbo)/i, 8_192],
     [/gpt-3\.5/i, 16_385],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -18,7 +18,7 @@
   "author": "Kushal P",
   "repository": {
     "type": "git",
-    "url": "https://github.com/KushalP1/context-doctor.git"
+    "url": "git+https://github.com/KushalP1/context-doctor.git"
   },
   "type": "module",
   "main": "./dist/index.js",
@@ -41,7 +41,7 @@
     "build": "tsc",
     "prepublishOnly": "npm run build",
     "dev": "tsc --watch",
-    "test": "npm run build && node --test dist/test/*.test.js"
+    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/hook.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",