context-doctor 0.24.0 → 0.26.0

package/README.md

@@ -7,6 +7,7 @@
 Long agent sessions fill up with tool output nobody reads again, and a 500k-token session re-reads all of it on every message. The most expensive moment is coming back after lunch: the prompt cache has expired, so the next message re-sends everything at full price. `context-doctor` measures this on your own sessions and acts on it at the moments that pay.
 
 - **Tells you when to `/compact`, at the moment it pays.** When you come back to a large session after the cache expired, the every-prompt hook gives the model the numbers and it offers `/compact` once. Replayed over 133 days of the author's Claude Code history: 401 such returns, and compacting then would have saved **$4,053 net at list price, about $914 a month**. It works in every Claude Code surface, including the desktop app. [What it saves →](#what-it-saves)
+- **Compacts earlier, automatically, in every Claude Code surface.** Claude Code auto-compacts near the full window (measured: ~970k tokens on a 1M model), so long sessions re-read 400k-900k tokens on every message. `context-doctor compact-window` replays your history at smaller windows and, if you choose, sets Claude Code's own `autoCompactWindow`. On the author's last 30 days: **a 400k window would have cut input cost 55%** ($6,119 to $2,757), for 15 compactions a week instead of 5. A native setting, so it works in the desktop app too. [The trade-off →](#3-compacting-earlier-automatic)
 - **Autopilot for terminal and IDE sessions and API apps:** a local proxy that clears stale tool output only when the prompt cache is cold, so it never costs more. **9.8% less input cost, no session made more expensive**, in the same replay. (The desktop app's Code tab sets its own API address, so autopilot cannot reach it; `doctor` tells you if that is your case.)
 - **Counts Claude correctly.** Current Claude models pack 2.75 characters per token, not the 4 most tools assume, so estimates built on 4 undercount Claude by about 40%. The ratios were measured from the API's own counts; `context-doctor accuracy` re-checks them on yours.
 - **Works where you work:** Claude Code (terminal, IDE, desktop app, plugin), Cursor, Codex, Claude Desktop chat, any Anthropic or OpenAI API app, VS Code, CI. macOS, Linux and Windows, Node 20+. Local, keyless, no telemetry, MIT.
@@ -21,7 +22,7 @@ Built and maintained by [gAI Ventures](https://gai.ventures).
 npx context-doctor savings
 ```
 
-<img src="https://raw.githubusercontent.com/KushalP1/context-doctor/main/assets/savings.svg" alt="npx context-doctor savings: input billed, what /compact at cold resumes and autopilot would have saved" width="640">
+<img src="https://raw.githubusercontent.com/KushalP1/context-doctor/main/assets/savings.svg" alt="npx context-doctor savings: input billed, what /compact at cold resumes, autopilot and an earlier auto-compact window would have saved" width="640">
 
 That is the author's machine: every session there runs in the desktop app, so the first line is the one that applies. Yours is computed the same way, from your own transcripts: every session replayed request by request through the shipped code, against what you were actually billed. `context-doctor savings --share` prints a few lines with totals only (no project names or paths) if you want to post your number.
 
@@ -40,7 +41,7 @@ context-doctor autopilot on     # every new Claude Code session keeps its contex
 /plugin install context-doctor@context-doctor
 ```
 
-The plugin brings the every-prompt check, the MCP tools, and `/context-doctor:savings`, `/context-doctor:checkup` and `/context-doctor:autopilot`. It needs no npm step: the MCP server ships as one self-contained file, so it also works on Claude Code versions that do not install plugin dependencies.
+The plugin brings the every-prompt check, the MCP tools, and `/context-doctor:savings`, `/context-doctor:checkup`, `/context-doctor:autopilot` and `/context-doctor:compact-window`. It needs no npm step: the MCP server ships as one self-contained file, so it also works on Claude Code versions that do not install plugin dependencies.
 
 `context-doctor autopilot status` shows what autopilot did; `context-doctor doctor` checks the whole setup. Everything is reversible: `context-doctor autopilot off`, `context-doctor uninstall`, or `/plugin uninstall`.
 
@@ -84,15 +85,27 @@ Each return counts only the messages up to the next return, and the compaction r
 
 The median session saves 1.9%, the best 37.7%: long sessions are where the money is (94% of input cost on that machine came from requests above 200k tokens). These sessions ran in the desktop app, which autopilot cannot reach, so for the author this is what the same sessions would have saved in a terminal; `context-doctor savings` separates the two for you.
 
+**3. Compacting earlier** <a id="3-compacting-earlier-automatic"></a>(automatic, every Claude Code surface, desktop app included). The offer in 1 is advice, and on the author's machine it was followed 1 time in 33. Claude Code has a native setting that needs nobody to follow anything: `autoCompactWindow` in `~/.claude/settings.json` makes it compact as if the window were that size. `context-doctor compact-window` replays each session request by request at several sizes, priced as the cache bills (each simulated compaction pays its own request and a 20k-token summary at the output rate), and changes nothing until you pick one:
+
+| Window | Input cost, last 30 days | Saved | Compactions a week |
+|---|---|---|---|
+| as now (~970k) | $6,119 | | 5.1 |
+| 600k | $3,570 | $2,549 (42%) | 6.5 |
+| **400k** | **$2,757** | **$3,362 (55%)** | **14.7** |
+| 300k | $2,353 | $3,766 (62%) | 24.5 |
+| 200k | $1,963 | $4,155 (68%) | 46.9 |
+
+29 sessions. The replay's baseline came within 9% of what the transcripts say was billed, on the low side. The cost is real: each compaction replaces the session's history with a summary, so a smaller window trades detail for money. That is why the command shows the table first and sets a window only when you name one (`context-doctor compact-window 400k`; `off` undoes it, and a backup of settings.json is kept).
+
 On a Claude subscription you do not pay list price; the same tokens come out of your usage limit instead. Anthropic does not publish how limits weight cached tokens, so read the dollars as the size of the effect, not as your bill.
 
 ## What happens on each platform
 
 | Where you work | Automatic, every request | What you get on top |
 |---|---|---|
-| **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 |
-| **Claude Code** in the desktop app's Code tab | **Hook**, as above, including the cold-resume `/compact` offer. Not autopilot: the app sets its own API address and ignores the one in settings | Same install options | 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)) |
+| **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) | 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 |
@@ -103,6 +116,8 @@ 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`.
 - **0.22 Honest about where each lever works, and a new one that works everywhere**: the every-prompt hook now offers `/compact` when you return to a large session after the cache expired (measured: ~$914 a month on the author's history), including in the desktop app. Found and fixed: autopilot cannot reach the desktop app's Code tab, and `doctor` now says so instead of reporting ✓; `savings` counted whole-file history as "last 30 days"; the hook quoted per-message cost at the uncached rate (10x too high). `--version` added.
@@ -129,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.
 
@@ -170,7 +186,8 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | Command | What it does |
 |---|---|
 | `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor/Codex, the Agent Skill, the every-prompt hook |
-| `context-doctor savings [--days n] [--share [--copy]]` | What your recent Claude Code sessions cost, and what `/compact` at cold resumes and autopilot would save, replayed through the shipped code against your actual billed usage. `--share` prints totals only (no project names or paths) to post. A bare `context-doctor` in a terminal shows the same |
+| `context-doctor savings [--days n] [--share [--copy]]` | What your recent Claude Code sessions cost, and what `/compact` at cold resumes, autopilot and an earlier auto-compact window would save, replayed through the shipped code against your actual billed usage. `--share` prints totals only (no project names or paths) to post. A bare `context-doctor` in a terminal shows the same |
+| `context-doctor compact-window [status\|off\|<size>]` | Replay your last 30 days at auto-compact windows from 200k to 800k: input cost, saving, and how many more compactions each means. `400k` (or `250000`, `0.4m`) sets Claude Code's `autoCompactWindow`, with a backup; `off` removes it. Works in every Claude Code surface, the desktop app included |
 | `context-doctor mcp [--http]` | The MCP server as a subcommand, for clients and registries that launch `npx -y context-doctor mcp` |
 | `context-doctor autopilot on\|off\|pause\|resume\|status` | Every new Claude Code session goes through the local proxy, which clears stale tool output only when the prompt cache is cold: measured 9.8% less input cost, no session worse |
 | `context-doctor instructions [--copy]` | The ~180-token standing rules (~120 on GPT) for claude.ai / ChatGPT preferences, for web and phones where no server runs |
@@ -182,7 +199,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor diff <before> <after>` | Compare two profiles: what moved by category, which findings were resolved or introduced, and what it saves in money and latency |
 | `context-doctor accuracy` | How much of what you are billed for is visible in your transcript (the fixed harness baseline, per-turn injected content), plus a tokenizer check: real chars/token per model from the API's own counts, next to the ratio the estimator uses |
 | `context-doctor cursor [--list]` | Profile a chat from Cursor's local history (both storage formats) |
-| `context-doctor report` | Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, recoverable waste in recent sessions |
+| `context-doctor report` | Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, how often the cold-resume `/compact` offer was followed by a compaction, recoverable waste in recent sessions |
 | `context-doctor proxy` | Always-on local proxy that optimizes every Anthropic/OpenAI API request in flight (`/stats` for cumulative savings) |
 | `context-doctor watch [file]` | Live monitor of a growing session transcript or agent trace (Claude Code / Codex JSONL, or a plain OpenAI/Anthropic conversation JSON file): token/cost line per change, findings as they appear |
 | `context-doctor doctor` | Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes |
@@ -241,7 +258,7 @@ context-doctor autopilot pause     # instant passthrough, nothing restarts
 context-doctor autopilot off       # remove it
 ```
 
-`autopilot on` runs the local proxy as a background service (launchd on macOS, a systemd user service on Linux, a logon task on Windows), waits until it answers, and only then points Claude Code at it through `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`. Every Claude Code session started afterwards in a terminal or an IDE sends its requests through it. **Not the desktop app's Code tab:** it runs Claude Code "host-orchestrated", sets `ANTHROPIC_BASE_URL` from its own account configuration, and drops the same key from settings files (checked in Claude Code 2.1.284). `autopilot on`, `autopilot status` and `doctor` look at which surface your recent sessions ran in and warn when autopilot cannot reach them; for desktop sessions the cold-resume advice is the lever that works. Your login (subscription or API key) passes through untouched.
+`autopilot on` runs the local proxy as a background service (launchd on macOS, a systemd user service on Linux, a logon task on Windows), waits until it answers, and only then points Claude Code at it through `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`. Every Claude Code session started afterwards in a terminal or an IDE sends its requests through it. **Not the desktop app's Code tab:** it runs Claude Code "host-orchestrated", sets `ANTHROPIC_BASE_URL` from its own account configuration, and drops the same key from settings files (checked in Claude Code 2.1.284). `autopilot on`, `autopilot status` and `doctor` look at which surface your recent sessions ran in and warn when autopilot cannot reach them; for desktop sessions the levers that work are the cold-resume advice and `compact-window`. Your login (subscription or API key) passes through untouched.
 
 **What it does to each request:** once old tool output adds up to 20k+ tokens (file reads, shell output, search and web results, screenshots inside them), it replaces that output with a one-line note, keeping the 3 most recent results. The tool call stays in the history, so the model can simply run it again if it needs the output. Your messages, its answers, answers you gave to its questions, subagent reports and MCP results are never touched.
 
@@ -314,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:**
 
@@ -330,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 |
 
@@ -354,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.
 
@@ -364,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
 
@@ -439,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
 
@@ -648,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/autopilot.js

@@ -253,7 +253,8 @@ export function reachNote(days = 30) {
         `! ${desktop} of your ${desktop + other} Claude Code sessions in the last ${days} days (with a recorded surface) ran in the desktop app. The desktop app`,
         "  sets its own API address and ignores the one in settings.json, so autopilot cannot reach those sessions.",
         "  It applies to Claude Code in a terminal (`claude`) and in IDEs. For desktop sessions, the every-prompt",
-        "  hook points out when /compact would pay off (see `context-doctor savings`).",
+        "  hook points out when /compact would pay off, and `context-doctor compact-window` makes Claude Code",
+        "  compact earlier by itself, which the desktop app honours (see `context-doctor savings`).",
     ];
     if (other === 0)
         lines.push("  Every recent session of yours is a desktop one: autopilot will not change anything until you use the terminal or an IDE.");

package/dist/cli.js

@@ -23,6 +23,7 @@ import { buildImpactReport } from "./impact.js";
 import { measureTokenizer, renderTokenizer } from "./tokenizer-measure.js";
 import { autopilotOff, autopilotOn, autopilotPause, autopilotPaths, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
 import { estimateSavings, renderSavings, renderShare } from "./savings.js";
+import { currentCompactWindow, estimateCompactWindows, MAX_WINDOW, MIN_WINDOW, parseWindow, renderCompactWindows, setCompactWindow } from "./compactwindow.js";
 import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
@@ -56,6 +57,10 @@ Usage:
                                                 /compact at cold resumes and autopilot would save,
                                                 replayed and priced as billed. --share: totals only,
                                                 to paste. Also what a bare \`context-doctor\` shows
+  context-doctor compact-window [status|off|<size>]
+                                                Claude Code's own auto-compact window (e.g. 400k):
+                                                what each size would have saved on your sessions,
+                                                and set or remove it. Works in the desktop app too
   context-doctor autopilot on|off|pause|resume|status
                                                 Every new Claude Code session goes through the
                                                 local proxy, which clears stale tool output only
@@ -521,6 +526,12 @@ async function main() {
         const report = estimateSavings(args.days ?? 30, {}, undefined, progress);
         if (progress)
             process.stderr.write("\r\x1b[K");
+        const setWindow = currentCompactWindow();
+        const cwReport = estimateCompactWindows([setWindow ?? 400_000], args.days ?? 30);
+        const est = cwReport.estimates[0];
+        const cwLine = cwReport.sessions > 0 && est
+            ? { window: est.window, savedUsd: est.savedUsd, compactionsPerWeek: (est.compactions / cwReport.days) * 7, nowPerWeek: (cwReport.actualCompactions / cwReport.days) * 7, isCurrent: setWindow !== undefined }
+            : undefined;
         const on = existsSync(autopilotPaths().config);
         if (args.json)
             console.log(JSON.stringify(report, null, 2));
@@ -531,7 +542,7 @@ async function main() {
                 console.log(copyToClipboard(text) ? "\n(copied to the clipboard)" : "\n(no clipboard tool found; copy the lines above)");
         }
         else {
-            console.log(renderSavings(report, on));
+            console.log(renderSavings(report, on, cwLine));
             if (!args.command)
                 console.log("\nAll commands: context-doctor --help");
         }
@@ -546,6 +557,34 @@ async function main() {
         await import("./mcp.js");
         return;
     }
+    if (args.command === "compact-window") {
+        const sub = args.file ?? "status";
+        if (sub === "off") {
+            setCompactWindow(undefined);
+            console.log("✓ autoCompactWindow removed from ~/.claude/settings.json: Claude Code compacts near the model's full window again (new sessions).");
+            return;
+        }
+        if (sub !== "status") {
+            const w = parseWindow(sub);
+            if (w === undefined || w < MIN_WINDOW || w > MAX_WINDOW) {
+                console.error(`Usage: context-doctor compact-window [status | off | <size>], size between 100k and 1m (e.g. 400k); got "${sub}".`);
+                process.exitCode = 1;
+                return;
+            }
+            setCompactWindow(w);
+            console.log(`✓ autoCompactWindow = ${w} in ~/.claude/settings.json (a .backup was kept).`);
+            console.log("  Claude Code sessions started from now on compact as if the window were that size,");
+            console.log("  in the terminal, IDEs and the desktop app. Check in a session with /context.");
+            console.log("  Undo: context-doctor compact-window off");
+            return;
+        }
+        const current = currentCompactWindow();
+        const windows = [200_000, 300_000, 400_000, 600_000, 800_000];
+        if (current && !windows.includes(current))
+            windows.push(current);
+        console.log(renderCompactWindows(estimateCompactWindows(windows.sort((a, b) => a - b), args.days ?? 30), current));
+        return;
+    }
     if (args.command === "autopilot") {
         const sub = args.file ?? "status";
         const port = args.port ?? DEFAULT_AUTOPILOT_PORT;

package/dist/coldresume.d.ts

@@ -41,6 +41,12 @@ export interface ColdResume {
  * Reads only the transcript's tail. Undefined when not (or when unreadable).
  */
 export declare function detectColdResume(path: string, now?: number, idleMs?: number, minTokens?: number): ColdResume | undefined;
+/**
+ * The one line shown to the USER in the app (hook `systemMessage`). In the
+ * first week the offer lived only inside the model's reply and was acted on
+ * 1 time in 33; a notice of its own is harder to miss.
+ */
+export declare function renderColdResumeNotice(c: ColdResume): string;
 /** The note the hook hands the model: the numbers, and one sentence to say. */
 export declare function renderColdResume(c: ColdResume): string;
 export interface ColdResumeEvent {
@@ -57,3 +63,16 @@ export interface ColdResumeEvent {
  * next one (no double counting), and the compaction request is a cost.
  */
 export declare function coldResumeEvents(path: string, idleMs?: number, minTokens?: number): ColdResumeEvent[];
+/**
+ * How often the cold-resume offer was acted on: offers (ledger events) whose
+ * session has a compaction within an hour after. `sessionPaths` maps the
+ * ledger's 12-char session id to its transcript. Only lines that mention a
+ * compact boundary are parsed, so even very large transcripts scan quickly.
+ */
+export declare function coldResumeFollowThrough(offers: {
+    ts: number;
+    sid?: string;
+}[], sessionPaths: Map<string, string>): {
+    offers: number;
+    compacted: number;
+};

package/dist/coldresume.js

@@ -104,6 +104,16 @@ function duration(ms) {
     const h = ms / 3_600_000;
     return h < 48 ? `${h.toFixed(h < 10 ? 1 : 0)} hours` : `${Math.round(h / 24)} days`;
 }
+/**
+ * The one line shown to the USER in the app (hook `systemMessage`). In the
+ * first week the offer lived only inside the model's reply and was acted on
+ * 1 time in 33; a notice of its own is harder to miss.
+ */
+export function renderColdResumeNotice(c) {
+    const cheaper = Math.max(0, Math.round((1 - AFTER_COMPACT_TOKENS / c.tokens) * 100));
+    const money = c.resumeUsd !== undefined ? ` (~${formatUsd(c.resumeUsd)} at list price)` : "";
+    return `context-doctor: idle ${duration(c.idleMs)}, so this message re-sent the whole ~${formatTokens(c.tokens)}-token context${money}. If you keep working here, /compact now makes each later message ~${cheaper}% cheaper.`;
+}
 /** The note the hook hands the model: the numbers, and one sentence to say. */
 export function renderColdResume(c) {
     const cheaper = Math.max(0, Math.round((1 - AFTER_COMPACT_TOKENS / c.tokens) * 100));
@@ -178,3 +188,42 @@ export function coldResumeEvents(path, idleMs = COLD_IDLE_MS, minTokens = COLD_M
     }
     return events;
 }
+/** A /compact within this long of the offer counts as acting on it. */
+const FOLLOW_MS = 60 * 60_000;
+/**
+ * How often the cold-resume offer was acted on: offers (ledger events) whose
+ * session has a compaction within an hour after. `sessionPaths` maps the
+ * ledger's 12-char session id to its transcript. Only lines that mention a
+ * compact boundary are parsed, so even very large transcripts scan quickly.
+ */
+export function coldResumeFollowThrough(offers, sessionPaths) {
+    const compactsBySid = new Map();
+    let compacted = 0;
+    for (const o of offers) {
+        const path = o.sid ? sessionPaths.get(o.sid) : undefined;
+        if (!path)
+            continue;
+        let times = compactsBySid.get(o.sid);
+        if (!times) {
+            const found = [];
+            try {
+                forEachLine(path, (line) => {
+                    if (!line.includes("compact_boundary"))
+                        return;
+                    try {
+                        const e = JSON.parse(line);
+                        const at = Date.parse(e.timestamp);
+                        if (e.subtype === "compact_boundary" && Number.isFinite(at))
+                            found.push(at);
+                    }
+                    catch { /* not a full JSON row */ }
+                });
+            }
+            catch { /* unreadable transcript: no compactions known */ }
+            compactsBySid.set(o.sid, (times = found));
+        }
+        if (times.some((t) => t >= o.ts && t - o.ts <= FOLLOW_MS))
+            compacted++;
+    }
+    return { offers: offers.length, compacted };
+}

package/dist/compactwindow.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `context-doctor compact-window`: compact earlier, automatically, in every
+ * Claude Code surface, including the desktop app.
+ *
+ * Claude Code auto-compacts near the model's window. With a 1M-token window
+ * that is ~970k (measured: 31 compactions on the author's machine, median
+ * preTokens 970,119), so long sessions spend most of their life re-reading
+ * 400k-900k tokens on every message. Claude Code has a native setting for
+ * this, `autoCompactWindow` in ~/.claude/settings.json ("Auto-compact window
+ * size"): it compacts as if the window were that size. It is a settings key,
+ * not an environment variable, so the desktop app (which filters settings env
+ * it sets itself) honours it, and no proxy or hook is involved.
+ *
+ * The trade-off is real: more compactions, each replacing history with a
+ * summary. So this measures both sides on the user's own history and changes
+ * nothing until asked. The replay uses the usage every transcript records;
+ * its baseline came within 9% of the billed figure on the author's history
+ * (on the low side, so savings are, if anything, understated).
+ */
+export declare const MIN_WINDOW = 100000;
+export declare const MAX_WINDOW = 1000000;
+export interface WindowEstimate {
+    window: number;
+    baselineUsd: number;
+    withWindowUsd: number;
+    savedUsd: number;
+    savedPct: number;
+    /** Compactions there would be over the period with this window. */
+    compactions: number;
+}
+export interface CompactWindowReport {
+    days: number;
+    sessions: number;
+    /** Compactions that actually happened over the period (Claude Code's own, or /compact). */
+    actualCompactions: number;
+    estimates: WindowEstimate[];
+}
+export declare function estimateCompactWindows(windows: number[], days?: number, paths?: string[]): CompactWindowReport;
+export declare function settingsPath(home?: string): string;
+/** The autoCompactWindow Claude Code will use from user settings, if set. */
+export declare function currentCompactWindow(home?: string): number | undefined;
+/** Set (or with undefined, remove) autoCompactWindow in ~/.claude/settings.json. A .backup is kept. */
+export declare function setCompactWindow(window: number | undefined, home?: string): void;
+/** "400k" / "400000" / "0.4m" -> 400000. Undefined when unparseable. */
+export declare function parseWindow(raw: string): number | undefined;
+export declare function renderCompactWindows(r: CompactWindowReport, current?: number): string;

package/dist/compactwindow.js

@@ -0,0 +1,222 @@
+/**
+ * `context-doctor compact-window`: compact earlier, automatically, in every
+ * Claude Code surface, including the desktop app.
+ *
+ * Claude Code auto-compacts near the model's window. With a 1M-token window
+ * that is ~970k (measured: 31 compactions on the author's machine, median
+ * preTokens 970,119), so long sessions spend most of their life re-reading
+ * 400k-900k tokens on every message. Claude Code has a native setting for
+ * this, `autoCompactWindow` in ~/.claude/settings.json ("Auto-compact window
+ * size"): it compacts as if the window were that size. It is a settings key,
+ * not an environment variable, so the desktop app (which filters settings env
+ * it sets itself) honours it, and no proxy or hook is involved.
+ *
+ * The trade-off is real: more compactions, each replacing history with a
+ * summary. So this measures both sides on the user's own history and changes
+ * nothing until asked. The replay uses the usage every transcript records;
+ * its baseline came within 9% of the billed figure on the author's history
+ * (on the low side, so savings are, if anything, understated).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { forEachLine, listSessions } from "./session.js";
+import { pricingFor } from "./pricing.js";
+import { readJson, writeJsonWithBackup } from "./install.js";
+/** Claude Code compacts at about this share of the window (970k of 1M, measured). */
+const TRIGGER_SHARE = 0.97;
+/** Context right after a compaction: system prompt, tools and the summary (median 75,447, measured). */
+const AFTER_COMPACT = 75_000;
+/** Output tokens a compaction summary costs, priced at output's 5x input rate. */
+const SUMMARY_OUTPUT = 20_000;
+const OUTPUT_RATIO = 5;
+const TTL_MS = 3_600_000;
+export const MIN_WINDOW = 100_000;
+export const MAX_WINDOW = 1_000_000;
+function readRequests(path) {
+    const reqs = [];
+    let lastId, model;
+    forEachLine(path, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (e.type === "system" && e.subtype === "compact_boundary") {
+            reqs.push("compact");
+            return;
+        }
+        if (e.type !== "assistant" || !e.message || e.message.id === lastId)
+            return;
+        lastId = e.message.id;
+        const u = e.message.usage ?? {};
+        const prompt = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+        const at = Date.parse(e.timestamp);
+        if (prompt > 0 && Number.isFinite(at)) {
+            reqs.push({ at, prompt });
+            model ??= e.message.model;
+        }
+    });
+    return { model, reqs };
+}
+/**
+ * Replay one session twice: as it ran, and with compaction whenever the
+ * context reaches the window's trigger. Both arms are priced as the prompt
+ * cache bills (warm: 0.1x re-read + 1.25x for what is new; cold after an hour
+ * idle: 1.25x for everything); each simulated compaction also pays its own
+ * request and summary.
+ */
+function replay(reqs, window, since) {
+    let base = 0, sim = 0, extra = 0, actual = 0;
+    let removed = 0, prevActual, prevSim, prevAt;
+    for (const r of reqs) {
+        if (r === "compact") {
+            if (prevAt !== undefined && prevAt >= since)
+                actual++;
+            // A real compaction in the transcript: the simulated arm compacts there too.
+            if (prevAt !== undefined && prevAt >= since && removed === 0)
+                extra++;
+            removed = 0;
+            prevActual = prevSim = undefined;
+            continue;
+        }
+        const counted = r.at >= since;
+        const cold = prevAt === undefined || r.at - prevAt > TTL_MS;
+        const cost = (ctx, prev) => {
+            if (cold)
+                return 1.25 * ctx;
+            const fresh = prev === undefined || ctx < prev ? ctx : ctx - prev;
+            return 0.1 * (ctx - fresh) + 1.25 * fresh;
+        };
+        if (counted)
+            base += cost(r.prompt, prevActual);
+        let ctx = r.prompt - removed;
+        // The real context fell below what we had removed (a rewind with no
+        // compaction marker): the two arms are back in step.
+        if (ctx < AFTER_COMPACT && removed > 0) {
+            removed = 0;
+            ctx = r.prompt;
+        }
+        let simPrev = prevSim;
+        if (ctx >= TRIGGER_SHARE * window) {
+            if (counted) {
+                sim += 0.1 * ctx + OUTPUT_RATIO * SUMMARY_OUTPUT;
+                extra++;
+            }
+            removed = r.prompt - AFTER_COMPACT;
+            ctx = AFTER_COMPACT;
+            simPrev = undefined; // everything after a compaction is new to the cache
+        }
+        if (counted)
+            sim += cost(ctx, simPrev);
+        prevActual = r.prompt;
+        prevSim = ctx;
+        prevAt = r.at;
+    }
+    return { base, sim, extra, actual };
+}
+export function estimateCompactWindows(windows, days = 30, paths) {
+    const since = Date.now() - days * 86_400_000;
+    const targets = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
+    const acc = windows.map((w) => ({ window: w, base: 0, sim: 0, extra: 0 }));
+    let sessions = 0, actualCompactions = 0;
+    for (const p of targets) {
+        let parsed;
+        try {
+            parsed = readRequests(p);
+        }
+        catch {
+            continue;
+        }
+        const perM = pricingFor(parsed.model)?.inputPerM;
+        if (!perM || parsed.reqs.filter((r) => r !== "compact" && r.at >= since).length < 10)
+            continue;
+        sessions++;
+        actualCompactions += replay(parsed.reqs, Number.MAX_SAFE_INTEGER, since).actual;
+        for (const a of acc) {
+            const r = replay(parsed.reqs, a.window, since);
+            a.base += (r.base * perM) / 1e6;
+            a.sim += (r.sim * perM) / 1e6;
+            a.extra += r.extra;
+        }
+    }
+    return {
+        days,
+        sessions,
+        actualCompactions,
+        estimates: acc.map((a) => ({
+            window: a.window,
+            baselineUsd: a.base,
+            withWindowUsd: a.sim,
+            savedUsd: a.base - a.sim,
+            savedPct: a.base > 0 ? (a.base - a.sim) / a.base : 0,
+            compactions: a.extra,
+        })),
+    };
+}
+export function settingsPath(home = homedir()) {
+    return join(home, ".claude", "settings.json");
+}
+/** The autoCompactWindow Claude Code will use from user settings, if set. */
+export function currentCompactWindow(home = homedir()) {
+    const p = settingsPath(home);
+    if (!existsSync(p))
+        return undefined;
+    try {
+        const v = JSON.parse(readFileSync(p, "utf8"))?.autoCompactWindow;
+        return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Set (or with undefined, remove) autoCompactWindow in ~/.claude/settings.json. A .backup is kept. */
+export function setCompactWindow(window, home = homedir()) {
+    if (window !== undefined && (!Number.isInteger(window) || window < MIN_WINDOW || window > MAX_WINDOW)) {
+        throw new Error(`window must be a whole number of tokens between ${MIN_WINDOW} and ${MAX_WINDOW}`);
+    }
+    const p = settingsPath(home);
+    const settings = readJson(p);
+    if (window === undefined)
+        delete settings.autoCompactWindow;
+    else
+        settings.autoCompactWindow = window;
+    writeJsonWithBackup(p, settings);
+}
+/** "400k" / "400000" / "0.4m" -> 400000. Undefined when unparseable. */
+export function parseWindow(raw) {
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([km]?)\s*$/i.exec(raw);
+    if (!m)
+        return undefined;
+    const n = Number(m[1]) * (m[2].toLowerCase() === "m" ? 1e6 : m[2].toLowerCase() === "k" ? 1e3 : 1);
+    return Math.round(n);
+}
+const usd = (n) => (Math.abs(n) >= 100 ? `$${Math.round(n).toLocaleString("en-US")}` : `$${n.toFixed(2)}`);
+const k = (n) => `${Math.round(n / 1000)}k`;
+export function renderCompactWindows(r, current) {
+    const lines = [];
+    lines.push("Auto-compact window: compact earlier, automatically (Claude Code's own setting)");
+    lines.push(`Your last ${r.days} days, ${r.sessions} Claude Code session${r.sessions === 1 ? "" : "s"}, priced at list prices`);
+    lines.push("─".repeat(66));
+    lines.push(`Now: ${current ? `${k(current)} (set in ~/.claude/settings.json)` : "not set: Claude Code compacts near the model's full window"}`);
+    if (r.sessions === 0) {
+        lines.push("No sessions with 10+ requests in the window to replay.");
+        return lines.join("\n");
+    }
+    lines.push("");
+    lines.push("  window   input cost   saved            compactions");
+    for (const e of r.estimates) {
+        const mark = current === e.window ? "  ← current" : "";
+        lines.push(`  ${k(e.window).padStart(6)}   ${usd(e.withWindowUsd).padStart(10)}   ${(usd(e.savedUsd) + ` (${Math.round(e.savedPct * 100)}%)`).padEnd(16)} ${String(e.compactions).padStart(4)} (${((e.compactions / r.days) * 7).toFixed(1)}/week)${mark}`);
+    }
+    lines.push(`  as now   ${usd(r.estimates[0]?.baselineUsd ?? 0).padStart(10)}                    ${String(r.actualCompactions).padStart(4)} (${((r.actualCompactions / r.days) * 7).toFixed(1)}/week)`);
+    lines.push("");
+    lines.push("Each compaction replaces the session's history with a summary, so a smaller");
+    lines.push("window trades detail for cost. Set one with:  context-doctor compact-window 400k");
+    lines.push("Undo with:  context-doctor compact-window off");
+    return lines.join("\n");
+}

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 {
@@ -237,7 +255,7 @@ export async function runDoctor() {
             const known = [...surfaces.keys()].filter((ep) => ep !== "unknown");
             const desktopOnly = known.length > 0 && known.every((ep) => ep.startsWith("claude-desktop"));
             checks.push(h.ok && h.autopilot && routed && seen === 0 && desktopOnly
-                ? { label: "Autopilot", status: "warn", detail: "running, but it has seen 0 requests: your recent Claude Code sessions all ran in the desktop app, which ignores settings.json's API address. Autopilot only reaches terminal and IDE sessions" }
+                ? { label: "Autopilot", status: "warn", detail: "running, but it has seen 0 requests: your recent Claude Code sessions all ran in the desktop app, which ignores settings.json's API address. Autopilot only reaches terminal and IDE sessions; for desktop ones, see `context-doctor compact-window`" }
                 : h.ok && h.autopilot && routed
                     ? { label: "Autopilot", status: "ok", detail: `proxy up on ${proxyUrl(cfg.port)}, Claude Code routed through it${seen >= 0 ? ` (${seen} requests since start)` : ""}${paused ? " (PAUSED: passthrough)" : ""}` }
                     : { label: "Autopilot", status: "fail", detail: !h.ok ? `proxy not answering on ${proxyUrl(cfg.port)}: the next Claude Code prompt restarts it; or run: context-doctor autopilot on` : "settings.json no longer routes Claude Code to the proxy: run context-doctor autopilot on" });

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,9 +19,9 @@ 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 } from "./coldresume.js";
+import { detectColdResume, renderColdResume, renderColdResumeNotice } from "./coldresume.js";
 import { formatUsd, pricingFor } from "./pricing.js";
 import { checkBudget, loadConfig } from "./config.js";
 /** Default nudge threshold; a project budget or env var can lower/raise it. */
@@ -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,23 +170,38 @@ 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.
         // Once per idle period; the tail read is ~1 ms and only on large files.
         const notes = [];
+        let notice;
         const cold = detectColdResume(transcriptPath);
         let cr = prev.cr;
         if (cold && cold.lastReplyAt !== prev.cr) {
             notes.push(renderColdResume(cold));
+            notice = renderColdResumeNotice(cold);
             cr = cold.lastReplyAt;
             recordLedger({ ev: "cold_resume", sid: sessionId.slice(0, 12), tok: cold.tokens, model: cold.model });
         }
         const emit = (lines) => {
-            if (lines.length === 0)
+            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;
-            console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: `<context-doctor>\n${lines.join("\n")}\n</context-doctor>` } }));
+            }
+            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: block };
+            console.log(JSON.stringify(out));
         };
         if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR) {
             if (cr !== prev.cr)
@@ -187,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.
@@ -200,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` : "") +
@@ -225,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/impact.js

@@ -14,6 +14,7 @@ import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
+import { coldResumeFollowThrough } from "./coldresume.js";
 /** Sessions larger than this are skipped in the report (keeps it snappy). */
 const MAX_SESSION_BYTES = 30 * 1024 * 1024;
 async function fetchProxyStats(port) {
@@ -117,6 +118,18 @@ export async function buildImpactReport(proxyPort = 8787) {
     else {
         lines.push("No hook activity recorded yet (ledger appears after the first deep check of a heavy session).");
     }
+    const offers = ledger.filter((e) => e.ev === "cold_resume");
+    if (offers.length > 0) {
+        const paths = new Map();
+        for (const s of listSessions(10_000))
+            paths.set((s.path.split(/[\\/]/).pop() ?? "").slice(0, 12), s.path);
+        const f = coldResumeFollowThrough(offers, paths);
+        lines.push(`/compact offered on ${f.offers} return(s) to a large session after the cache expired;`);
+        lines.push(`a compaction (yours or Claude Code's) followed within the hour on ${f.compacted}.`);
+        if (f.offers >= 5 && f.compacted / f.offers < 0.2) {
+            lines.push("Rarely acted on? `context-doctor compact-window` makes Claude Code compact earlier by itself.");
+        }
+    }
     lines.push("");
     // -- Measured-now: recent session profiles ------------------------------------
     lines.push("Your recent sessions — live context and waste still recoverable");
@@ -144,7 +157,7 @@ export async function buildImpactReport(proxyPort = 8787) {
                     totalWasteUsd += p.cost.savingsPerCallUsd * (pr.cacheReadPerM / pr.inputPerM);
                 const wastePct = p.totalTokens > 0 ? Math.round((p.totalEstSavings / p.totalTokens) * 100) : 0;
                 // Ledger sids are the session UUID's first 12 chars (= filename prefix).
-                const sid = (s.path.split("/").pop() ?? "").slice(0, 12);
+                const sid = (s.path.split(/[\\/]/).pop() ?? "").slice(0, 12);
                 const saved = reductionBySession.get(sid) ?? 0;
                 const warns = bySession.get(sid)?.warns ?? 0;
                 lines.push(`  ${(parsed.title ?? s.path.split("/").pop() ?? "session").slice(0, 40).padEnd(42)} ` +

package/dist/index.d.ts

@@ -25,3 +25,4 @@ export * from "./autoclear.js";
 export * from "./autopilot.js";
 export * from "./savings.js";
 export * from "./coldresume.js";
+export * from "./compactwindow.js";

package/dist/index.js

@@ -20,3 +20,4 @@ export * from "./autoclear.js";
 export * from "./autopilot.js";
 export * from "./savings.js";
 export * from "./coldresume.js";
+export * from "./compactwindow.js";

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.24.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.24.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.24.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/savings.d.ts

@@ -58,7 +58,15 @@ export interface SavingsReport {
 /** Replay one Claude Code transcript. Undefined when it holds too few requests to mean anything. */
 export declare function replaySession(path: string, options?: AutoClearOptions, since?: number): SessionSavings | undefined;
 export declare function estimateSavings(days?: number, options?: AutoClearOptions, paths?: string[], onProgress?: (done: number, total: number) => void): SavingsReport;
-export declare function renderSavings(r: SavingsReport, autopilotOn?: boolean): string;
+/** Optional third lever, computed by compactwindow.ts and passed in by the CLI. */
+export interface CompactWindowLine {
+    window: number;
+    savedUsd: number;
+    compactionsPerWeek: number;
+    nowPerWeek: number;
+    isCurrent: boolean;
+}
+export declare function renderSavings(r: SavingsReport, autopilotOn?: boolean, cw?: CompactWindowLine): string;
 /**
  * `savings --share`: a few lines people can paste or screenshot. Totals only:
  * no project names, paths or session ids, so sharing it leaks nothing.

package/dist/savings.js

@@ -199,7 +199,7 @@ export function estimateSavings(days = 30, options = {}, paths, onProgress) {
 }
 const tokens = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(1)}B` : formatTokens(n));
 const usd = (n) => (n >= 100 ? `$${Math.round(n).toLocaleString("en-US")}` : `$${n.toFixed(2)}`);
-export function renderSavings(r, autopilotOn = false) {
+export function renderSavings(r, autopilotOn = false, cw) {
     const lines = [];
     if (r.sessions.length === 0) {
         lines.push(`No Claude Code sessions with 10+ requests in the last ${r.days} days to replay.`);
@@ -236,6 +236,15 @@ export function renderSavings(r, autopilotOn = false) {
         if (!autopilotOn)
             lines.push("   Turn it on:  context-doctor autopilot on");
     }
+    if (cw) {
+        lines.push("");
+        lines.push(`${`3. Compact earlier (${Math.round(cw.window / 1000)}k window)`.padEnd(34)}${usd(Math.max(0, cw.savedUsd)).padStart(9)}${pct(Math.max(0, cw.savedUsd))}`);
+        lines.push(`   Claude Code's own auto-compact window${cw.isCurrent ? ", as you have it set" : ""}: automatic in every surface,`);
+        lines.push(`   ${cw.compactionsPerWeek.toFixed(1)} compactions a week instead of ${cw.nowPerWeek.toFixed(1)}. Each keeps a summary, not the`);
+        lines.push("   full history. Compare sizes: context-doctor compact-window");
+        if (!cw.isCurrent)
+            lines.push(`   Set it with: context-doctor compact-window ${Math.round(cw.window / 1000)}k`);
+    }
     lines.push("");
     lines.push("Replayed request by request through the shipped code and priced as the");
     lines.push("prompt cache bills. On a subscription the same tokens come out of your");

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.24.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",