context-doctor 0.3.6 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # context-doctor 🩺
 
+[![CI](https://github.com/KushalP1/context-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/KushalP1/context-doctor/actions) [![npm](https://img.shields.io/npm/v/context-doctor)](https://www.npmjs.com/package/context-doctor)
+
 **See what's eating your LLM context window — and fix it.**
 
 Every long-running LLM conversation slowly fills up with junk: duplicated documents, 10k-token tool outputs nobody reads again, base64 blobs, stale history. You pay for those tokens on **every single call**, and model quality drops as the window fills.
@@ -93,7 +95,10 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor session [file]` | Profile a Claude Code session transcript (defaults to your most recent; `--list` to browse) |
 | `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 hook` | The every-prompt Claude Code hook (registered by `install`; you never run this yourself) |
+| `context-doctor watch [file]` | Live monitor of a growing session/agent trace: token/cost line per change, findings as they appear |
+| `context-doctor doctor` | Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes |
+| `context-doctor hook` | The every-prompt Claude Code hook (registered by `install`; you never run this yourself). Warning threshold tunable via `CONTEXT_DOCTOR_WARN_TOKENS` (default 80000) |
+| `context-doctor-mcp` | The MCP server itself — stdio by default (what the installer wires); `--http [--port 8808] [--host H]` serves streamable HTTP at `/mcp` for URL-based clients like ChatGPT developer-mode connectors |
 
 ## What "always-on" means, per surface
 
@@ -175,7 +180,7 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 | Claude Desktop | `npx context-doctor install` writes the config — just restart the app |
 | Claude Code | Same command — MCP + skill + every-prompt hook, all automatic |
 | Cursor | Same command — writes `~/.cursor/mcp.json` |
-| ChatGPT desktop | **Manual, one time** (ChatGPT's connectors live inside its own settings): Settings → Connectors → Developer mode → add local server, command `npx`, args `-y context-doctor-mcp` |
+| ChatGPT (developer mode) | **Manual + a reachable URL** — ChatGPT connects to servers over the internet, never local commands. Run `context-doctor-mcp --http` on a host/tunnel, then add the URL as a connector. Normal ChatGPT (no dev mode) has no MCP — use the CLI |
 
 For any other MCP client, the server entry is:
 
@@ -197,14 +202,15 @@ For any other MCP client, the server entry is:
 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
+### How it works in ChatGPT, step by step (honest version)
+
+ChatGPT's MCP support differs fundamentally from Claude Desktop's: **it never spawns local processes**. Its custom connectors (developer mode) have OpenAI's servers connect to a **URL** — so the MCP server must be reachable from the internet.
 
-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.
+1. **Normal ChatGPT (no developer mode): no MCP at all.** context-doctor still helps via the CLI: export the conversation and run `npx context-doctor analyze chat.json --model gpt-5` / `optimize` — no account settings required.
+2. **ChatGPT developer mode**: run our HTTP transport somewhere reachable — `context-doctor-mcp --http --port 8808` on a small host (bind `--host 0.0.0.0` there), or expose your machine temporarily with a tunnel (`ngrok http 8808`). Then Settings → Connectors → Advanced → Developer mode → add connector with URL `https://<your-host>/mcp`.
+3. Once connected, GPT gets the same three tools with the same trigger guidance: ask *"what's eating my context?"* → it calls `profile_context`; *"optimize it"* works the same, including GPT writing the pruning summary itself.
 
-For ChatGPT on the web (no MCP): export the conversation and use the CLI — `npx context-doctor analyze chat.json --model gpt-5`.
+Security note for step 2: the HTTP endpoint is unauthenticated — put it behind your tunnel's auth or a reverse proxy if it stays up long-term.
 
 ### claude.ai on the web
 
@@ -292,12 +298,7 @@ Exact counts require each provider's private tokenizer. `context-doctor` uses a
 
 ## Roadmap
 
-- [x] ~~Session import from Claude Code transcript formats~~ (`context-doctor session`)
-- [x] ~~LLM summarization for prune-history~~ (host-model summarization via MCP — no key needed)
-- [ ] Proxy: per-route strategy config + response token accounting
-- [ ] `context-doctor watch` — live profiling of a running agent's JSONL trace
-- [ ] Exact tokenizer adapters (tiktoken, Anthropic count-tokens API) as optional plugins
-- [ ] Cursor / ChatGPT-export transcript formats for `session`
+See [ROADMAP.md](./ROADMAP.md) for the full plan with rationale. Headlines: **v0.5** trust & automation (tag-based publishing, `doctor` self-check, live `watch`), **v0.6** accuracy (exact tokenizers, semantic dedupe, more session formats), **v0.7** proxy pro (response accounting, prompt-cache advisor), **v1.0** budgets + local dashboard. Non-goals, permanently: cloud services, telemetry, silent history rewriting, mandatory API keys.
 
 Contributions welcome — this project is small on purpose. Open an issue before a big PR.
 

package/dist/cli.js

@@ -20,6 +20,8 @@ import { listSessions, parseSessionFile } from "./session.js";
 import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
 import { recordLedger } from "./ledger.js";
+import { runDoctor } from "./doctor.js";
+import { runWatch } from "./watch.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -36,6 +38,11 @@ Usage:
                                                 automatically by \`install\`; reads hook JSON on stdin)
   context-doctor report                         Impact report: exact proxy savings, hook activity,
                                                 and remaining recoverable waste in recent sessions
+  context-doctor doctor                         Self-check the installation (configs, hook, skill,
+                                                MCP handshake) with one pasteable diagnosis
+  context-doctor watch [file]                   Live-monitor a growing session/agent trace: running
+                                                token/cost line per change, new findings as they appear
+                                                (--interval-ms n, default 2000)
 
 Input: a conversation JSON file (OpenAI or Anthropic message format, or a bare
 message array). Use "-" to read from stdin.
@@ -96,6 +103,9 @@ function parseArgs(argv) {
             case "--port":
                 args.port = Number(argv[++i]);
                 break;
+            case "--interval-ms":
+                args.intervalMs = Number(argv[++i]);
+                break;
             case "--host":
                 args.host = argv[++i];
                 break;
@@ -123,6 +133,14 @@ function main() {
         void runHook();
         return;
     }
+    if (args.command === "watch") {
+        runWatch({ file: args.file, intervalMs: args.intervalMs, model: args.model });
+        return; // interval keeps the process alive
+    }
+    if (args.command === "doctor") {
+        void runDoctor();
+        return;
+    }
     if (args.command === "report") {
         void buildImpactReport(args.port).then((r) => console.log(r));
         return;

package/dist/doctor.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `context-doctor doctor` — self-check for a local installation.
+ *
+ * Verifies every integration point end to end and prints one ✓/✗/– line per
+ * check, so "it doesn't work" becomes a single pasteable diagnosis. Always
+ * exits 0 — absence of an app is a note, not a failure.
+ */
+export declare function runDoctor(): Promise<void>;

package/dist/doctor.js

@@ -0,0 +1,121 @@
+/**
+ * `context-doctor doctor` — self-check for a local installation.
+ *
+ * Verifies every integration point end to end and prints one ✓/✗/– line per
+ * check, so "it doesn't work" becomes a single pasteable diagnosis. Always
+ * exits 0 — absence of an app is a note, not a failure.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ledgerPath, recordLedger } from "./ledger.js";
+function claudeDesktopConfigPath() {
+    switch (platform()) {
+        case "darwin": return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+        case "win32": return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+        default: return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+    }
+}
+function checkMcpEntry(appName, configPath) {
+    if (!existsSync(configPath))
+        return { label: appName, status: "skip", detail: "app not detected (config file absent)" };
+    try {
+        const config = JSON.parse(readFileSync(configPath, "utf8"));
+        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];
+        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"})` };
+    }
+    catch (e) {
+        return { label: appName, status: "fail", detail: `${configPath} is not valid JSON (${e.message})` };
+    }
+}
+/** Spawn our own MCP server and run the initialize handshake over stdio. */
+function checkMcpHandshake() {
+    const label = "MCP server handshake";
+    const mcpPath = join(dirname(fileURLToPath(import.meta.url)), "mcp.js");
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [mcpPath], { stdio: ["pipe", "pipe", "ignore"] });
+        const timer = setTimeout(() => {
+            child.kill();
+            resolve({ label, status: "fail", detail: "no initialize response within 5s" });
+        }, 5000);
+        let out = "";
+        child.stdout.on("data", (d) => {
+            out += d.toString();
+            if (out.includes("\n")) {
+                clearTimeout(timer);
+                child.kill();
+                try {
+                    const reply = JSON.parse(out.split("\n")[0]);
+                    const version = reply.result?.serverInfo?.version;
+                    const hasInstructions = typeof reply.result?.instructions === "string" && reply.result.instructions.length > 0;
+                    resolve(version && hasInstructions
+                        ? { label, status: "ok", detail: `v${version} responds; standing instructions present` }
+                        : { label, status: "fail", detail: "handshake reply missing serverInfo/instructions" });
+                }
+                catch {
+                    resolve({ label, status: "fail", detail: "unparseable handshake reply" });
+                }
+            }
+        });
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            resolve({ label, status: "fail", detail: e.message });
+        });
+        child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "doctor", version: "1" } } }) + "\n");
+    });
+}
+export async function runDoctor() {
+    const checks = [];
+    checks.push(checkMcpEntry("Claude Desktop", claudeDesktopConfigPath()));
+    checks.push(checkMcpEntry("Claude Code", join(homedir(), ".claude.json")));
+    checks.push(checkMcpEntry("Cursor", join(homedir(), ".cursor", "mcp.json")));
+    // Hook registration
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    if (existsSync(settingsPath)) {
+        try {
+            const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+            const registered = JSON.stringify(settings.hooks?.UserPromptSubmit ?? []).includes("context-doctor");
+            checks.push(registered
+                ? { label: "Every-prompt hook", status: "ok", detail: "registered in ~/.claude/settings.json" }
+                : { label: "Every-prompt hook", status: "fail", detail: "not registered — run: context-doctor install" });
+        }
+        catch (e) {
+            checks.push({ label: "Every-prompt hook", status: "fail", detail: `settings.json unreadable (${e.message})` });
+        }
+    }
+    else {
+        checks.push({ label: "Every-prompt hook", status: "skip", detail: "Claude Code not detected" });
+    }
+    // Skill
+    const skillPath = join(homedir(), ".claude", "skills", "context-doctor", "SKILL.md");
+    checks.push(existsSync(skillPath)
+        ? { label: "Agent Skill", status: "ok", detail: skillPath }
+        : { label: "Agent Skill", status: "skip", detail: "not installed (run context-doctor install on a Claude Code machine)" });
+    // Ledger writable
+    try {
+        recordLedger({ ev: "check", sid: "doctor-probe", tok: 0, warn: false });
+        checks.push({ label: "Ledger", status: "ok", detail: `writable at ${ledgerPath()}` });
+    }
+    catch {
+        checks.push({ label: "Ledger", status: "fail", detail: `cannot write ${ledgerPath()}` });
+    }
+    checks.push(await checkMcpHandshake());
+    const mark = { ok: "✓", fail: "✗", skip: "–" };
+    console.log("CONTEXT DOCTOR — self-check");
+    console.log("═".repeat(56));
+    for (const c of checks) {
+        console.log(`${mark[c.status]} ${c.label.padEnd(22)} ${c.detail}`);
+    }
+    const fails = checks.filter((c) => c.status === "fail");
+    console.log("");
+    console.log(fails.length === 0 ? "All good." : `${fails.length} issue(s) found — fixes suggested above.`);
+}

package/dist/hook.js

@@ -17,8 +17,8 @@ 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;
+/** Start nudging at 80k tokens of context (override: CONTEXT_DOCTOR_WARN_TOKENS). */
+const WARN_TOKENS = Number(process.env.CONTEXT_DOCTOR_WARN_TOKENS) > 0 ? Number(process.env.CONTEXT_DOCTOR_WARN_TOKENS) : 80_000;
 /** Re-nudge only after the context grows another 40% — one reminder, not a nag. */
 const REGROWTH_FACTOR = 1.4;
 /**

package/dist/install.js

@@ -167,5 +167,13 @@ export function runUninstall() {
         console.log("✓ Agent Skill removed");
     }
     uninstallHook();
+    // Remove our bookkeeping files too — uninstall means gone.
+    for (const file of [".context-doctor-hook-state.json", ".context-doctor-ledger.jsonl"]) {
+        const p = join(homedir(), ".claude", file);
+        if (existsSync(p)) {
+            rmSync(p);
+            console.log(`✓ Removed ${file}`);
+        }
+    }
     console.log("Done.");
 }

package/dist/ledger.js

@@ -8,7 +8,7 @@
  *              (pre-0.3.6 hook entries have no `ev` field; treated as checks)
  *   optimize — an optimization was applied  {ev: "optimize", src: "cli"|"mcp", saved, model?}
  */
-import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 export function statePath() {
@@ -20,6 +20,9 @@ export function ledgerPath() {
 export function recordLedger(entry) {
     const path = ledgerPath();
     try {
+        // Claude-Desktop-only machines have no ~/.claude — create it so their
+        // optimize events count in `context-doctor report` too.
+        mkdirSync(dirname(path), { recursive: true });
         // Cap growth: past ~256KB keep the most recent 500 entries.
         if (existsSync(path) && statSync(path).size > 256 * 1024) {
             const lines = readFileSync(path, "utf8").trimEnd().split("\n");

package/dist/mcp.js

@@ -30,63 +30,77 @@ 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 server = new McpServer({ name: "context-doctor", version: "0.3.6" }, { 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"),
-    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. 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."),
-    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 }) => {
-    const result = optimizeConversation(conversation, {
-        strategies: strategies,
-        keepRecent: keep_recent,
-        maxToolResultTokens: max_tool_result_tokens,
+/**
+ * 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.5.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"),
+    }, async ({ conversation, model }) => {
+        const profile = profileConversation(parseConversation(conversation), model);
+        return { content: [{ type: "text", text: renderProfile(profile) }] };
     });
-    const saved = result.tokensBefore - result.tokensAfter;
-    if (saved > 0) {
-        recordLedger({ ev: "optimize", src: "mcp", saved, model: result.conversation?.model });
-    }
-    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 },
-        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
-    // tool and ask IT to write the summary.
-    if (result.prunedDigest) {
-        content.push({
-            type: "text",
-            text: "ACTION REQUIRED (you, the assistant calling this tool): the pruned turns are digested below. " +
-                "Write a dense factual summary of them (≤150 tokens: decisions, current state, open items, key identifiers) " +
-                "and replace the '[context-doctor: ... pruned]' stub message in the conversation above with your summary " +
-                "before presenting the result.\n\nPRUNED TURNS DIGEST:\n" + result.prunedDigest,
+    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."),
+        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 }) => {
+        const result = optimizeConversation(conversation, {
+            strategies: strategies,
+            keepRecent: keep_recent,
+            maxToolResultTokens: max_tool_result_tokens,
         });
-    }
-    return { content };
-});
+        const saved = result.tokensBefore - result.tokensAfter;
+        if (saved > 0) {
+            recordLedger({ ev: "optimize", src: "mcp", saved, model: result.conversation?.model });
+        }
+        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 },
+            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
+        // tool and ask IT to write the summary.
+        if (result.prunedDigest) {
+            content.push({
+                type: "text",
+                text: "ACTION REQUIRED (you, the assistant calling this tool): the pruned turns are digested below. " +
+                    "Write a dense factual summary of them (≤150 tokens: decisions, current state, open items, key identifiers) " +
+                    "and replace the '[context-doctor: ... pruned]' stub message in the conversation above with your summary " +
+                    "before presenting the result.\n\nPRUNED TURNS DIGEST:\n" + result.prunedDigest,
+            });
+        }
+        return { content };
+    });
+    server.tool("context_best_practices", "Get a curated checklist of context-management best practices, optionally specialized for a provider (anthropic, openai).", {
+        provider: z.enum(["general", "anthropic", "openai"]).optional().describe("Provider to specialize tips for (default: general)"),
+    }, async ({ provider }) => {
+        const tips = [...BEST_PRACTICES.general, ...(provider && provider !== "general" ? BEST_PRACTICES[provider] : [])];
+        return { content: [{ type: "text", text: tips.map((t, i) => `${i + 1}. ${t}`).join("\n") }] };
+    });
+    return server;
+}
 const BEST_PRACTICES = {
     general: [
         "Put stable content first (system prompt, tool definitions, reference docs) and volatile content last — prompt caches match byte-identical prefixes only.",
@@ -106,11 +120,61 @@ const BEST_PRACTICES = {
         "Use max_completion_tokens headroom math: input + output must fit the window together.",
     ],
 };
-server.tool("context_best_practices", "Get a curated checklist of context-management best practices, optionally specialized for a provider (anthropic, openai).", {
-    provider: z.enum(["general", "anthropic", "openai"]).optional().describe("Provider to specialize tips for (default: general)"),
-}, async ({ provider }) => {
-    const tips = [...BEST_PRACTICES.general, ...(provider && provider !== "general" ? BEST_PRACTICES[provider] : [])];
-    return { content: [{ type: "text", text: tips.map((t, i) => `${i + 1}. ${t}`).join("\n") }] };
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// -- Transport dispatch --------------------------------------------------------
+// Default: stdio (Claude Desktop, Claude Code, Cursor spawn us as a child).
+// --http [--port N] [--host H]: streamable-HTTP endpoint at /mcp for clients
+// that connect to a URL instead of spawning a process — ChatGPT developer-mode
+// connectors (which require a reachable URL), web MCP clients, remote setups.
+const argv = process.argv.slice(2);
+if (argv.includes("--http")) {
+    const argAfter = (flag) => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const port = Number(argAfter("--port")) > 0 ? Number(argAfter("--port")) : 8808;
+    const host = argAfter("--host") ?? "127.0.0.1";
+    const { createServer: createHttpServer } = await import("node:http");
+    const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
+    createHttpServer(async (req, res) => {
+        try {
+            if (req.url === "/health") {
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({ ok: true, service: "context-doctor-mcp" }));
+                return;
+            }
+            if (!(req.url ?? "").startsWith("/mcp")) {
+                res.statusCode = 404;
+                res.end(JSON.stringify({ error: "MCP endpoint is /mcp" }));
+                return;
+            }
+            if (req.method !== "POST") {
+                // Stateless mode: no standalone SSE stream, no sessions to delete.
+                res.statusCode = 405;
+                res.setHeader("allow", "POST");
+                res.end(JSON.stringify({ error: "Stateless server: POST /mcp only" }));
+                return;
+            }
+            // Fresh server + transport per request (stateless — nothing shared).
+            const server = createServer();
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            res.on("close", () => {
+                void transport.close();
+                void server.close();
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+        catch (e) {
+            if (!res.headersSent)
+                res.statusCode = 500;
+            res.end(JSON.stringify({ error: e.message }));
+        }
+    }).listen(port, host, () => {
+        console.error(`context-doctor MCP (streamable HTTP) on http://${host}:${port}/mcp`);
+        console.error(`ChatGPT developer-mode connectors need a URL their servers can reach — expose this via your host or a tunnel.`);
+    });
+}
+else {
+    const transport = new StdioServerTransport();
+    await createServer().connect(transport);
+}

package/dist/test/doctor.test.d.ts

@@ -0,0 +1,2 @@
+/** doctor must always produce a diagnosis and exit 0, even on a bare machine. */
+export {};

package/dist/test/doctor.test.js

@@ -0,0 +1,19 @@
+/** doctor must always produce a diagnosis and exit 0, even on a bare machine. */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtempSync } 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");
+test("doctor runs, checks the MCP handshake, and exits 0", async () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "ctxdoc-doctor-"));
+    const out = await new Promise((resolve, reject) => {
+        execFile(process.execPath, [cliPath, "doctor"], { env: { ...process.env, CONTEXT_DOCTOR_HOOK_STATE: join(stateDir, "state.json") }, timeout: 20000 }, (err, stdout) => (err ? reject(err) : resolve(stdout)));
+    });
+    assert.ok(out.includes("CONTEXT DOCTOR — self-check"));
+    assert.ok(out.includes("MCP server handshake"));
+    assert.ok(/✓ MCP server handshake/.test(out), "our own server must pass its own handshake");
+    assert.ok(out.includes("Ledger"));
+});

package/dist/test/mcp-http.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP streamable-HTTP transport: spawn `mcp.js --http`, run the initialize
+ * handshake and a tool call over plain HTTP, exactly as a URL-based client
+ * (e.g. a ChatGPT developer-mode connector) would.
+ */
+export {};

package/dist/test/mcp-http.test.js

@@ -0,0 +1,63 @@
+/**
+ * MCP streamable-HTTP transport: spawn `mcp.js --http`, run the initialize
+ * handshake and a tool call over plain HTTP, exactly as a URL-based client
+ * (e.g. a ChatGPT developer-mode connector) would.
+ */
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const mcpPath = join(dirname(fileURLToPath(import.meta.url)), "..", "mcp.js");
+const PORT = 8898;
+const child = spawn(process.execPath, [mcpPath, "--http", "--port", String(PORT)], { stdio: ["ignore", "ignore", "pipe"] });
+await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("HTTP MCP server did not start")), 8000);
+    child.stderr.on("data", (d) => {
+        if (d.toString().includes("streamable HTTP")) {
+            clearTimeout(timer);
+            resolve();
+        }
+    });
+});
+after(() => child.kill());
+async function rpc(body) {
+    const res = await fetch(`http://127.0.0.1:${PORT}/mcp`, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    // Streamable HTTP may answer as SSE ("data: {...}") or plain JSON.
+    const dataLine = text.split("\n").find((l) => l.startsWith("data: "));
+    return { status: res.status, json: JSON.parse(dataLine ? dataLine.slice(6) : text) };
+}
+test("initialize over HTTP returns server info + instructions", async () => {
+    const { status, json } = await rpc({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "t", version: "1" } },
+    });
+    assert.equal(status, 200);
+    assert.equal(json.result.serverInfo.name, "context-doctor");
+    assert.ok(json.result.instructions.includes("Context hygiene"));
+});
+test("tools/call works statelessly over HTTP", async () => {
+    const { json } = await rpc({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "tools/call",
+        params: {
+            name: "profile_context",
+            arguments: { conversation: JSON.stringify({ messages: [{ role: "user", content: "hello world" }] }) },
+        },
+    });
+    assert.ok(json.result.content[0].text.includes("CONTEXT DOCTOR"));
+});
+test("health endpoint responds; non-POST is rejected", async () => {
+    const health = (await (await fetch(`http://127.0.0.1:${PORT}/health`)).json());
+    assert.equal(health.ok, true);
+    const get = await fetch(`http://127.0.0.1:${PORT}/mcp`);
+    assert.equal(get.status, 405);
+});

package/dist/test/watch.test.d.ts

@@ -0,0 +1,2 @@
+/** watch: emits a status line on growth, surfaces new findings once. */
+export {};

package/dist/test/watch.test.js

@@ -0,0 +1,36 @@
+/** watch: emits a status line on growth, surfaces new findings once. */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { appendFileSync, 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");
+function line(role, content) {
+    return JSON.stringify({ type: role, message: { role, content } }) + "\n";
+}
+test("watch reports growth and new findings live", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctxdoc-watch-"));
+    const file = join(dir, "trace.jsonl");
+    writeFileSync(file, line("user", "hello there"));
+    const child = spawn(process.execPath, [cliPath, "watch", file, "--interval-ms", "150"], { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    child.stdout.on("data", (d) => (out += d.toString()));
+    try {
+        // First tick: initial line.
+        await new Promise((r) => setTimeout(r, 500));
+        assert.ok(/tokens/.test(out), `initial status line expected, got: ${out}`);
+        // Grow the file with an oversized tool result → new status + a finding.
+        appendFileSync(file, line("assistant", JSON.stringify([{ type: "tool_use", id: "t1", name: "search", input: {} }])) +
+            JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "data ".repeat(3000) }] } }) +
+            "\n");
+        await new Promise((r) => setTimeout(r, 700));
+        const statusLines = out.split("\n").filter((l) => l.includes("tokens"));
+        assert.ok(statusLines.length >= 2, `expected a second status line after growth: ${out}`);
+        assert.ok(out.includes("⚠"), `expected a finding to surface: ${out}`);
+    }
+    finally {
+        child.kill();
+    }
+});

package/dist/watch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `context-doctor watch [file]` — live monitor for a growing session/agent
+ * trace. Polls the file (default: your most recent Claude Code session) and
+ * on growth re-profiles, printing one status line per change plus any NEW
+ * findings as they appear. Ctrl-C to stop.
+ *
+ * Polling (not fs.watch) is deliberate: editors/agents rewrite files in ways
+ * that break watchers cross-platform, and a 2s stat is effectively free.
+ */
+export interface WatchOptions {
+    file?: string;
+    intervalMs?: number;
+    model?: string;
+}
+export declare function runWatch(opts: WatchOptions): void;

package/dist/watch.js

@@ -0,0 +1,62 @@
+/**
+ * `context-doctor watch [file]` — live monitor for a growing session/agent
+ * trace. Polls the file (default: your most recent Claude Code session) and
+ * on growth re-profiles, printing one status line per change plus any NEW
+ * findings as they appear. Ctrl-C to stop.
+ *
+ * Polling (not fs.watch) is deliberate: editors/agents rewrite files in ways
+ * that break watchers cross-platform, and a 2s stat is effectively free.
+ */
+import { existsSync, statSync } from "node:fs";
+import { listSessions, parseSessionFile } from "./session.js";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+export function runWatch(opts) {
+    const file = opts.file ?? listSessions(1)[0]?.path;
+    if (!file || !existsSync(file)) {
+        console.error("No transcript to watch. Pass a .jsonl file or run where Claude Code sessions exist.");
+        process.exitCode = 1;
+        return;
+    }
+    const intervalMs = opts.intervalMs ?? 2000;
+    let lastSize = -1;
+    let lastTokens = 0;
+    const seenFindings = new Set();
+    console.error(`Watching ${file} (every ${intervalMs / 1000}s; Ctrl-C to stop)`);
+    const tick = () => {
+        try {
+            const size = statSync(file).size;
+            if (size === lastSize)
+                return; // nothing new — cost of this tick was one stat
+            lastSize = size;
+            const parsed = parseSessionFile(file);
+            if (parsed.messageCount === 0)
+                return;
+            const profile = profileConversation(parseConversation(parsed.conversationJson), opts.model ?? parsed.model);
+            const delta = profile.totalTokens - lastTokens;
+            lastTokens = profile.totalTokens;
+            const cost = profile.cost ? ` · ${formatUsd(profile.cost.perCallUsd)}/msg` : "";
+            const pct = profile.usagePct !== undefined ? ` · ${profile.usagePct.toFixed(1)}% of window` : "";
+            console.log(`[${new Date().toISOString().slice(11, 19)}] ~${formatTokens(profile.totalTokens)} tokens` +
+                (delta !== 0 ? ` (${delta > 0 ? "+" : ""}${formatTokens(Math.abs(delta)) === "0" ? delta : (delta > 0 ? "" : "-") + formatTokens(Math.abs(delta))})` : "") +
+                `${pct}${cost} · ${profile.messageCount} messages`);
+            // Surface each finding once, when it first appears.
+            for (const f of profile.findings) {
+                if (f.estSavings === 0)
+                    continue;
+                const key = `${f.id}:${f.messages.join(",")}`;
+                if (seenFindings.has(key))
+                    continue;
+                seenFindings.add(key);
+                console.log(`  ⚠ ${f.message} [save ~${formatTokens(f.estSavings)}]`);
+            }
+        }
+        catch {
+            /* transient read race — try again next tick */
+        }
+    };
+    tick();
+    setInterval(tick, intervalMs);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.3.6",
+  "version": "0.5.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",
@@ -41,7 +41,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"
+    "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"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",