context-doctor 0.2.0

package/dist/test/smoke.test.js

@@ -0,0 +1,73 @@
+/** Smoke tests: parse → profile → optimize roundtrip for both provider formats. */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseConversation } from "../parse.js";
+import { profileConversation } from "../profile.js";
+import { optimizeConversation } from "../optimize.js";
+// Large enough to clear the profiler's 2000-token oversized-tool-result threshold.
+const bigText = "Sunny, 18C. ".repeat(900);
+const openaiConv = JSON.stringify({
+    messages: [
+        { role: "system", content: "You are helpful." },
+        { role: "user", content: "weather in SF?" },
+        { role: "assistant", content: null, tool_calls: [{ id: "c1", type: "function", function: { name: "get_weather", arguments: '{"city":"SF"}' } }] },
+        { role: "tool", tool_call_id: "c1", content: bigText },
+        { role: "assistant", content: "It is sunny and 18C in SF." },
+    ],
+});
+const anthropicConv = JSON.stringify({
+    system: "You are helpful.",
+    messages: [
+        { role: "user", content: "weather in SF?" },
+        { role: "assistant", content: [{ type: "tool_use", id: "t1", name: "get_weather", input: { city: "SF" } }] },
+        { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: bigText }] },
+        { role: "assistant", content: "Sunny and 18C." },
+    ],
+});
+test("parses OpenAI format and classifies tool plumbing", () => {
+    const conv = parseConversation(openaiConv);
+    assert.equal(conv.sourceFormat, "openai");
+    assert.equal(conv.messages.filter((m) => m.kind === "tool_result").length, 1);
+    assert.equal(conv.messages.filter((m) => m.kind === "tool_call").length, 1);
+});
+test("parses Anthropic format including external system prompt", () => {
+    const conv = parseConversation(anthropicConv);
+    assert.equal(conv.sourceFormat, "anthropic");
+    assert.equal(conv.messages[0].kind, "system");
+    assert.ok(conv.messages.some((m) => m.toolName === "get_weather"));
+});
+test("profiler flags oversized tool results", () => {
+    const profile = profileConversation(parseConversation(openaiConv), "gpt-4o");
+    assert.ok(profile.totalTokens > 500);
+    assert.equal(profile.contextWindow, 128_000);
+    assert.ok(profile.findings.some((f) => f.id === "large_tool_result"));
+});
+test("optimizer trims stale tool results and reports savings", () => {
+    const result = optimizeConversation(openaiConv, { keepRecent: 1, maxToolResultTokens: 50 });
+    assert.ok(result.tokensAfter < result.tokensBefore);
+    assert.ok(result.applied.some((c) => c.strategy === "trim-tool-results"));
+    // Output must remain valid JSON with the same message count.
+    const out = result.conversation;
+    assert.equal(out.messages.length, 5);
+});
+test("optimizer output for Anthropic format keeps block structure valid", () => {
+    const result = optimizeConversation(anthropicConv, { keepRecent: 1, maxToolResultTokens: 50 });
+    const out = result.conversation;
+    for (const m of out.messages) {
+        assert.ok(typeof m.content === "string" || Array.isArray(m.content));
+    }
+    // The trimmed tool_result must KEEP its block type and tool_use_id — the
+    // Anthropic API rejects a tool_use with no matching tool_result.
+    const toolResultMsg = out.messages[2].content;
+    assert.equal(toolResultMsg[0].type, "tool_result");
+    assert.equal(toolResultMsg[0].tool_use_id, "t1");
+    assert.ok(toolResultMsg[0].content.length < 1000, "tool_result content was trimmed");
+    // And the tool_use block on the assistant side is untouched.
+    const assistantMsg = out.messages[1].content;
+    assert.equal(assistantMsg[0].type, "tool_use");
+});
+test("raw text input still profiles", () => {
+    const profile = profileConversation(parseConversation("just some prompt text"));
+    assert.equal(profile.messageCount, 1);
+    assert.ok(profile.totalTokens > 0);
+});

package/dist/tokens.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Token estimation without provider tokenizer dependencies.
+ *
+ * Exact token counts require each provider's tokenizer (tiktoken, Anthropic's
+ * API, etc.). For profiling purposes an estimate within ~10% is enough to rank
+ * what's eating the window, so we use a calibrated chars-per-token heuristic:
+ * prose averages ~4 chars/token, code and JSON are denser (~3.2), and
+ * whitespace-heavy content is cheaper. This keeps the tool zero-config and
+ * fully offline.
+ */
+export type Provider = "anthropic" | "openai" | "google" | "generic";
+export declare function contextWindowFor(model?: string): number | undefined;
+export declare function providerFor(model?: string): Provider;
+export declare function estimateTokens(text: string): number;
+/** Per-message structural overhead (role markers, delimiters) is roughly constant. */
+export declare const MESSAGE_OVERHEAD_TOKENS = 4;
+export declare function formatTokens(n: number): string;

package/dist/tokens.js

@@ -0,0 +1,69 @@
+/**
+ * Token estimation without provider tokenizer dependencies.
+ *
+ * Exact token counts require each provider's tokenizer (tiktoken, Anthropic's
+ * API, etc.). For profiling purposes an estimate within ~10% is enough to rank
+ * what's eating the window, so we use a calibrated chars-per-token heuristic:
+ * prose averages ~4 chars/token, code and JSON are denser (~3.2), and
+ * whitespace-heavy content is cheaper. This keeps the tool zero-config and
+ * fully offline.
+ */
+/** Known context window sizes (tokens) by model-name substring, checked in order. */
+const MODEL_WINDOWS = [
+    [/claude.*haiku/i, 200_000],
+    // 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-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],
+    [/gemini.*(1\.5|2\.|2-5)/i, 1_000_000],
+    [/llama.*3/i, 128_000],
+    [/mistral|mixtral/i, 32_000],
+];
+export function contextWindowFor(model) {
+    if (!model)
+        return undefined;
+    for (const [pattern, window] of MODEL_WINDOWS) {
+        if (pattern.test(model))
+            return window;
+    }
+    return undefined;
+}
+export function providerFor(model) {
+    if (!model)
+        return "generic";
+    if (/claude/i.test(model))
+        return "anthropic";
+    if (/gpt|^o\d/i.test(model))
+        return "openai";
+    if (/gemini/i.test(model))
+        return "google";
+    return "generic";
+}
+/** Fraction of characters that are code-ish symbols — used to pick density. */
+function symbolDensity(text) {
+    if (text.length === 0)
+        return 0;
+    const symbols = text.match(/[{}[\]()<>;:=_\/\\|"'`#$%&*+^~-]/g);
+    return (symbols?.length ?? 0) / text.length;
+}
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    // Denser tokenization for code/JSON-like content, lighter for plain prose.
+    const density = symbolDensity(text);
+    const charsPerToken = density > 0.08 ? 3.2 : 4.0;
+    return Math.ceil(text.length / charsPerToken);
+}
+/** Per-message structural overhead (role markers, delimiters) is roughly constant. */
+export const MESSAGE_OVERHEAD_TOKENS = 4;
+export function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 10_000)
+        return `${Math.round(n / 1000)}k`;
+    if (n >= 1_000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return String(n);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "context-doctor",
+  "version": "0.2.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",
+    "context-window",
+    "tokens",
+    "prompt-engineering",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "openai",
+    "context-management",
+    "prompt-caching"
+  ],
+  "license": "MIT",
+  "author": "Kushal P",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KushalP1/context-doctor.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "context-doctor": "dist/cli.js",
+    "ctx-doctor": "dist/cli.js",
+    "context-doctor-mcp": "dist/mcp.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --test dist/test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/skills/context-doctor/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: context-doctor
+description: Keep the LLM context window lean and fast. Use when the conversation grows long, large content is pasted or produced by tools, the user asks "what's eating my context/tokens", asks to reduce cost or latency of LLM calls, or asks to profile/optimize/compact a conversation. Also triggers on "context doctor", "token usage", "context window", "prompt caching".
+---
+
+# Context Doctor — context hygiene for this session and the user's LLM apps
+
+You have two jobs when this skill triggers: (1) keep **this session's** context lean, and (2) help the user profile and optimize **their own** LLM conversations and apps using the context-doctor toolkit.
+
+## Principles of a healthy context window
+
+1. **Tool results are the #1 context killer.** After using a large tool result, carry forward only the extracted facts; never re-quote large outputs. If a tool returns >2k tokens and you need <10% of it, summarize the relevant part immediately in one sentence.
+2. **Never duplicate.** If a document, file, or result already appears earlier in the conversation, reference it ("the pricing doc from earlier") instead of re-pasting it.
+3. **Stable first, volatile last.** Prompt caches match byte-identical prefixes. Anything reusable (system prompts, tool definitions, reference docs) belongs before anything per-request. One changed byte early invalidates the cache for everything after it — this alone can be a 10x cost difference.
+4. **No base64 in text.** Images and files go through file/image APIs, never inline as base64 text.
+5. **Summarize old history.** Past ~30-40 turns, models lose the middle of the context. Proactively offer to compact: write a tight summary of the older turns, keep the recent ones verbatim.
+6. **Fewer input tokens = faster responses.** Time-to-first-token scales with input size. Every token trimmed is latency and money saved on EVERY subsequent call.
+
+## When the conversation you are in grows long
+
+Proactively (do not wait to be asked):
+- Summarize large tool outputs right after consuming them.
+- When the session passes roughly 30 turns or contains several large pastes, offer: "This conversation is getting heavy — want me to compact the older history into a summary so responses stay fast and cheap?"
+- When asked to summarize/compact, produce a dense factual summary (decisions made, current state, open items, key identifiers) — not a narrative.
+
+## Using the context-doctor tools
+
+If the `context-doctor` MCP tools are available:
+- `profile_context` — pass a conversation JSON (OpenAI or Anthropic format) or raw text; returns a token breakdown, largest messages, findings with estimated savings.
+- `optimize_context` — applies deterministic fixes (dedupe, trim stale tool results, strip base64; opt-in `prune-history`). When the result contains pruned-turn source material and asks for a summary, **you write that summary** (≤150 tokens, dense, factual) and place it where the stub indicates — this is how summarization works without any API key.
+- `context_best_practices` — provider-specific checklist to share with the user.
+
+If the tools are not connected, the CLI does the same: `npx context-doctor analyze <file> --model <model>` and `npx context-doctor optimize <file>`. For always-on optimization of the user's own apps: `npx context-doctor proxy` then point `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` at it.
+
+## When the user pastes a conversation or asks about their token usage
+
+1. Run `profile_context` (or suggest the CLI) rather than eyeballing.
+2. Lead with the top finding and its dollar/latency impact, not the full dump.
+3. Offer to apply the safe fixes via `optimize_context`; only suggest `prune-history` when the user confirms losing old detail is acceptable (and then write the replacement summary yourself).