context-doctor 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kushal P
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# 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.
+
+`context-doctor` is a zero-config profiler + optimizer for LLM contexts. It works with **Claude, GPT, Gemini** message formats, and plugs into **Claude Desktop, ChatGPT (developer mode), Cursor, Claude Code** — any MCP-capable app — or runs standalone from the terminal.
+
+```
+Where the tokens go
+────────────────────────────────────────────────────────
+Tool results      ████████████████░░░░░░░░░░░░  57%  ~41k
+System prompt     ██████░░░░░░░░░░░░░░░░░░░░░░  21%  ~15k
+Assistant replies ████░░░░░░░░░░░░░░░░░░░░░░░░  13%  ~9.4k
+User messages     ██░░░░░░░░░░░░░░░░░░░░░░░░░░   9%  ~6.5k
+
+Findings (4)
+────────────────────────────────────────────────────────
+✖ Message #12 contains a base64/binary blob (~8.2k tokens). [save ~7.4k]
+   → Never put base64 in text content — use the provider's file/image APIs.
+▲ Tool result at message #7 (web_search) is ~6.1k tokens. [save ~4.9k]
+   → Truncate or summarize large tool outputs before they enter history.
+```
+
+## 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:
+
+```bash
+npx context-doctor install
+```
+
+Restart your apps, then just ask Claude: *"what's eating my context?"* (`npx context-doctor uninstall` reverses it.)
+
+Or use the CLI directly, no install needed:
+
+```bash
+npx context-doctor analyze conversation.json --model claude-sonnet-5
+```
+
+```bash
+npx context-doctor optimize conversation.json --out slimmed.json
+```
+
+Input is any of: OpenAI chat format, Anthropic messages format (with `system` and content blocks), or a bare `[{role, content}]` array. Use `-` to pipe from stdin.
+
+Reports include **dollar and latency estimates**, not just tokens:
+
+```
+Cost:  ~$3.30 input per call · ~$3302 per 1k calls · ~13.2s of latency per call (estimates)
+...
+Potential recovery: ~5.9k tokens (~73% of context) ≈ $17.69 per 1k calls, 0.2s faster per call
+```
+
+## Profile your actual Claude Code sessions
+
+```bash
+npx context-doctor session            # profile your most recent session
+npx context-doctor session --list    # browse sessions
+```
+
+Parses the transcripts Claude Code writes locally and answers "where did my tokens go today?" — it will happily tell you that one giant skill load is 67% of your context.
+
+## Always-on: optimize every request automatically
+
+Run the proxy and every Anthropic/OpenAI API call your apps make gets optimized in flight — no code changes:
+
+```bash
+npx context-doctor proxy
+```
+
+Then point your app or SDK at it:
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8787      # Anthropic SDKs / tools
+export OPENAI_BASE_URL=http://localhost:8787/v1      # OpenAI SDKs / tools
+```
+
+The proxy dedupes repeated content, trims stale tool results, and strips base64 blobs from the message history of each request, then forwards it to the real API. Your API key passes through in headers untouched, streaming (SSE) works unchanged, and per-request savings are logged with upstream latency:
+
+```
+[context-doctor] POST /v1/messages → 200 in 842ms | optimized 7.3k → 518 tokens (2 changes) | session total: 6.9k tokens ≈ $0.021 saved
+```
+
+`GET http://localhost:8787/stats` returns cumulative savings (requests, tokens, estimated USD) since launch.
+
+Because prompt caching matches byte-identical prefixes, deterministic strategies are chosen so repeated requests stay stable — but if you rely on aggressive cache prefixes, start with `--strategy strip-base64 --strategy dedupe` and add more as you verify.
+
+> **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)
+
+`context-doctor` ships an MCP server, so the AI itself can profile and slim context on demand.
+
+**Claude Desktop** — add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "context-doctor": {
+      "command": "npx",
+      "args": ["-y", "context-doctor-mcp"]
+    }
+  }
+}
+```
+
+**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?"*
+
+### MCP tools
+
+| Tool | What it does |
+|---|---|
+| `profile_context` | Token breakdown by category, largest messages, findings with estimated savings |
+| `optimize_context` | Rewrites the conversation: dedupe, trim stale tool results, strip base64, optional history pruning |
+| `context_best_practices` | Curated checklist, optionally specialized for Anthropic / OpenAI |
+
+## Use it as a library
+
+```ts
+import { parseConversation, profileConversation, optimizeConversation } from "context-doctor";
+
+const profile = profileConversation(parseConversation(chatJson), "claude-sonnet-5");
+console.log(profile.totalTokens, profile.findings);
+
+const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJson, {
+  strategies: ["dedupe", "trim-tool-results", "strip-base64"],
+});
+```
+
+## What it detects
+
+- **Oversized tool results** — the #1 context killer in agent loops
+- **Duplicate content** — the same doc/result pasted twice
+- **Repeated identical tool calls** — a signal your agent forgot earlier results
+- **Base64 / binary blobs** in text content
+- **Long history** past the point where models track the middle
+- **Cache-hostile ordering** — volatile content before stable content breaks prompt caching (Anthropic `cache_control`, OpenAI automatic prefix caching)
+- **Window pressure** — usage % against the target model's real context window
+
+## What it fixes (deterministically — no LLM calls, no API keys)
+
+| Strategy | Lossy? | Default |
+|---|---|---|
+| `dedupe` — replace repeated content with a reference | No | ✅ |
+| `trim-tool-results` — truncate stale tool outputs | Mostly no | ✅ |
+| `strip-base64` — remove inline binary blobs | No (for the model) | ✅ |
+| `prune-history` — collapse old turns into a stub for summarization | Yes | opt-in |
+
+Everything the optimizer does is inspectable: it prints exactly which messages changed and how many tokens each change saved.
+
+**Summarization without an API key:** when `prune-history` runs through the MCP tools, context-doctor hands a digest of the pruned turns back to the model that called it (the Claude/GPT already running in your app) and asks *it* to write the replacement summary — LLM-quality compaction, zero extra cost, no keys.
+
+## The Agent Skill
+
+`skills/context-doctor/SKILL.md` (installed by `npx context-doctor install`) teaches Claude to practice context hygiene proactively: summarize big tool results after consuming them, never re-paste duplicated content, keep stable content cache-friendly, and offer compaction when a session gets heavy — so sessions get inherently leaner without you asking.
+
+## Why token counts are "~"
+
+Exact counts require each provider's private tokenizer. `context-doctor` uses a calibrated chars-per-token heuristic (denser for code/JSON) that lands within ~10% — plenty accurate for finding what's heavy and measuring savings, and it keeps the tool fully offline with zero configuration.
+
+## 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`
+
+Contributions welcome — this project is small on purpose. Open an issue before a big PR.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * context-doctor CLI
+ *
+ *   context-doctor analyze <file|-> [--model claude-sonnet-5] [--json]
+ *   context-doctor optimize <file|-> [--out file] [--strategy s]... [--keep-recent N] [--max-tool-tokens N]
+ *
+ * `-` reads from stdin, so you can pipe: `cat chat.json | context-doctor analyze -`
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * context-doctor CLI
+ *
+ *   context-doctor analyze <file|-> [--model claude-sonnet-5] [--json]
+ *   context-doctor optimize <file|-> [--out file] [--strategy s]... [--keep-recent N] [--max-tool-tokens N]
+ *
+ * `-` reads from stdin, so you can pipe: `cat chat.json | context-doctor analyze -`
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import process from "node:process";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { optimizeConversation } from "./optimize.js";
+import { renderProfile } from "./report.js";
+import { formatTokens } from "./tokens.js";
+import { startProxy } from "./proxy.js";
+import { runInstall, runUninstall } from "./install.js";
+import { listSessions, parseSessionFile } from "./session.js";
+const HELP = `context-doctor — profile and optimize LLM context windows
+
+Usage:
+  context-doctor analyze  <file|->  [options]   Show what's eating your tokens
+  context-doctor optimize <file|->  [options]   Apply safe fixes, print slimmed conversation
+  context-doctor proxy              [options]   Always-on: local proxy that optimizes every
+                                                Anthropic/OpenAI API request in flight
+  context-doctor install                        Wire the MCP server + skill into Claude Desktop,
+                                                Claude Code, and Cursor automatically
+  context-doctor uninstall                      Undo install
+  context-doctor session [file]                 Profile a Claude Code session transcript
+                                                (default: the most recent session; --list to browse)
+
+Input: a conversation JSON file (OpenAI or Anthropic message format, or a bare
+message array). Use "-" to read from stdin.
+
+Options:
+  --model <name>          Model name for window-size math (e.g. claude-sonnet-5, gpt-4o)
+  --json                  Machine-readable output
+  --out <file>            (optimize) Write result to file instead of stdout
+  --strategy <id>         (optimize) Strategy to run; repeatable.
+                          Available: dedupe, trim-tool-results, strip-base64, prune-history
+                          Default: dedupe, trim-tool-results, strip-base64 (lossless-ish set)
+  --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)
+  --upstream-anthropic <url>  (proxy) Override Anthropic upstream (testing)
+  --upstream-openai <url>     (proxy) Override OpenAI upstream (testing)
+  -h, --help              Show this help
+
+Examples:
+  context-doctor analyze chat.json --model claude-sonnet-5
+  context-doctor optimize chat.json --strategy dedupe --strategy prune-history --out slim.json
+  context-doctor proxy --port 8787
+    then: export ANTHROPIC_BASE_URL=http://localhost:8787
+          export OPENAI_BASE_URL=http://localhost:8787/v1
+`;
+function parseArgs(argv) {
+    const args = { json: false, strategies: [], list: false };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "-h":
+            case "--help":
+                console.log(HELP);
+                process.exit(0);
+            case "--json":
+                args.json = true;
+                break;
+            case "--list":
+                args.list = true;
+                break;
+            case "--model":
+                args.model = argv[++i];
+                break;
+            case "--out":
+                args.out = argv[++i];
+                break;
+            case "--strategy":
+                args.strategies.push(argv[++i]);
+                break;
+            case "--keep-recent":
+                args.keepRecent = Number(argv[++i]);
+                break;
+            case "--max-tool-tokens":
+                args.maxToolTokens = Number(argv[++i]);
+                break;
+            case "--port":
+                args.port = Number(argv[++i]);
+                break;
+            case "--upstream-anthropic":
+                args.upstreamAnthropic = argv[++i];
+                break;
+            case "--upstream-openai":
+                args.upstreamOpenai = argv[++i];
+                break;
+            default: positional.push(a);
+        }
+    }
+    args.command = positional[0];
+    args.file = positional[1];
+    return args;
+}
+function readInput(file) {
+    if (file === "-")
+        return readFileSync(0, "utf8");
+    return readFileSync(file, "utf8");
+}
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.command === "session") {
+        if (args.list) {
+            const sessions = listSessions();
+            if (sessions.length === 0) {
+                console.log("No Claude Code sessions found under ~/.claude/projects.");
+                return;
+            }
+            for (const s of sessions) {
+                console.log(`${s.modifiedAt.toISOString().slice(0, 16)}  ${(s.sizeBytes / 1024).toFixed(0).padStart(6)}KB  ${s.path}`);
+            }
+            return;
+        }
+        const path = args.file ?? listSessions(1)[0]?.path;
+        if (!path) {
+            console.error("No session transcript found. Pass a .jsonl path or run inside a machine with Claude Code sessions.");
+            process.exit(1);
+        }
+        let parsed;
+        try {
+            parsed = parseSessionFile(path);
+        }
+        catch (e) {
+            console.error(`Could not read session: ${e.message}`);
+            process.exit(1);
+        }
+        const profile = profileConversation(parseConversation(parsed.conversationJson), args.model ?? parsed.model);
+        if (args.json) {
+            console.log(JSON.stringify({ session: { path: parsed.path, title: parsed.title }, profile }, null, 2));
+        }
+        else {
+            console.log(`Session: ${parsed.title ?? "(untitled)"}\nFile:    ${parsed.path}\n`);
+            console.log(renderProfile(profile));
+        }
+        return;
+    }
+    if (args.command === "install") {
+        runInstall();
+        return;
+    }
+    if (args.command === "uninstall") {
+        runUninstall();
+        return;
+    }
+    if (args.command === "proxy") {
+        startProxy({
+            port: args.port,
+            anthropicUpstream: args.upstreamAnthropic,
+            openaiUpstream: args.upstreamOpenai,
+            strategies: args.strategies.length > 0 ? args.strategies : undefined,
+            keepRecent: args.keepRecent,
+            maxToolResultTokens: args.maxToolTokens,
+        });
+        return; // server keeps the process alive
+    }
+    if (!args.command || !args.file) {
+        console.log(HELP);
+        process.exit(args.command ? 1 : 0);
+    }
+    let input;
+    try {
+        input = readInput(args.file);
+    }
+    catch (e) {
+        console.error(`Could not read ${args.file}: ${e.message}`);
+        process.exit(1);
+    }
+    if (args.command === "analyze") {
+        const profile = profileConversation(parseConversation(input), args.model);
+        console.log(args.json ? JSON.stringify(profile, null, 2) : renderProfile(profile));
+        return;
+    }
+    if (args.command === "optimize") {
+        let result;
+        try {
+            result = optimizeConversation(input, {
+                strategies: args.strategies.length > 0 ? args.strategies : undefined,
+                keepRecent: args.keepRecent,
+                maxToolResultTokens: args.maxToolTokens,
+            });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        const output = JSON.stringify(result.conversation, null, 2);
+        if (args.out) {
+            writeFileSync(args.out, output);
+        }
+        else if (args.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(output);
+        }
+        const saved = result.tokensBefore - result.tokensAfter;
+        const pct = result.tokensBefore > 0 ? Math.round((saved / result.tokensBefore) * 100) : 0;
+        console.error(`\ncontext-doctor: ${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)} tokens ` +
+            `(saved ~${formatTokens(saved)}, ${pct}%) via ${result.applied.length} change(s)` +
+            (args.out ? ` — written to ${args.out}` : ""));
+        return;
+    }
+    console.error(`Unknown command: ${args.command}\n`);
+    console.log(HELP);
+    process.exit(1);
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * context-doctor — profile and optimize LLM context windows.
+ * Library entry point; see cli.ts for the CLI and mcp.ts for the MCP server.
+ */
+export { parseConversation } from "./parse.js";
+export type { NormalizedConversation, NormalizedMessage, MessageKind } from "./parse.js";
+export { profileConversation } from "./profile.js";
+export type { ContextProfile, Finding, FindingId, MessageProfile, Category } from "./profile.js";
+export { optimizeConversation } from "./optimize.js";
+export type { OptimizeOptions, OptimizeResult, AppliedChange, StrategyId } from "./optimize.js";
+export { renderProfile } from "./report.js";
+export { startProxy } from "./proxy.js";
+export type { ProxyOptions, ProxyStats } from "./proxy.js";
+export { listSessions, parseSessionFile } from "./session.js";
+export type { SessionInfo, ParsedSession } from "./session.js";
+export { pricingFor, inputCostUsd, estimatedTtftSeconds, formatUsd } from "./pricing.js";
+export type { ModelPricing } from "./pricing.js";
+export { estimateTokens, contextWindowFor, providerFor, formatTokens } from "./tokens.js";
+export type { Provider } from "./tokens.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * context-doctor — profile and optimize LLM context windows.
+ * Library entry point; see cli.ts for the CLI and mcp.ts for the MCP server.
+ */
+export { parseConversation } from "./parse.js";
+export { profileConversation } from "./profile.js";
+export { optimizeConversation } from "./optimize.js";
+export { renderProfile } from "./report.js";
+export { startProxy } from "./proxy.js";
+export { listSessions, parseSessionFile } from "./session.js";
+export { pricingFor, inputCostUsd, estimatedTtftSeconds, formatUsd } from "./pricing.js";
+export { estimateTokens, contextWindowFor, providerFor, formatTokens } from "./tokens.js";

package/dist/install.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One-command setup: `context-doctor install`
+ *
+ * Detects the AI apps present on this machine and wires the context-doctor
+ * MCP server into each, plus installs the Agent Skill for Claude Code.
+ * Every config edit is a careful JSON merge with a .backup file written first.
+ * `context-doctor uninstall` reverses it.
+ */
+export declare function runInstall(): void;
+export declare function runUninstall(): void;

package/dist/install.js

@@ -0,0 +1,120 @@
+/**
+ * One-command setup: `context-doctor install`
+ *
+ * Detects the AI apps present on this machine and wires the context-doctor
+ * MCP server into each, plus installs the Agent Skill for Claude Code.
+ * Every config edit is a careful JSON merge with a .backup file written first.
+ * `context-doctor uninstall` reverses it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+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 targets() {
+    const desktop = claudeDesktopConfigPath();
+    const claudeCode = join(homedir(), ".claude.json");
+    const cursor = join(homedir(), ".cursor", "mcp.json");
+    return [
+        { name: "Claude Desktop", configPath: desktop, detect: () => existsSync(dirname(desktop)) },
+        { name: "Claude Code", configPath: claudeCode, detect: () => existsSync(claudeCode) || existsSync(join(homedir(), ".claude")) },
+        { name: "Cursor", configPath: cursor, detect: () => existsSync(join(homedir(), ".cursor")) },
+    ];
+}
+/**
+ * The server command to write into configs. When running from a published
+ * install, npx keeps it auto-updating; from a local checkout, point at the
+ * built file directly so it works before the package is on npm.
+ */
+function serverEntry() {
+    const selfDir = dirname(fileURLToPath(import.meta.url));
+    const localMcp = join(selfDir, "mcp.js");
+    const runningFromNpx = (process.env.npm_execpath ?? "").includes("npx") || selfDir.includes("_npx");
+    if (!runningFromNpx && existsSync(localMcp)) {
+        return { command: process.execPath, args: [localMcp] };
+    }
+    return { command: "npx", args: ["-y", "context-doctor-mcp"] };
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${path} exists but is not valid JSON — fix or remove it first (${e.message})`);
+    }
+}
+function writeJsonWithBackup(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (existsSync(path))
+        copyFileSync(path, path + ".context-doctor.backup");
+    writeFileSync(path, JSON.stringify(data, null, 2));
+}
+function installSkill() {
+    const selfDir = dirname(fileURLToPath(import.meta.url));
+    // dist/install.js → package root is one level up; skills/ ships in the package.
+    const skillSource = join(selfDir, "..", "skills", "context-doctor", "SKILL.md");
+    if (!existsSync(skillSource))
+        return null;
+    const skillDest = join(homedir(), ".claude", "skills", "context-doctor");
+    mkdirSync(skillDest, { recursive: true });
+    copyFileSync(skillSource, join(skillDest, "SKILL.md"));
+    return join(skillDest, "SKILL.md");
+}
+export function runInstall() {
+    const entry = serverEntry();
+    const found = targets().filter((t) => t.detect());
+    if (found.length === 0) {
+        console.log("No supported AI apps detected (Claude Desktop, Claude Code, Cursor).");
+        console.log("Manual setup — add to your app's MCP config:");
+        console.log(JSON.stringify({ mcpServers: { "context-doctor": entry } }, null, 2));
+        return;
+    }
+    for (const target of found) {
+        try {
+            const config = readJson(target.configPath);
+            config.mcpServers = config.mcpServers ?? {};
+            config.mcpServers["context-doctor"] = entry;
+            writeJsonWithBackup(target.configPath, config);
+            console.log(`✓ ${target.name}: MCP server added (${target.configPath})`);
+        }
+        catch (e) {
+            console.error(`✗ ${target.name}: ${e.message}`);
+        }
+    }
+    const skillPath = installSkill();
+    if (skillPath)
+        console.log(`✓ Agent Skill installed for Claude Code (${skillPath})`);
+    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.');
+}
+export function runUninstall() {
+    for (const target of targets().filter((t) => t.detect())) {
+        try {
+            if (!existsSync(target.configPath))
+                continue;
+            const config = readJson(target.configPath);
+            if (config.mcpServers?.["context-doctor"]) {
+                delete config.mcpServers["context-doctor"];
+                writeJsonWithBackup(target.configPath, config);
+                console.log(`✓ ${target.name}: MCP server removed`);
+            }
+        }
+        catch (e) {
+            console.error(`✗ ${target.name}: ${e.message}`);
+        }
+    }
+    const skillDir = join(homedir(), ".claude", "skills", "context-doctor");
+    if (existsSync(skillDir)) {
+        rmSync(skillDir, { recursive: true });
+        console.log("✓ Agent Skill removed");
+    }
+    console.log("Done.");
+}

package/dist/mcp.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * context-doctor MCP server (stdio).
+ *
+ * Plug into Claude Desktop, ChatGPT desktop (developer mode), Cursor, or any
+ * MCP client:
+ *
+ *   { "mcpServers": { "context-doctor": { "command": "npx", "args": ["-y", "context-doctor-mcp"] } } }
+ *
+ * Tools:
+ *   profile_context   — analyze a conversation/prompt, report token breakdown + findings
+ *   optimize_context  — apply safe strategies, return the slimmed conversation
+ *   context_best_practices — curated checklist for a given provider/use case
+ */
+export {};