context-doctor 0.3.1 → 0.3.3

package/README.md

@@ -42,6 +42,45 @@ Restart your apps, then just ask Claude: *"what's eating my context?"* (`npx con
 
 **No API keys, ever.** Everything is deterministic local code; when an LLM is needed (summarizing pruned history), the model already running in your app does it. The proxy forwards *your app's* credentials untouched — context-doctor itself holds nothing.
 
+## What `install` actually does — and what happens in every session after
+
+One run of `npx context-doctor install` writes five things (each config edit makes a `.backup` first; `uninstall` reverses all of it):
+
+1. **Claude Desktop config** (`claude_desktop_config.json`) — registers the MCP server
+2. **Claude Code config** (`~/.claude.json`) — registers the MCP server
+3. **Cursor config** (`~/.cursor/mcp.json`) — registers the MCP server
+4. **Agent Skill** → `~/.claude/skills/context-doctor/` — context-hygiene playbook for Claude Code
+5. **Every-prompt hook** → `~/.claude/settings.json` — the per-query context check for Claude Code
+
+**In every chat afterward (Claude Desktop, Cursor):** when the conversation starts, the app launches the MCP server, which hands the model standing instructions that stay in force for the whole chat:
+
+- summarize large pastes and tool results instead of carrying them verbatim,
+- reference earlier content instead of re-quoting it, never inline base64,
+- once the chat passes ~30 turns or accumulates big pastes, *proactively offer to profile it*,
+- answer any "what's eating my context / cost / latency" question by calling `profile_context`, not by guessing.
+
+**In every Claude Code / Cowork session afterward:** all of the above via MCP, plus two more layers:
+
+- the **skill** loads whenever context work is relevant, and
+- the **hook runs on every single prompt you send**: it measures the session's real size in ~100ms. Under 80k tokens it stays completely silent. Above, it injects a note the model sees with your message — actual token count, cost per message, the single largest recoverable waste — with instructions to work leaner and offer you compaction. It re-fires only after ~40% further growth, and can never break a prompt (any failure exits silently).
+
+**What it never does:** delete or rewrite your history without asking (pruning is consent-only, and the model writes the replacement summary so nothing is lost silently), send data anywhere (everything runs on your machine), or touch an API key.
+
+## Do you need MCP? Only sometimes — all the ways to use context-doctor
+
+MCP is just one of six delivery mechanisms. It's only required when you want the AI **inside a chat app** to run the tools itself. Everything else works without it:
+
+| How you use it | MCP needed? | What it requires |
+|---|---|---|
+| **CLI** — `analyze`, `optimize`, `session` on files/transcripts | ❌ No | Nothing but `npx` — works in any terminal, scripts, CI |
+| **Proxy** — always-on optimization of your API apps | ❌ No | `context-doctor proxy` + one env var in your app |
+| **Claude Code every-prompt hook** | ❌ No | Written by `install`; Claude Code invokes it directly |
+| **Agent Skill** — hygiene behavior in Claude Code / claude.ai | ❌ No | A markdown file; `install` places it (or upload to claude.ai) |
+| **Library** — `import { profileConversation } from "context-doctor"` | ❌ No | `npm install context-doctor` in your project |
+| **In-chat tools** — Claude Desktop, ChatGPT desktop, Cursor chat | ✅ Yes | This is the only MCP piece — so the model itself can call `profile_context` / `optimize_context` mid-conversation |
+
+Practical upshot: a developer who only wants cheaper, faster API calls never touches MCP (proxy + CLI). A Claude Code user gets the hook and skill without MCP either — the MCP server just adds in-chat tools on top. `install` sets up all of it at once precisely so you don't have to think about which mechanism is which.
+
 ## What "always-on" means, per surface
 
 | Where you run LLMs | Mechanism | Guarantee |
@@ -115,7 +154,16 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 
 `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):
+**Do you need to configure anything by hand? Usually no:**
+
+| App | Setup |
+|---|---|
+| 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` |
+
+For any other MCP client, the server entry is:
 
 ```json
 {
@@ -128,8 +176,6 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 }
 ```
 
-**ChatGPT desktop** (developer mode), **Cursor**, **Claude Code** (`claude mcp add context-doctor -- npx -y context-doctor-mcp`), and any other MCP client: same command, their config syntax.
-
 ### How it works in Claude Desktop, step by step
 
 1. Run `npx context-doctor install` (writes the config above for you) and restart Claude Desktop.

package/dist/mcp.js

@@ -31,7 +31,7 @@ const SERVER_INSTRUCTIONS = `context-doctor keeps this conversation's context wi
 2. When the conversation has grown long (roughly 30+ turns) or contains several large pastes, proactively offer to profile it and call profile_context — do not wait to be asked.
 3. When the user asks anything about token usage, cost, latency, or "what's eating my context", call profile_context immediately rather than estimating by eye.
 4. When optimize_context returns a pruned-turns digest, YOU write the replacement summary (dense, factual, ≤150 tokens) as instructed in the result.`;
-const server = new McpServer({ name: "context-doctor", version: "0.3.1" }, { instructions: SERVER_INSTRUCTIONS });
+const server = new McpServer({ name: "context-doctor", version: "0.3.3" }, { 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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",