context-doctor 0.3.0 → 0.3.2

package/README.md

@@ -42,6 +42,30 @@ 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.
+
 ## What "always-on" means, per surface
 
 | Where you run LLMs | Mechanism | Guarantee |
@@ -111,11 +135,20 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 
 > **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)
+## Use with the Claude & ChatGPT apps
 
 `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,9 +161,25 @@ 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
 
-Then just ask: *"profile this conversation with context-doctor"* or paste an exported chat and say *"what's eating my context?"*
+1. Run `npx context-doctor install` (writes the config above for you) and restart Claude Desktop.
+2. From then on, **every conversation automatically carries context-doctor's standing instructions** — the MCP server hands Claude hygiene rules on connect: summarize big pastes instead of re-quoting them, offer profiling when the chat gets long, never inline base64.
+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
+
+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.
+
+For ChatGPT on the web (no MCP): export the conversation and use the CLI — `npx context-doctor analyze chat.json --model gpt-5`.
+
+### claude.ai on the web
+
+Your local MCP server can't reach the website, but the behavior can: upload `skills/context-doctor/SKILL.md` under Settings → Capabilities → Skills, and web conversations gain the same standing context-hygiene habits (summarize-don't-requote, offer compaction when heavy).
 
 ### MCP tools
 
@@ -195,6 +244,19 @@ Exact counts require each provider's private tokenizer. `context-doctor` uses a
 
 Contributions welcome — this project is small on purpose. Open an issue before a big PR.
 
+## Releasing (maintainers)
+
+```bash
+npm version patch        # or minor/major — bumps package.json + git tag
+npm test                 # 14 tests must pass; CI runs the same on 3 OSes
+npm publish              # prompts for the npm 2FA code
+git push --follow-tags
+```
+
+Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doctor`** on a package that clearly exists, the real cause is an **expired npm login token** — npm reports unauthenticated publishes as a 404, not a 401. Check with `npm whoami`; if that errors, run `npm login` and publish again.
+
+Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, and remember `dist/` is committed — run `npm run build` before committing so the CI dist-sync check passes.
+
 ## License
 
 MIT

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.0" }, { instructions: SERVER_INSTRUCTIONS });
+const server = new McpServer({ name: "context-doctor", version: "0.3.2" }, { 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.0",
+  "version": "0.3.2",
   "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",