context-doctor 0.4.0 → 0.5.0

package/README.md

@@ -95,6 +95,8 @@ 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 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 |
 
@@ -296,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/mcp.js

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

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/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.4.0",
+  "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 dist/test/mcp-http.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",