context-doctor 0.25.0 → 0.27.0

package/README.md

@@ -2,18 +2,27 @@
 
 [![CI](https://github.com/KushalP1/context-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/KushalP1/context-doctor/actions) [![npm](https://img.shields.io/npm/v/context-doctor)](https://www.npmjs.com/package/context-doctor) [![npm downloads](https://img.shields.io/npm/dm/context-doctor)](https://www.npmjs.com/package/context-doctor) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE) ![macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
 
-**Keep every AI session's context lean, and see exactly what it costs you, without ever making it more expensive.**
+**Cut your Claude Code bill, measured on your own sessions.**
+
+```bash
+npx context-doctor savings
+```
+
+One command shows, in dollars, what your recent sessions cost and what each lever below would have saved on them. Then the levers do it: an every-prompt hook, an auto-compact window, and a proxy that never makes a request more expensive.
 
 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.)
+- **Keeps waste out in the first place.** `context-doctor pack` (and the `pack_context` MCP tool) puts only the chunks of a big document, log or codebase that a question needs into the context, within a token budget: 9 of 10 questions about this repo answered from 0.6% of its tokens. `context-doctor overhead` measures what every request re-reads before your message (system prompt, tools, CLAUDE.md, rules, memory) and prices each memory file per month. [How →](#before-it-enters-the-context-pack-and-overhead)
 - **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.
+- **Works where you work:** Claude Code (terminal, IDE, desktop app, plugin), Cursor, Codex, Gemini CLI, Claude Desktop chat, any Anthropic or OpenAI API app, VS Code, CI. macOS, Linux and Windows, Node 20+. Local, keyless, no telemetry, MIT.
 
 Built and maintained by [gAI Ventures](https://gai.ventures).
 
+> **Which context-doctor is this?** Several projects share the name. This one is [`context-doctor` on npm](https://www.npmjs.com/package/context-doctor) and `io.github.KushalP1/context-doctor` in the [official MCP Registry](https://registry.modelcontextprotocol.io): the one you run as `npx context-doctor`, and the one that prices what it saves on your own history.
+
 ## Quick start
 
 **See what it would save you first** (no install, reads your local Claude Code history):
@@ -24,7 +33,7 @@ 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, 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.
+That is the author's machine: every session there runs in the desktop app, which autopilot cannot reach, so lines 1 and 3 are the ones that apply. 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.
 
 **Then install it**, whichever way suits you:
 
@@ -105,17 +114,60 @@ 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 |
+| **Gemini CLI** | Every-prompt hook (`BeforeAgent`) with the API's own token counts. On an API key, autopilot too: `GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787` (Google sign-in traffic goes elsewhere) | MCP tools, `session` and `watch` read its chats, `overhead` sizes GEMINI.md |
+| **Your own apps on the Anthropic, OpenAI or Gemini API** | Autopilot on `/v1/messages`, `/v1/chat/completions`, `/v1/responses` and Gemini's `generateContent` (`ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` / `GOOGLE_GEMINI_BASE_URL`), or the full optimizing proxy; no proxy possible (serverless, edge)? `withContextDoctor(client)` runs autopilot inside the SDK client | 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; `pack_context` instead of reading a big local file whole | One-click `.mcpb` install, `context_checkup` prompt |
 | **claude.ai, ChatGPT, the phone apps** | Your account's standing preferences (`context-doctor instructions --copy`) | Profile an exported chat with `analyze` |
 | **CI** | `analyze --fail-over-budget` fails a build whose prompts outgrow a budget | `.contextdoctorrc` budgets and presets |
 
 Not claimed, because no process on your machine sends those requests: trimming inside Claude Desktop chat, claude.ai, ChatGPT, Cursor's own subscription models, or Codex signed in with ChatGPT. Those get the rules and the measurements above, not autopilot.
 
+## Before it enters the context: pack and overhead
+
+Everything above slims context that is already there. Two commands stop it getting in.
+
+**`pack`: only the parts of a document a question needs.** A 60k-token manual pasted to answer one question is paid on that message and re-read on every message after it. `pack` splits files and folders along their own structure (markdown headings, top-level code declarations, paragraphs; one-line logs and minified files are cut too), ranks the chunks against your question with BM25, and returns the best ones that fit a budget. Every chunk carries an id and its line range, and the result names the next-best ids, so asking for more is one call. Without a question you get an outline to pick from.
+
+```bash
+context-doctor pack docs/ README.md --query "how do I rotate the signing key" --max-tokens 3000
+context-doctor pack big-manual.md                     # outline: id, lines, tokens, heading per chunk
+context-doctor pack big-manual.md --ids big-manual.md#12,big-manual.md#13
+cat server.log | context-doctor pack - -q "timeout upstream"
+```
+
+```
+$ context-doctor pack README.md src -q "how is the ledger kept from growing" --max-tokens 2000
+PACKED ~1.9k of ~315k tokens (1%) from 80 files: 7 of 1026 chunks for "how is the ledger kept from growing", budget 2.0k.
+
+── src/ledger.ts#6 · L108-128 · export function recordLedger(entry: Omit<LedgerEntry, "ts">): void { · ~404
+...
+── src/test/ledger.test.ts#1 · L1-22 · The ledger is capped, and everything it feeds is a LIFETIME total. · ~409
+...
+Not included: 1019 chunk(s). Next best: src/watch.ts#1 (...); src/test/compactwindow.test.ts#4 (...)
+```
+
+In Claude Desktop, Claude Code, Cursor and Codex the same thing is the `pack_context` MCP tool, and the standing instructions tell the model to use it when it needs to answer from a large file it is not editing. Ranking is lexical, offline and keyless; it misses pure paraphrase, which is what the outline is for. If you run [Ollama](https://ollama.com) with an embedding model (`ollama pull nomic-embed-text`), `--semantic` (or `semantic: true` on the MCP tool) also ranks by meaning and merges the two rankings; chunk vectors are cached, so repeat packs are fast. Without one it says so and stays lexical. Measured on this repository (README plus source, ~305k tokens): 9 of 10 factual questions were answered from a 2k-token pack. PDFs, Word (`.docx`, `.doc`, `.rtf`), PowerPoint and ODT files are read with tools the OS already has (`pdftotext` where installed, PDFKit and `textutil` on macOS, `unzip` elsewhere); when none is available, pack says what to install. Over HTTP (the ChatGPT connector mode) the tool reads no files, only text you pass.
+
+**`overhead`: what every request re-reads before your message.** The system prompt, tool and MCP schemas, skills and your memory files ride on every request: cached, so each read is cheap, but read on every request of every session and written again at full price after each cold start. Transcripts never show them. `overhead` measures the fixed part from the first request of each recent Claude Code session (the API's own count, minus your first message), lists every memory file each agent loads in the current directory (Claude Code's CLAUDE.md with its `@imports`, rules and auto memory; Codex's AGENTS.md; Cursor's always-applied rules; GEMINI.md), and prices each per month from your own request and cold-start counts.
+
+```
+Claude Code, last 30 days: 71 sessions start at a median ~54k tokens (p90 ~62k) before the first message.
+Memory files loaded here are ~3.4k of that; the rest is Claude Code's system prompt, tools, skills and MCP schemas.
+At your usage (14,104 requests, 249 cold starts, claude-fable-5-1 list prices) every 1k tokens of it costs ~$16.97 a month;
+```
+
+Findings point at files over 2k tokens, paragraphs loaded twice from two files, and long code blocks that could live in a file the agent opens when it needs them.
+
+To act on a finding, `context-doctor overhead split <file>` plans the fix: sections over ~400 tokens (or mostly code) move word for word to `<name>.reference.md`, each run of them leaving one pointer the agent follows when a task needs it. Lists of links are indexes and stay, and an auto-memory `MEMORY.md` keeps only its index, as Claude Code intends. Nothing is written until you add `--write`, which backs up the original first. On a copy of the author's auto-memory index: ~3.4k to ~1.7k tokens on every request, about $28 a month, nothing lost.
+
+MCP servers are part of the same overhead: each one's tool definitions ride on every request. `overhead` counts calls per server from your transcripts, including servers the app or its connectors provide, and `overhead --mcp` launches each configured server once to size its definitions, flagging the ones you never call with what they cost a month. When Claude Code's tool search is on (the report says how often it was used), definitions are deferred and an idle server costs about its tool names instead.
+
 ## What's new
 
+- **0.27 Keep waste out**: `pack` and the `pack_context` MCP tool put only the chunks of big files (text, code, PDF, Word, PowerPoint) a question needs into the context, within a budget; `overhead` measures and prices the front matter every request re-reads (system prompt, tools, CLAUDE.md, rules, memory, AGENTS.md, Cursor rules, GEMINI.md). MCP servers sized and their use counted; `overhead split` turns a heavy memory file into a lean one plus a reference file. `withContextDoctor(client)` runs autopilot inside an Anthropic or OpenAI SDK client, for apps with no proxy. Gemini joins: `install` wires Gemini CLI's MCP server and every-prompt hook, `session` and `watch` read its chats, and the proxy and autopilot carry Google's Gemini API. A GitHub Action (and `context-doctor ci`) reports memory-file growth on every pull request and gates on a budget. Re-verified on every surface: 229 tests on macOS, Linux and Windows, plus MCP, OpenAI and Gemini end-to-end smoke runs, now in CI, MCP over stdio and HTTP, the OpenAI proxy, and a live `doctor`.
+- **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 +195,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.
 
@@ -189,6 +242,10 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `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 |
+| `context-doctor pack <files\|dirs\|-> --query "…"` | Only the chunks of big documents, logs or code a question needs, ranked and fit to `--max-tokens` (default 4000). No query: an outline; `--ids a#2,b#5` picks chunks from it. Offline, no key |
+| `context-doctor overhead [--days n] [--mcp]` | What every request re-reads before your message: measured first-request size, each memory file (CLAUDE.md and imports, rules, auto memory, AGENTS.md, Cursor rules, GEMINI.md) priced per month, MCP calls per server; `--mcp` sizes each configured server's tool definitions and flags unused ones |
+| `context-doctor overhead split <file> [--write]` | Move a memory file's big or code-heavy sections word for word to `<name>.reference.md`, leaving pointers; indexes stay. A plan until `--write`, which backs up first |
+| `context-doctor ci [--base <ref>] [--max-tokens n] [--max-increase n]` | Memory files (CLAUDE.md, AGENTS.md, GEMINI.md, rules, their imports) at HEAD vs a base commit; exit 1 over budget. What the GitHub Action runs |
 | `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates. `--fail-over-budget` exits 1 on a breach, for CI |
 | `context-doctor optimize <file>` | Apply the safe fixes; add `--strategy trim-tool-calls` for big inline file writes, `--strategy prune-history` for consented lossy compaction |
 | `context-doctor session [file]` | Profile a Claude Code session: live context, findings, **measured tokens and prompt-cache economics**, **where the wall clock went** per tool, and **what its subagents cost** (their own windows, your bill; never in the parent's profile). Also reads ChatGPT data exports (`conversations.json`) |
@@ -329,15 +386,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 +402,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 +426,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 +436,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
 
@@ -393,6 +450,7 @@ Your local MCP server can't reach the website, but the behavior can. Two options
 |---|---|
 | `profile_context` | Token breakdown by category, largest messages, findings with estimated savings. Takes either `conversation` (full JSON or text) or `sketch` (turns + large/repeated blocks, for chat apps) |
 | `optimize_context` | Rewrites the conversation: dedupe, trim stale tool results, strip base64, optional history pruning |
+| `pack_context` | Only the chunks of large local files or folders (or passed `text`) that a question needs, within `max_tokens`; outline without a query; `ids` to fetch more. Reads no files over HTTP |
 | `context_best_practices` | Curated checklist, optionally specialized for Anthropic / OpenAI |
 
 ## Use it as a library
@@ -406,8 +464,24 @@ console.log(profile.totalTokens, profile.findings);
 const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJson, {
   strategies: ["dedupe", "trim-tool-results", "strip-base64"],
 });
+
+// Autopilot without a proxy: wrap the SDK client (Anthropic or OpenAI)
+import Anthropic from "@anthropic-ai/sdk";
+import { withContextDoctor, contextDoctorStats } from "context-doctor";
+const client = withContextDoctor(new Anthropic());       // use exactly as before
+await client.messages.create({ model, max_tokens, messages });
+console.log(contextDoctorStats(client));                 // { requests, changed, tokensRemoved }
+
+// RAG-style context packing: chunk, rank, fit a budget (no embeddings, no key)
+import { packContext, renderPack } from "context-doctor";
+const packed = packContext([{ name: "manual.md", text: manual }], { query: "rotate the signing key", budget: 3000 });
+console.log(packed.selected.map((c) => `${c.id} L${c.startLine}-${c.endLine}`), renderPack(packed));
 ```
 
+### Autopilot inside your app: `withContextDoctor`
+
+For apps that cannot send traffic through a local proxy (serverless and edge functions, managed hosts), wrap the SDK client. `messages.create` / `stream`, `chat.completions.create` / `stream` / `parse` and `responses.create` / `stream` / `parse` (beta namespaces too) go through the same autopilot as the proxy: stale tool output is cleared only when the prompt cache is cold. Each request is cloned before it changes, so the history your app holds is never rewritten; only the copy on the wire is slimmer. State lives in the process: one long-lived process per conversation stream behaves like the proxy, and a conversation the process has not seen counts as warm, so a fresh serverless instance never clears blind (pass `statePath` on shared storage if many instances serve the same conversations). Tested with the real `@anthropic-ai/sdk` and `openai` packages.
+
 ## Subagents: their own windows, your bill
 
 A subagent has its own context window, so its tokens are correctly absent from the parent's profile. They are not absent from the bill. Claude Code writes each one to `<session>/subagents/agent-<id>.jsonl`, and `session` now reads them:
@@ -454,7 +528,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
 
@@ -571,6 +645,29 @@ A cache read bills at ~10% of input while a write bills at ~125%, so a session t
 
 ## Enforce a budget in CI
 
+**Memory files on every pull request.** CLAUDE.md, AGENTS.md, GEMINI.md and rules are re-read by every request of everyone working in the repository, so their growth deserves review. The repository is also a GitHub Action:
+
+```yaml
+# .github/workflows/context.yml
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write   # for the comment
+jobs:
+  memory:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KushalP1/context-doctor@v0.27.0
+        with:
+          max-increase: "2000"        # fail a PR that adds more than 2k tokens
+          requests-per-day: "5000"    # optional: price the change
+```
+
+It compares the memory files and their `@imports` at the PR head with the base branch, writes the table to the job summary, keeps one PR comment up to date, and fails over budget. Locally: `context-doctor ci --base origin/main`.
+
+**Conversation fixtures.**
+
 ```bash
 npx context-doctor analyze conversation.json --fail-over-budget
 ```
@@ -626,7 +723,7 @@ One honest caveat worth knowing: a transcript stores the conversation, **not** t
 
 ## Roadmap
 
-See [ROADMAP.md](./ROADMAP.md) for the full plan with rationale. Headlines: **v0.5** trust & automation (tag-based publishing, `doctor` self-check, live `watch`), **v0.6** accuracy (exact tokenizers, semantic dedupe, more session formats), **v0.7** proxy pro (response accounting, prompt-cache advisor), **v1.0** budgets + local dashboard. Non-goals, permanently: cloud services, telemetry, silent history rewriting, mandatory API keys.
+See [ROADMAP.md](./ROADMAP.md) for the full plan, the per-surface coverage table and the measurements behind every shipped item. Next, in order of expected saving: the MCP schema tax per server in `overhead`; a Python package for RAG pipelines. Non-goals, permanently: cloud services, telemetry, silent history rewriting, mandatory API keys.
 
 Contributions welcome — this project is small on purpose. Open an issue before a big PR.
 
@@ -663,6 +760,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.d.ts

@@ -53,6 +53,13 @@ export interface AutoClearOptions {
     paybackSafety?: number;
     /** Where cleared ids persist so a restart does not un-clear (and re-bill) them. */
     statePath?: string;
+    /**
+     * Treat a conversation this instance has never seen as warm-cached (so
+     * nothing is cleared on it). The proxy sees every request and leaves this
+     * off; an in-process wrapper in a fresh process cannot know whether another
+     * process just sent the conversation, so it turns this on.
+     */
+    unseenIsWarm?: boolean;
 }
 export interface AutoClearResult {
     changed: boolean;
@@ -81,7 +88,7 @@ interface Found {
  * as Codex with an API key sends).
  */
 interface View {
-    format: "anthropic" | "openai-chat" | "openai-responses";
+    format: "anthropic" | "openai-chat" | "openai-responses" | "gemini";
     units: Array<Record<string, unknown>>;
     toolName: Map<string, string>;
     results: Array<Omit<Found, "tokens">>;
@@ -112,7 +119,7 @@ export declare class AutoClearer {
      * Rewrite `body` in place: an Anthropic Messages, OpenAI Chat Completions or
      * OpenAI Responses request. Never throws; anything unrecognised is left alone.
      */
-    apply(body: Record<string, unknown>, now?: number): AutoClearResult;
+    apply(body: Record<string, unknown>, now?: number, modelHint?: string): AutoClearResult;
     /**
      * Warm cache: clearing rewrites everything after the first cleared result
      * at the write rate (1.25x instead of 0.1x: 1.15x extra, once), and saves

package/dist/autoclear.js

@@ -45,10 +45,13 @@ 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",
+    // Gemini CLI
+    "read_many_files", "run_shell_command", "glob", "search_file_content", "list_directory", "web_fetch", "google_web_search",
     // 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;
@@ -83,6 +86,9 @@ function resultTokens(content, model) {
  *    the request sets prompt_cache_retention "24h".
  */
 export function requestTtlMs(body) {
+    // Gemini: implicit caching's lifetime is not published, explicit caches default to an hour.
+    if (Array.isArray(body.contents))
+        return HOUR;
     const openai = Array.isArray(body.input) || (Array.isArray(body.messages) && isOpenAIChat(body.messages));
     if (openai)
         return body.prompt_cache_retention === "24h" ? 24 * HOUR : HOUR;
@@ -96,6 +102,37 @@ export function viewOf(body) {
     const toolName = new Map();
     const results = [];
     let firstToolId = "";
+    // Gemini generateContent: contents[].parts[] with functionCall / functionResponse.
+    // Ids are optional there, so a missing one is derived from its position
+    // (stable: history only grows) and scoped to the conversation, because the
+    // cleared set is keyed by id and positions repeat across conversations.
+    if (Array.isArray(body.contents)) {
+        const units = body.contents;
+        const firstUser = units.find((u) => u?.role === "user")?.parts;
+        const scope = createHash("sha1").update(JSON.stringify(firstUser ?? "").slice(0, 4000)).digest("hex").slice(0, 10);
+        units.forEach((u, i) => {
+            if (!Array.isArray(u?.parts))
+                return;
+            const parts = u.parts;
+            parts.forEach((p, j) => {
+                const call = p?.functionCall;
+                const resp = p?.functionResponse;
+                if (call && typeof call === "object") {
+                    const id = typeof call.id === "string" && call.id ? call.id : `gemini:${scope}:${i}:${j}`;
+                    toolName.set(id, String(call.name ?? ""));
+                    firstToolId ||= id;
+                }
+                else if (resp && typeof resp === "object") {
+                    const id = typeof resp.id === "string" && resp.id ? resp.id : `gemini:${scope}:${i}:${j}`;
+                    // The response names its tool, so it classifies on its own.
+                    if (!toolName.has(id))
+                        toolName.set(id, String(resp.name ?? ""));
+                    results.push({ unit: i, id, content: resp.response, set: (note) => { parts[j] = { ...p, functionResponse: { ...resp, response: { output: note } } }; } });
+                }
+            });
+        });
+        return { format: "gemini", units, toolName, results, firstUser, firstToolId, ttlMs: requestTtlMs(body) };
+    }
     if (Array.isArray(body.input)) {
         const units = body.input;
         units.forEach((it, i) => {
@@ -170,6 +207,7 @@ export class AutoClearer {
             keepRecent: options.keepRecent ?? 3,
             minClearTokens: options.minClearTokens ?? 20_000,
             paybackSafety: options.paybackSafety ?? 0,
+            unseenIsWarm: options.unseenIsWarm ?? false,
             statePath: options.statePath,
         };
         this.load();
@@ -178,16 +216,17 @@ export class AutoClearer {
      * Rewrite `body` in place: an Anthropic Messages, OpenAI Chat Completions or
      * OpenAI Responses request. Never throws; anything unrecognised is left alone.
      */
-    apply(body, now = Date.now()) {
+    apply(body, now = Date.now(), modelHint) {
         const none = (reason, cold = false) => ({ changed: false, newlyCleared: 0, tokensRemoved: 0, cold, reason, firstChanged: -1 });
         try {
             const view = viewOf(body);
             if (!view)
                 return none("no messages");
-            const model = typeof body.model === "string" ? body.model : undefined;
+            // Gemini puts the model in the URL, not the body; the proxy passes it.
+            const model = typeof body.model === "string" ? body.model : modelHint;
             const key = conversationKey(view);
             const conv = this.convs.get(key);
-            const cold = !conv || now - conv.last > view.ttlMs;
+            const cold = conv ? now - conv.last > view.ttlMs : !this.opts.unseenIsWarm;
             this.convs.set(key, { last: now, requests: (conv?.requests ?? 0) + 1 });
             if (this.convs.size > 2000)
                 this.convs.delete(this.convs.keys().next().value);

package/dist/ci.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `context-doctor ci`: the memory-file check for pull requests.
+ *
+ * CLAUDE.md, AGENTS.md, GEMINI.md and always-applied rules are re-read on
+ * every request of every session by everyone who works in the repository, so
+ * a PR that grows them by 2k tokens is a standing cost nobody reviews. This
+ * compares those files (and what they @import) at HEAD against a base commit,
+ * prints a table, and exits 1 over a budget, so CI can comment and gate.
+ *
+ * Base contents come from `git show <base>:<path>`; nothing is checked out.
+ */
+export interface CiFile {
+    path: string;
+    agent: string;
+    base: number;
+    head: number;
+    /** Loaded through an @import rather than directly. */
+    imported?: boolean;
+}
+export interface CiReport {
+    base?: string;
+    files: CiFile[];
+    baseTotal: number;
+    headTotal: number;
+    breaches: string[];
+}
+export declare function ciReport(opts?: {
+    cwd?: string;
+    base?: string;
+    maxTokens?: number;
+    maxIncrease?: number;
+}): CiReport;
+/** Markdown for a PR comment or a job summary. */
+export declare function renderCiMarkdown(r: CiReport, opts?: {
+    model?: string;
+    requestsPerDay?: number;
+}): string;
+/** Plain-text rendering for a terminal. */
+export declare function renderCiText(r: CiReport): string;

package/dist/ci.js

@@ -0,0 +1,144 @@
+/**
+ * `context-doctor ci`: the memory-file check for pull requests.
+ *
+ * CLAUDE.md, AGENTS.md, GEMINI.md and always-applied rules are re-read on
+ * every request of every session by everyone who works in the repository, so
+ * a PR that grows them by 2k tokens is a standing cost nobody reviews. This
+ * compares those files (and what they @import) at HEAD against a base commit,
+ * prints a table, and exits 1 over a budget, so CI can comment and gate.
+ *
+ * Base contents come from `git show <base>:<path>`; nothing is checked out.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { estimateTokens, formatTokens } from "./tokens.js";
+import { formatUsd, pricingFor } from "./pricing.js";
+const CLAUDE = "claude-opus-5";
+/** Repo-relative paths (posix) that agents load on every request. */
+const MEMORY_PATTERNS = [
+    [/(^|\/)CLAUDE(\.local)?\.md$/, "Claude Code"],
+    [/(^|\/)\.claude\/CLAUDE\.md$/, "Claude Code"],
+    [/(^|\/)\.claude\/rules\/.+\.md$/, "Claude Code"],
+    [/(^|\/)AGENTS(\.override)?\.md$/, "Codex"],
+    [/(^|\/)GEMINI\.md$/, "Gemini CLI"],
+    [/(^|\/)\.cursorrules$/, "Cursor"],
+    [/(^|\/)\.cursor\/rules\/.+\.mdc?$/, "Cursor"],
+];
+function git(args, cwd) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 });
+    }
+    catch {
+        return undefined;
+    }
+}
+function agentFor(path) {
+    return MEMORY_PATTERNS.find(([re]) => re.test(path))?.[1];
+}
+/** Cursor rules count only when always applied; the rest load on demand. */
+function counts(path, text) {
+    return !/\.mdc?$/.test(path) || !path.includes(".cursor/rules/") || /^alwaysApply:\s*true/m.test(text);
+}
+/** `@path` imports (Claude Code), resolved relative to the importing file, repo-relative. */
+function importsOf(text, from) {
+    const out = [];
+    let fence = false;
+    for (const line of text.split("\n")) {
+        if (/^\s*(```|~~~)/.test(line))
+            fence = !fence;
+        if (fence)
+            continue;
+        for (const m of line.replace(/`[^`]*`/g, "").matchAll(/(?:^|\s)@((?:\.{0,2}\/|[\w.-]+\/)[^\s)]+|[\w.-]+\.\w+)/g)) {
+            if (m[1].startsWith("/") || m[1].startsWith("~"))
+                continue; // outside the repo
+            out.push(posix.normalize(posix.join(posix.dirname(from), m[1])));
+        }
+    }
+    return out.filter((p) => !p.startsWith(".."));
+}
+/** Token totals per memory file, with a reader for one side (HEAD from disk, base from git). */
+function measure(paths, read) {
+    const out = new Map();
+    const visit = (p, imported, depth) => {
+        if (out.has(p))
+            return;
+        const text = read(p);
+        if (text === undefined || !counts(p, text))
+            return;
+        out.set(p, { tokens: estimateTokens(text, CLAUDE), imported });
+        // Only Claude Code resolves @imports; an imported file can import further.
+        if (depth < 4 && (imported || agentFor(p) === "Claude Code"))
+            for (const i of importsOf(text, p))
+                visit(i, true, depth + 1);
+    };
+    for (const p of paths)
+        visit(p, false, 0);
+    return out;
+}
+export function ciReport(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const root = git(["rev-parse", "--show-toplevel"], cwd)?.trim() ?? cwd;
+    const headList = (git(["ls-files", "--cached", "--others", "--exclude-standard"], root) ?? "").split("\n").filter(Boolean);
+    const baseList = opts.base ? (git(["ls-tree", "-r", "--name-only", opts.base], root) ?? "").split("\n").filter(Boolean) : [];
+    const head = measure(headList.filter((p) => agentFor(p)), (p) => (existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : undefined));
+    const base = opts.base ? measure(baseList.filter((p) => agentFor(p)), (p) => git(["show", `${opts.base}:${p}`], root)) : new Map();
+    const files = [...new Set([...head.keys(), ...base.keys()])].sort().map((p) => ({
+        path: p,
+        agent: agentFor(p) ?? "Claude Code",
+        base: base.get(p)?.tokens ?? 0,
+        head: head.get(p)?.tokens ?? 0,
+        imported: (head.get(p) ?? base.get(p))?.imported || undefined,
+    }));
+    const baseTotal = files.reduce((s, f) => s + f.base, 0);
+    const headTotal = files.reduce((s, f) => s + f.head, 0);
+    const breaches = [];
+    if (opts.maxTokens !== undefined && headTotal > opts.maxTokens)
+        breaches.push(`memory files total ~${formatTokens(headTotal)} tokens, over the ${formatTokens(opts.maxTokens)} budget`);
+    if (opts.base && opts.maxIncrease !== undefined && headTotal - baseTotal > opts.maxIncrease) {
+        breaches.push(`this change adds ~${formatTokens(headTotal - baseTotal)} tokens, over the ${formatTokens(opts.maxIncrease)} allowed increase`);
+    }
+    return { base: opts.base, files, baseTotal, headTotal, breaches };
+}
+const signed = (n) => (n > 0 ? `+${formatTokens(n)}` : n < 0 ? `−${formatTokens(-n)}` : "0");
+/** Markdown for a PR comment or a job summary. */
+export function renderCiMarkdown(r, opts = {}) {
+    // The marker lets the GitHub Action find and update its own comment.
+    const out = ["<!-- context-doctor -->", "### context-doctor: what every agent request re-reads", ""];
+    if (r.files.length === 0) {
+        out.push("No agent memory files (CLAUDE.md, AGENTS.md, GEMINI.md, rules) in this repository.");
+        return out.join("\n");
+    }
+    const changed = r.base ? r.files.filter((f) => f.base !== f.head) : r.files;
+    const delta = r.headTotal - r.baseTotal;
+    out.push(r.base
+        ? `Memory files: **~${formatTokens(r.baseTotal)} → ~${formatTokens(r.headTotal)} tokens (${signed(delta)})**, loaded into every request of every session in this repo.`
+        : `Memory files: **~${formatTokens(r.headTotal)} tokens**, loaded into every request of every session in this repo.`);
+    const price = pricingFor(opts.model ?? "claude-sonnet-5");
+    if (price && opts.requestsPerDay && r.base && delta !== 0) {
+        // Cache reads on warm requests; this is the floor of the cost, cold starts add to it.
+        const usd = ((delta * price.cacheReadPerM) / 1e6) * opts.requestsPerDay * 30;
+        out.push(`At ${opts.requestsPerDay.toLocaleString("en-US")} requests a day on ${opts.model ?? "claude-sonnet-5"} (cached reads), that is ${usd >= 0 ? "+" : "−"}${formatUsd(Math.abs(usd))} a month.`);
+    }
+    out.push("");
+    if (changed.length) {
+        out.push(r.base ? "| File | Agent | Base | This PR | Change |" : "| File | Agent | Tokens |", r.base ? "|---|---|---:|---:|---:|" : "|---|---|---:|");
+        for (const f of changed) {
+            const name = `\`${f.path}\`${f.imported ? " (imported)" : ""}`;
+            out.push(r.base ? `| ${name} | ${f.agent} | ${f.base ? "~" + formatTokens(f.base) : "—"} | ${f.head ? "~" + formatTokens(f.head) : "—"} | ${signed(f.head - f.base)} |` : `| ${name} | ${f.agent} | ~${formatTokens(f.head)} |`);
+        }
+    }
+    else {
+        out.push("No memory file changed in this PR.");
+    }
+    if (r.breaches.length)
+        out.push("", ...r.breaches.map((b) => `**Over budget:** ${b}.`));
+    const big = r.files.filter((f) => f.head >= 2000);
+    if (big.length)
+        out.push("", `Large files: ${big.map((f) => `\`${f.path}\``).join(", ")}. \`npx context-doctor overhead split <file>\` moves reference sections out, word for word.`);
+    return out.join("\n");
+}
+/** Plain-text rendering for a terminal. */
+export function renderCiText(r) {
+    return renderCiMarkdown(r).replace("<!-- context-doctor -->\n", "").replace(/^### /m, "").replace(/\*\*/g, "").replace(/`/g, "");
+}