context-doctor 0.25.0 → 0.26.0

package/README.md

@@ -105,7 +105,7 @@ On a Claude subscription you do not pay list price; the same tokens come out of
 |---|---|---|
 | **Claude Code** in the terminal, VS Code or JetBrains | **Autopilot** clears stale tool output (cold cache only, never more expensive). **Hook** on every prompt: real context size, largest waste, and a `/compact` offer when you return to a large session after the cache expired. **`compact-window`**, if you set one |
 | **Claude Code** in the desktop app's Code tab | **Hook**, as above, including the cold-resume `/compact` offer, shown to you as well as the model. **`compact-window`**, if you set one: Claude Code compacts earlier by itself. Not autopilot: the app sets its own API address and ignores the one in settings | Install via npm or as a **plugin** (`/plugin marketplace add KushalP1/context-doctor`). Status bar context meter, `/context-doctor:savings`, `session`, `watch`, `report`, dashboard |
-| **Cursor** (agent) | Cursor runs Claude Code's hooks, so the same every-prompt check fires inside Cursor | MCP tools, editor status bar extension, `cursor` profiler. With your own OpenAI key, autopilot too via a tokened tunnel ([how](#putting-the-proxy-on-a-public-url-cursor-with-your-own-openai-key-remote-apps)) |
+| **Cursor** (agent) | A native **after-tool-call hook** (`~/.cursor/hooks.json`): in a heavy chat the agent gets the same hygiene guidance and the largest waste, once per 40% of growth. (Cursor's prompt hook can only allow or block a prompt, so this is the event where guidance reaches the model) | MCP tools, editor status bar extension, `cursor` profiler. With your own OpenAI key, autopilot too via a tokened tunnel ([how](#putting-the-proxy-on-a-public-url-cursor-with-your-own-openai-key-remote-apps)) |
 | **Codex** (ChatGPT app's Codex tab, IDE extension, CLI) | Every-prompt hook with the API's own token counts | MCP tools, skill, `session` reads Codex rollouts. On an API key, autopilot too (`OPENAI_BASE_URL`) |
 | **Your own apps on the Anthropic or OpenAI API** | Autopilot on `/v1/messages`, `/v1/chat/completions` and `/v1/responses` (`ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL`), or the full optimizing proxy | Exact usage and cache hit rates in `/stats`, prompt-cache placement advice |
 | **Claude Desktop chat** | Standing context rules in every chat; one cheap `profile_context` call the model makes past ~30 turns or on any cost question | One-click `.mcpb` install, `context_checkup` prompt |
@@ -116,6 +116,7 @@ Not claimed, because no process on your machine sends those requests: trimming i
 
 ## What's new
 
+- **0.26 Checked on every platform, three fixes**: tested end to end in Claude Code (terminal, desktop app, plugin from GitHub), Claude Desktop, Cursor, Codex on GPT-5.5, VS Code, the MCP server on every launch path, and the proxy on OpenAI's APIs. Found and fixed: Cursor's agent never received the hook's guidance (Cursor runs Claude Code's hook where output cannot add context), so `install` now adds a native Cursor hook; Codex blocked the MCP tools behind an approval it never grants in `codex exec`, so the tools are now marked read-only; autopilot skipped Codex's newest tools (`exec`, `wait`) and some of Cursor's. Also: a history imported into Codex no longer reads as "2136% of the window", and the chat-app settings paths are current.
 - **0.25 Compact earlier, by itself**: the `/compact` offer at cold resumes was followed 1 time in 33 on the author's machine, so two changes. The hook now also shows you the notice (it went only to the model, which rarely raised it), with the dollar cost of the message you just sent. And `context-doctor compact-window` measures and sets Claude Code's own auto-compact window, which works without anyone acting on advice, in every surface including the desktop app: 55% less input cost at 400k on the author's last 30 days. `savings` shows it as a third lever.
 - **0.20 Autopilot**: stale tool output cleared from every Claude Code request, only when the prompt cache is cold, so it cannot cost more (measured: 9.8% less input cost, ~$1,080 a month on the author's usage, no session worse); runs as a login service on macOS, Linux and Windows; now also for GPT via OpenAI's Chat Completions and Responses APIs.
 - **0.24 A full audit, fixed**: the session parser now rebuilds API messages from Claude Code's one-row-per-block transcripts (it had split each reply into several messages, breaking tool pairing in exported conversations and inflating profiles); the proxy forwards every non-conversation endpoint and never re-encodes bodies it does not rewrite (model listing and file uploads failed or were corrupted through it); `report` and the dashboard no longer count compaction as tokens context-doctor saved, and MCP sketches no longer inflate them; `watch` follows plain conversation files; MCP inputs are bounded. 0.23: four dependency vulnerabilities patched, no false `/compact` alarm after compacting, `savings --share`.
@@ -143,9 +144,10 @@ One run of `context-doctor install` writes these (each config edit makes a `.bac
 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 (Cursor runs it too)
-6. **Codex**, when present: MCP server in `~/.codex/config.toml`, the hook in `~/.codex/hooks.json`, the skill in `~/.codex/skills/`
-7. With `--statusline`: live context size, cache share and cost in Claude Code's status bar
+5. **Every-prompt hook** → `~/.claude/settings.json` — the per-query context check for Claude Code
+6. **Cursor hook**, when Cursor is present → `~/.cursor/hooks.json` (`postToolUse`) — the same check for Cursor's agent, after each tool call
+7. **Codex**, when present: MCP server in `~/.codex/config.toml`, the hook in `~/.codex/hooks.json`, the skill in `~/.codex/skills/`
+8. With `--statusline`: live context size, cache share and cost in Claude Code's status bar
 
 `context-doctor autopilot on` is separate and opt-in: it adds the background proxy service and one line (`env.ANTHROPIC_BASE_URL`) to `~/.claude/settings.json`, after the proxy has answered a health check.
 
@@ -329,15 +331,15 @@ Your API key still rides in the request headers, as before. The token protects t
 | Surface | Runs by itself | What that means |
 |---|---|---|
 | **Claude Code** | Yes: hook on every prompt, status line on every refresh | Past ~80k tokens the model receives hygiene guidance naming the largest waste; compaction is offered. Measured: 115 automatic checks, 48 warnings, across 32 sessions on one machine |
-| **Cursor** | **Yes**, since 0.15: Cursor loads Claude Code's hook config (`~/.claude/settings.json`) and runs the same hook on every agent prompt, passing its own transcript. Output is accepted through Cursor's Claude-compat layer | Same guidance as Claude Code, inside Cursor's agent, for everyone who ran `install`. Before 0.15 the hook fired but could not read Cursor's transcript format, so it said nothing |
+| **Cursor** | **Yes**, since 0.26: `install` adds a native `postToolUse` hook to `~/.cursor/hooks.json`; Cursor passes it the agent transcript, and its `additional_context` reaches the model | In a heavy chat, the agent gets hygiene guidance and the largest recoverable waste, once per 40% of growth. Cursor's transcript records tool calls but not their output, and keeps turns Cursor has since summarized, so the note gives the chat's accumulated size, with no window share or price. Corrected in 0.26: Cursor also runs Claude Code's hook, but as `beforeSubmitPrompt`, whose output can only allow or block the prompt, so from 0.15 to 0.25 the guidance never reached Cursor's model |
 | **API traffic through the proxy** | Yes: every request rewritten in flight | Fewer tokens, guaranteed, model not consulted |
 | **Claude Desktop** | The standing instruction in every chat (we confirmed in the app bundle that Desktop's `LocalMcpServerManager` reads it), a one-click `context_checkup` prompt, and since 0.17 a `profile_context` the model can actually afford to call from chat | Until 0.17 the tool wanted the whole conversation as its argument, so calling it from chat meant re-typing 50k tokens; nobody did, and Desktop's log showed zero calls in a month. Now the model passes a ~120-token **sketch** (turn count, the large or repeated blocks) and gets a sized estimate, findings and the fix to apply. Still a nudge, not a hook: Desktop chat has no hook API and no transcript on disk |
-| **Codex (OpenAI): ChatGPT.app's Codex tab, the Codex IDE extension, the `codex` CLI** | **Yes**, since 0.16: `install` writes the hook to `~/.codex/hooks.json`, the MCP server to `~/.codex/config.toml`, and the skill to `~/.codex/skills/`. Codex uses Claude Code's hook contract almost verbatim and passes its own rollout transcript, which carries the API's real usage figures | Same guidance as Claude Code, from measured tokens. One extra step, Codex's rule not ours: a new hook runs only after you trust it once (type `/hooks` in Codex). `session` and `session --list` read Codex rollouts too |
+| **Codex (OpenAI): ChatGPT.app's Codex tab, the Codex IDE extension, the `codex` CLI** | **Yes**, since 0.16: `install` writes the hook to `~/.codex/hooks.json`, the MCP server to `~/.codex/config.toml`, and the skill to `~/.codex/skills/`. Codex uses Claude Code's hook contract almost verbatim and passes its own rollout transcript, which carries the API's real usage figures | Same guidance as Claude Code, from measured tokens. One extra step, Codex's rule not ours: a new hook runs only after you trust it once (type `/hooks` in Codex). The MCP tools are marked read-only, so Codex runs them without an approval prompt, `codex exec` included. `session` and `session --list` read Codex rollouts too |
 | **ChatGPT chat UI** | No | No MCP, no hooks, no data path in the chat product itself. Use Codex, or a developer-mode connector at a URL you host |
 
 So "every chat inherently better" is true for Claude Code, Cursor, Codex and the proxy; for Claude Desktop it is "the rules ride in every chat and the checkup is one cheap tool call away"; and not a claim we make for the ChatGPT chat UI.
 
-**Where there is no hook and no MCP at all** (claude.ai on the web, the Claude and ChatGPT phone apps, plain ChatGPT): the app's per-account preferences are read on every turn, which is the closest those surfaces have to a hook. `context-doctor instructions --copy` puts the ~180-token rules on your clipboard and tells you where to paste them (claude.ai Settings > Profile; ChatGPT Settings > Personalization > Custom instructions).
+**Where there is no hook and no MCP at all** (claude.ai on the web, the Claude and ChatGPT phone apps, plain ChatGPT): the app's per-account preferences are read on every turn, which is the closest those surfaces have to a hook. `context-doctor instructions --copy` puts the ~180-token rules on your clipboard and tells you where to paste them (claude.ai Settings > General; ChatGPT Settings > Personalization > Custom instructions, "What traits should ChatGPT have?").
 
 **Do you need to configure anything by hand? Usually no:**
 
@@ -345,7 +347,7 @@ So "every chat inherently better" is true for Claude Code, Cursor, Codex and the
 |---|---|
 | Claude Desktop | `npx context-doctor install` writes the config — just restart the app. Or one click: download `context-doctor-<version>.mcpb` from the [latest release](https://github.com/KushalP1/context-doctor/releases) and open it (Settings > Extensions). The bundle runs on Desktop's own Node, no npm needed |
 | Claude Code | Same command — MCP + skill + every-prompt hook, all automatic |
-| Cursor | Same command — writes `~/.cursor/mcp.json`; the every-prompt hook is picked up from Claude Code's config, which Cursor reads |
+| Cursor | Same command — writes `~/.cursor/mcp.json` and the after-tool-call hook in `~/.cursor/hooks.json`. `context-doctor doctor` checks both |
 | Codex (OpenAI) | Same command — `~/.codex/config.toml`, `~/.codex/hooks.json`, `~/.codex/skills/`. Then, once, `/hooks` in Codex to trust the hook |
 | ChatGPT (developer mode) | **Manual + a reachable URL** — ChatGPT connects to servers over the internet, never local commands. Run `context-doctor-mcp --http` on a host/tunnel, then add the URL as a connector. Normal ChatGPT (no dev mode) has no MCP — use the CLI |
 
@@ -369,7 +371,7 @@ For any other MCP client, the server entry is:
 3. That call is cheap on purpose. Claude cannot export a Desktop chat, so it passes a **sketch**: how many turns, which blocks are large, repeated, stale or images, with one size hint each (~120 tokens). The server sizes it (usually within ±20%, measured; see "Why token counts are ~"), prices the per-turn re-read (on a subscription that is what spends your usage limit), and returns ranked findings with the action for each: "summarize *the nginx config* into the points still needed", "refer to *test output* by name", "offer a 300-token handoff summary for a fresh chat". The reply ends with an instruction to apply the top one, not just suggest it.
 4. One click instead of asking: the `context_checkup` prompt in the **+** menu sends that request for you.
 5. Say *"optimize it"* on an exported conversation 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).
-6. For the same rules on your phone and on claude.ai, where no MCP server runs: `context-doctor instructions --copy`, then paste into Settings > Profile > personal preferences.
+6. For the same rules on your phone and on claude.ai, where no MCP server runs: `context-doctor instructions --copy`, then paste into Settings > General > personal preferences.
 
 What this does not do: read the chat behind Claude's back or trim it for you. Desktop chat has no hook API and no transcript on disk (checked in the app bundle, v2.2553). The model does the trimming, when the rules and the checkup tell it to.
 
@@ -379,13 +381,13 @@ ChatGPT's MCP support differs fundamentally from Claude Desktop's: **it never sp
 
 1. **Normal ChatGPT (no developer mode): no MCP at all.** context-doctor still helps via the CLI: export the conversation and run `npx context-doctor analyze chat.json --model gpt-5` / `optimize` — no account settings required.
 2. **ChatGPT developer mode**: run our HTTP transport somewhere reachable — `context-doctor-mcp --http --port 8808` on a small host (bind `--host 0.0.0.0` there), or expose your machine temporarily with a tunnel (`ngrok http 8808`). Then Settings → Connectors → Advanced → Developer mode → add connector with URL `https://<your-host>/mcp`.
-3. Once connected, GPT gets the same three tools with the same trigger guidance: ask *"what's eating my context?"* → it calls `profile_context`; *"optimize it"* works the same, including GPT writing the pruning summary itself.
+3. Once connected, GPT gets the same three tools, each marked read-only (they only read their input and return text), with the same trigger guidance: ask *"what's eating my context?"* → it calls `profile_context`; *"optimize it"* works the same, including GPT writing the pruning summary itself.
 
 Security note for step 2: the HTTP endpoint is unauthenticated — put it behind your tunnel's auth or a reverse proxy if it stays up long-term.
 
 ### claude.ai on the web and the phone apps
 
-Your local MCP server can't reach the website, but the behavior can. Two options: `context-doctor instructions --copy` and paste into Settings > Profile > personal preferences (applies everywhere you are signed in, phone included), or upload `skills/context-doctor/SKILL.md` under Settings → Capabilities → Skills. Either way web and mobile conversations gain the same standing habits: summarize, don't re-quote, offer a handoff when heavy.
+Your local MCP server can't reach the website, but the behavior can. Two options: `context-doctor instructions --copy` and paste into Settings > General > personal preferences (applies everywhere you are signed in, phone included), or upload `skills/context-doctor/SKILL.md` under Settings → Capabilities → Skills. Either way web and mobile conversations gain the same standing habits: summarize, don't re-quote, offer a handoff when heavy.
 
 ### MCP tools
 
@@ -454,7 +456,7 @@ ctx 801k/1.0M ▮▮▮▮▮▮▮▮░░ 80% ⚠ · cache 100% · $12.34
 
 Live context against the model's window, a warning mark from 70%, the share served from cache, and the session's cost. It reads the size from the status payload when Claude Code provides it, and otherwise from the last 256KB of the transcript (about 1ms on a 20MB file; 80ms end to end including Node startup). It is opt-in and polite: there is only one status line, so it never overwrites one you already have, and `uninstall` removes only its own. Any failure prints nothing rather than an error.
 
-This is the "editor status bar" roadmap item, delivered for the editor most users of this tool are actually in. A VS Code / Cursor extension for the same number remains future work.
+The same number in VS Code and Cursor's status bar: see [the editor extension](#the-same-number-inside-vs-code-and-cursor).
 
 ## Does a smaller context actually help? Measure it
 
@@ -663,6 +665,18 @@ Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, an
 
 Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the six rules that keep this tool trustworthy (no API keys, nothing leaves the machine, no silent data loss, measurements not guesses, the hot path stays cheap, tests with every change) and a list of good first issues. What is planned next lives in [ROADMAP.md](./ROADMAP.md).
 
+Two end-to-end checks beyond `npm test`, both run against a throwaway `HOME`:
+
+```bash
+HOME=$(mktemp -d) node scripts/smoke-mcp.mjs node dist/mcp.js
+```
+
+```bash
+HOME=$(mktemp -d) node scripts/smoke-openai-proxy.mjs
+```
+
+The first connects to the MCP server the way a client does (it takes any launch command, `npx -y context-doctor mcp` included, or `--http <url>`), lists the tools and prompt, calls every tool and checks that bad input is rejected. The second runs the proxy against a local mock of OpenAI: streaming, the Responses API, usage capture and autopilot.
+
 ## License
 
 MIT © [gAI Ventures](https://gai.ventures)

package/dist/autoclear.js

@@ -45,10 +45,11 @@ import { estimateTokens } from "./tokens.js";
 export const CLEARABLE_TOOLS = new Set([
     // Claude Code
     "Read", "Bash", "BashOutput", "Grep", "Glob", "LS", "WebFetch", "WebSearch", "NotebookRead",
-    // Codex and other OpenAI-API agents
-    "shell", "exec_command", "local_shell", "read_file", "list_dir", "grep_search", "file_search", "web_search",
+    // Codex and other OpenAI-API agents. Codex's code mode runs every tool from
+    // one `exec` cell and polls long commands with `wait` (as Bash/BashOutput).
+    "shell", "exec_command", "local_shell", "read_file", "list_dir", "grep_search", "file_search", "web_search", "exec", "wait",
     // Cursor's agent
-    "Shell", "ReadFile", "rg", "run_terminal_cmd", "codebase_search",
+    "Shell", "ReadFile", "rg", "run_terminal_cmd", "codebase_search", "SemanticSearch", "ReadLints", "AwaitShell",
 ]);
 /** Tokens billed for one image inside a tool result (a full-size screenshot is ~1.6k on Claude). */
 const IMAGE_TOKENS = 1600;

package/dist/doctor.js

@@ -165,6 +165,24 @@ export async function runDoctor() {
     else {
         checks.push({ label: "Codex", status: "skip", detail: "not detected (ChatGPT's Codex agent, IDE extension or CLI)" });
     }
+    // Cursor: its agent gets the guidance through a native postToolUse hook
+    // (the Claude Code hook it also runs cannot add context there).
+    if (existsSync(join(homedir(), ".cursor"))) {
+        const hooksPath = join(homedir(), ".cursor", "hooks.json");
+        try {
+            const hooks = existsSync(hooksPath) ? JSON.parse(readFileSync(hooksPath, "utf8")) : {};
+            const ours = (hooks.hooks?.postToolUse ?? []).map((e) => e.command ?? "").find((c) => /(cli\.js|context-doctor(\.cmd|\.exe|\.bat)?)"?\s+hook\s*$/.test(c));
+            const missing = ours ? hookBinaryMissing(ours) : undefined;
+            checks.push(!ours
+                ? { label: "Cursor hook", status: "fail", detail: "not registered — run: context-doctor install" }
+                : missing
+                    ? { label: "Cursor hook", status: "fail", detail: `registered, but ${missing} no longer exists — re-run: context-doctor install` }
+                    : { label: "Cursor hook", status: "ok", detail: "registered in ~/.cursor/hooks.json (after each tool call in heavy chats)" });
+        }
+        catch (e) {
+            checks.push({ label: "Cursor hook", status: "fail", detail: `~/.cursor/hooks.json unreadable (${e.message})` });
+        }
+    }
     // Status line (opt-in, so absence is a note, not a failure)
     if (existsSync(settingsPath)) {
         try {

package/dist/hook.d.ts

@@ -1,5 +1,6 @@
 /**
- * Claude Code UserPromptSubmit hook: runs on EVERY query in Claude Code.
+ * Claude Code UserPromptSubmit hook: runs on EVERY query in Claude Code (and
+ * Codex, same format), and after every tool call in Cursor (postToolUse).
  *
  * Claude Code pipes hook input as JSON on stdin ({session_id, transcript_path,
  * prompt, ...}). We profile the session transcript; when the context is lean

package/dist/hook.js

@@ -1,5 +1,6 @@
 /**
- * Claude Code UserPromptSubmit hook: runs on EVERY query in Claude Code.
+ * Claude Code UserPromptSubmit hook: runs on EVERY query in Claude Code (and
+ * Codex, same format), and after every tool call in Cursor (postToolUse).
  *
  * Claude Code pipes hook input as JSON on stdin ({session_id, transcript_path,
  * prompt, ...}). We profile the session transcript; when the context is lean
@@ -18,7 +19,7 @@ import { recordLedger, statePath } from "./ledger.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
-import { formatTokens, CHARS_PER_TOKEN } from "./tokens.js";
+import { formatTokens, CHARS_PER_TOKEN, LARGEST_WINDOW } from "./tokens.js";
 import { ensureProxyUp } from "./autopilot.js";
 import { detectColdResume, renderColdResume, renderColdResumeNotice } from "./coldresume.js";
 import { formatUsd, pricingFor } from "./pricing.js";
@@ -145,13 +146,23 @@ export async function runHook() {
         }
         const input = JSON.parse(await readStdin());
         await heal;
+        // Cursor runs this hook twice over: Claude Code's UserPromptSubmit as its
+        // beforeSubmitPrompt (which cannot add context, so there is nothing to do),
+        // and natively after each tool call, where `additional_context` reaches
+        // the model. Codex and Claude Code send UserPromptSubmit.
+        // Cursor marks every hook input with cursor_version; any of its events but
+        // postToolUse would only spend the once-per-growth warning on output Cursor
+        // drops.
+        const cursor = input.hook_event_name === "postToolUse";
+        if (input.hook_event_name === "beforeSubmitPrompt" || (input.cursor_version && !cursor))
+            return;
         const transcriptPath = input.transcript_path;
         if (!transcriptPath || !existsSync(transcriptPath))
             return;
         // Fast path 1: a small transcript cannot exceed the threshold — exit on a
         // single stat() without reading the file. This is the every-prompt cost
         // for lean sessions: ~1ms.
-        const { config } = loadConfig(input.cwd ?? process.cwd());
+        const { config } = loadConfig(input.cwd ?? input.workspace_roots?.[0] ?? process.cwd());
         const threshold = warnThreshold(config.budget?.maxTokens);
         const sizeBytes = statSync(transcriptPath).size;
         if (sizeBytes < minBytesForWarn(threshold))
@@ -159,7 +170,7 @@ export async function runHook() {
         // Fast path 2: growth gate BEFORE parsing. If the file hasn't grown ~40%
         // since the last full parse, nothing new can trigger — exit without the
         // expensive read. Heavy-but-quiet sessions cost one stat + tiny state read.
-        const sessionId = input.session_id ?? transcriptPath;
+        const sessionId = input.session_id ?? input.conversation_id ?? transcriptPath;
         const prev = readSessionState(sessionId);
         // Cold resume: back on a large session after the cache expired. Checked
         // before the growth gate, because a return after idle involves no growth.
@@ -177,12 +188,19 @@ export async function runHook() {
         const emit = (lines) => {
             if (lines.length === 0 && !notice)
                 return;
+            const block = `<context-doctor>\n${lines.join("\n")}\n</context-doctor>`;
+            if (cursor) {
+                // Cursor's postToolUse has no user-facing field, so only the model's note goes out.
+                if (lines.length > 0)
+                    console.log(JSON.stringify({ additional_context: block }));
+                return;
+            }
             const out = {};
             // systemMessage is shown to the user in the app; additionalContext goes to the model.
             if (notice)
                 out.systemMessage = notice;
             if (lines.length > 0)
-                out.hookSpecificOutput = { hookEventName: "UserPromptSubmit", additionalContext: `<context-doctor>\n${lines.join("\n")}\n</context-doctor>` };
+                out.hookSpecificOutput = { hookEventName: "UserPromptSubmit", additionalContext: block };
             console.log(JSON.stringify(out));
         };
         if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR) {
@@ -195,7 +213,8 @@ export async function runHook() {
         const parsed = parseSessionFile(transcriptPath);
         if (parsed.messageCount === 0)
             return;
-        const profile = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
+        const model = parsed.model ?? input.model;
+        const profile = profileConversation(parseConversation(parsed.conversationJson), model);
         // Prefer the API's own figure when the transcript carries it: it includes
         // the system prompt and tool schemas the transcript omits, so it is the
         // real context size rather than a message-only estimate.
@@ -208,15 +227,27 @@ export async function runHook() {
             emit(notes);
             return;
         }
-        const windowPct = profile.contextWindow ? (liveTokens / profile.contextWindow) * 100 : undefined;
+        // An estimate past the window (no API figure, e.g. a history imported into
+        // Codex) is not the live context: the app must already be trimming it.
+        const overWindow = !cursor && parsed.reportedInputTokens === undefined && liveTokens > (profile.contextWindow ?? LARGEST_WINDOW);
+        const windowPct = !cursor && !overWindow && profile.contextWindow ? (liveTokens / profile.contextWindow) * 100 : undefined;
         // Agent sessions run on the prompt cache: a message normally re-reads the
         // context at the cached rate (0.1x) and pays the full rate only when the
         // cache has expired. Quoting the uncached figure alone overstated the
         // per-message cost tenfold (fixed in 0.22).
-        const pricing = pricingFor(parsed.model);
+        const pricing = pricingFor(model);
         const cachedUsd = pricing ? (liveTokens * pricing.cacheReadPerM) / 1e6 : undefined;
         const coldUsd = pricing ? (liveTokens * pricing.inputPerM * 1.25) / 1e6 : undefined;
-        const lines = [
+        // Cursor's agent transcript records tool calls but not their output, and
+        // keeps turns Cursor has since summarized, so it measures how much the chat
+        // has accumulated, not the live context: no window share or price for it.
+        const lines = cursor ? [
+            `This chat has accumulated ~${formatTokens(liveTokens)} tokens of messages and tool calls (tool output not counted; Cursor summarizes older turns itself, so the live context may differ).`,
+            "Practice context hygiene from here on: summarize large tool results instead of keeping them verbatim, reference earlier content rather than re-reading or re-quoting it, and keep responses lean.",
+        ] : overWindow ? [
+            `This session's transcript holds ~${formatTokens(liveTokens)} tokens, more than ${profile.contextWindow ? `the model's ~${formatTokens(profile.contextWindow)}` : "any current model's"} window, so the app is already summarizing or dropping older turns; what the model sees is a part of it.`,
+            "Practice context hygiene from here on: summarize large tool results instead of keeping them verbatim, reference earlier content rather than re-reading or re-quoting it, and keep responses lean.",
+        ] : [
             `This session's context is at ~${formatTokens(liveTokens)} tokens` +
                 (windowPct !== undefined ? ` (${windowPct.toFixed(0)}% of the window)` : "") +
                 (cachedUsd !== undefined ? `: each message re-reads it for ~${formatUsd(cachedUsd)} from the prompt cache, ~${formatUsd(coldUsd)} when the cache has expired` : "") +
@@ -233,7 +264,9 @@ export async function runHook() {
             lines.push(`Largest recoverable waste: ${topFinding.message} (${topFinding.suggestion})`);
         }
         if (liveTokens > threshold * 2) {
-            lines.push("If it fits the flow, offer the user a compaction of the older history.");
+            lines.push(cursor
+                ? "If the task changes, suggest the user start a new chat from a short summary of this one."
+                : "If it fits the flow, offer the user a compaction of the older history.");
         }
         emit([...notes, ...lines]);
     }

package/dist/install.d.ts

@@ -31,6 +31,16 @@ export declare function isEphemeralPath(path: string): boolean;
  * ours. Returns what happened so install can print the truth.
  */
 export declare function installStatusLine(): "installed" | "already" | "kept-foreign" | "no-claude-code";
+/**
+ * Cursor runs Claude Code's UserPromptSubmit hook as its own
+ * beforeSubmitPrompt, which can only allow or block a prompt: what the hook
+ * says never reaches Cursor's model. Cursor's postToolUse can add context
+ * (`additional_context`), and its input carries the agent transcript, so the
+ * check runs there, in Cursor's own ~/.cursor/hooks.json. It fires after every
+ * tool call, which the hook's stat-only fast path and regrowth gate make cheap.
+ */
+export declare function cursorHooksPath(): string;
+export declare function installCursorHook(): string | null;
 export declare function codexDir(): string;
 /**
  * Add or replace our [mcp_servers.context-doctor] table in config.toml without

package/dist/install.js

@@ -237,6 +237,53 @@ function installHookInto(settingsPath, gateDir) {
 function uninstallHook() {
     uninstallHookFrom(join(homedir(), ".claude", "settings.json"), "Claude Code every-prompt hook");
     uninstallHookFrom(join(homedir(), ".codex", "hooks.json"), "Codex every-prompt hook");
+    uninstallCursorHook();
+}
+/**
+ * Cursor runs Claude Code's UserPromptSubmit hook as its own
+ * beforeSubmitPrompt, which can only allow or block a prompt: what the hook
+ * says never reaches Cursor's model. Cursor's postToolUse can add context
+ * (`additional_context`), and its input carries the agent transcript, so the
+ * check runs there, in Cursor's own ~/.cursor/hooks.json. It fires after every
+ * tool call, which the hook's stat-only fast path and regrowth gate make cheap.
+ */
+export function cursorHooksPath() {
+    return join(homedir(), ".cursor", "hooks.json");
+}
+const isOurCursorEntry = (e) => /(cli\.js|context-doctor(\.cmd|\.exe|\.bat)?)"?\s+hook\s*$/.test(String(e?.command ?? ""));
+export function installCursorHook() {
+    if (!existsSync(join(homedir(), ".cursor")))
+        return null;
+    const path = cursorHooksPath();
+    const config = readJson(path);
+    config.version = config.version ?? 1;
+    config.hooks = config.hooks ?? {};
+    const entries = config.hooks.postToolUse ?? [];
+    const want = hookCommand();
+    const ours = entries.filter(isOurCursorEntry);
+    if (ours.length === 1 && ours[0].command === want)
+        return path; // already correct
+    config.hooks.postToolUse = [...entries.filter((e) => !isOurCursorEntry(e)), { command: want, timeout: 10 }];
+    writeJsonWithBackup(path, config);
+    return path;
+}
+function uninstallCursorHook() {
+    const path = cursorHooksPath();
+    if (!existsSync(path))
+        return;
+    const config = readJson(path);
+    const entries = config.hooks?.postToolUse;
+    if (!entries)
+        return;
+    const filtered = entries.filter((e) => !isOurCursorEntry(e));
+    if (filtered.length === entries.length)
+        return;
+    if (filtered.length === 0)
+        delete config.hooks.postToolUse;
+    else
+        config.hooks.postToolUse = filtered;
+    writeJsonWithBackup(path, config);
+    console.log("✓ Cursor after-tool-call hook removed");
 }
 function uninstallHookFrom(settingsPath, label) {
     if (!existsSync(settingsPath))
@@ -440,6 +487,15 @@ export function runInstall(options = {}) {
         console.error(`✗ Claude Code every-prompt hook: ${e.message}`);
         failures.push("Claude Code hook");
     }
+    try {
+        const cursorHook = installCursorHook();
+        if (cursorHook)
+            console.log(`✓ Cursor after-tool-call hook installed (${cursorHook}) — Cursor's agent gets the same guidance in heavy sessions`);
+    }
+    catch (e) {
+        console.error(`✗ Cursor hook: ${e.message}`);
+        failures.push("Cursor hook");
+    }
     installCodex(entry, failures);
     if (options.statusLine) {
         try {

package/dist/mcp.js

@@ -49,7 +49,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.25.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.26.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~120 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({
@@ -68,7 +68,9 @@ function createServer() {
             })).max(500).describe("Only the blocks over ~500 tokens, repeated, or images. Plain turns need not be listed."),
         }).optional().describe("Coarse description of the conversation for chat apps. One size hint per block: lines for code, words for prose, chars (or tokens) for logs and tool output, which vary most per line."),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),
-    }, async ({ conversation, sketch, model }) => {
+    }, 
+    // Pure: reads its input and returns text. Clients (Codex, ChatGPT) may skip approval for read-only tools.
+    { title: "Profile context", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ conversation, sketch, model }) => {
         if (sketch) {
             return { content: [{ type: "text", text: runSketch({ ...sketch, model: sketch.model ?? model }) }] };
         }
@@ -87,7 +89,9 @@ function createServer() {
             .describe("Strategies to apply. Default: dedupe, trim-tool-results, strip-base64. Add trim-tool-calls to shrink big inline file writes, or prune-history for lossy compaction of old turns."),
         keep_recent: z.number().int().nonnegative().optional().describe("Messages at the tail to leave untouched (default 6; 0 = none)"),
         max_tool_result_tokens: z.number().int().positive().optional().describe("Token budget for trimmed tool results (default 300)"),
-    }, async ({ conversation, strategies, keep_recent, max_tool_result_tokens }) => {
+    }, 
+    // Pure: reads its input and returns text. Clients (Codex, ChatGPT) may skip approval for read-only tools.
+    { title: "Optimize context", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ conversation, strategies, keep_recent, max_tool_result_tokens }) => {
         const result = optimizeConversation(conversation, {
             strategies: strategies,
             keepRecent: keep_recent,
@@ -148,7 +152,9 @@ function createServer() {
     }));
     server.tool("context_best_practices", "Get a curated checklist of context-management best practices, optionally specialized for a provider (anthropic, openai).", {
         provider: z.enum(["general", "anthropic", "openai"]).optional().describe("Provider to specialize tips for (default: general)"),
-    }, async ({ provider }) => {
+    }, 
+    // Pure: reads its input and returns text. Clients (Codex, ChatGPT) may skip approval for read-only tools.
+    { title: "Context best practices", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ provider }) => {
         const tips = [...BEST_PRACTICES.general, ...(provider && provider !== "general" ? BEST_PRACTICES[provider] : [])];
         return { content: [{ type: "text", text: tips.map((t, i) => `${i + 1}. ${t}`).join("\n") }] };
     });

package/dist/preferences.js

@@ -16,8 +16,8 @@ export const CHAT_PREFERENCES = [
 ].join(" ");
 /** Where to paste, per app. Paths are the UI labels, not URLs, so they survive redesigns. */
 export const PREFERENCE_TARGETS = [
-    "claude.ai / Claude Desktop / Claude mobile: Settings > Profile > \"What personal preferences should Claude consider in responses?\"",
-    "ChatGPT: Settings > Personalization > Custom instructions > \"How would you like ChatGPT to respond?\"",
+    "claude.ai / Claude Desktop / Claude mobile: Settings > General > \"What personal preferences should Claude consider in responses?\"",
+    "ChatGPT: Settings > Personalization > Custom instructions > \"What traits should ChatGPT have?\"",
 ];
 /** Copy text to the system clipboard; false when no clipboard tool is available. */
 export function copyToClipboard(text, platform = process.platform) {

package/dist/proxy.d.ts

@@ -47,7 +47,7 @@ export interface ProxyOptions extends OptimizeOptions {
     openaiUpstream?: string;
 }
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export declare const PROXY_VERSION = "0.25.0";
+export declare const PROXY_VERSION = "0.26.0";
 /**
  * Remove a leading `/t/<token>` from a request path, or return undefined when
  * the prefix is absent or the token differs. The comparison is constant time

package/dist/proxy.js

@@ -20,7 +20,7 @@ import { formatTokens, CHARS_PER_TOKEN, providerFor } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
 import { recordLedger } from "./ledger.js";
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export const PROXY_VERSION = "0.25.0";
+export const PROXY_VERSION = "0.26.0";
 /** Connection-level headers that must not be forwarded. */
 const SKIP_REQUEST_HEADERS = new Set(["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
 const SKIP_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);
@@ -384,7 +384,9 @@ export function startProxy(opts = {}) {
         console.error(`context-doctor proxy listening on http://${host}:${port}`);
         console.error(`  Anthropic apps/SDKs: export ANTHROPIC_BASE_URL=http://localhost:${port}${prefix}`);
         console.error(`  OpenAI apps/SDKs:    export OPENAI_BASE_URL=http://localhost:${port}${prefix}/v1`);
-        console.error(`  Every request's context is optimized in flight; savings are logged here.`);
+        console.error(opts.autopilot
+            ? `  Autopilot: stale re-runnable tool output is cleared only when the prompt cache is cold; savings are logged here.`
+            : `  Every request's context is optimized in flight; savings are logged here.`);
         console.error(`  Cumulative savings: http://localhost:${port}${prefix}/stats`);
         if (opts.token) {
             console.error(`  Token required: every path except /health must start with /t/<token>/.`);

package/dist/tokens.d.ts

@@ -9,6 +9,8 @@
  * fully offline.
  */
 export type Provider = "anthropic" | "openai" | "google" | "generic";
+/** The largest window any model above has: no live context can exceed it. */
+export declare const LARGEST_WINDOW: number;
 export declare function contextWindowFor(model?: string): number | undefined;
 export declare function providerFor(model?: string): Provider;
 /**

package/dist/tokens.js

@@ -22,6 +22,8 @@ const MODEL_WINDOWS = [
     [/llama.*3/i, 128_000],
     [/mistral|mixtral/i, 32_000],
 ];
+/** The largest window any model above has: no live context can exceed it. */
+export const LARGEST_WINDOW = Math.max(...MODEL_WINDOWS.map(([, w]) => w));
 export function contextWindowFor(model) {
     if (!model)
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "See what your Claude Code sessions cost and cut it: offers /compact when you return to a large session after the cache expired (every surface, desktop app included), and a cache-safe autopilot for terminal, IDE and API traffic. Token profiler, hooks, MCP tools and a Claude Code plugin.",
   "keywords": [
     "agent",