context-doctor 0.26.0 → 0.28.0

package/README.md

@@ -1,49 +1,66 @@
 # context-doctor 🩺
 
-[![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)
+[![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) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.KushalP1%2Fcontext--doctor-blue)](https://registry.modelcontextprotocol.io) [![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.**
+**See where your AI agent's tokens go, and stop paying for the ones that do nothing.**
 
-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.
+AI agents re-send their whole context on every message: old tool output, pasted files, long instructions. A 500k-token session pays for all of it again each time, and at full price after a coffee break, when the prompt cache has expired. context-doctor measures that waste on your own sessions, in dollars, and removes it at the moments it pays: before it enters the context, while it sits there, and on every request.
 
-- **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.
+It runs on your machine, needs no API key, sends no telemetry, and works with **Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI**, any app on the **Anthropic, OpenAI or Gemini API**, and **CI**. MIT licensed, Node 20+, macOS, Linux and Windows.
 
-Built and maintained by [gAI Ventures](https://gai.ventures).
+```bash
+npx context-doctor savings     # what your recent sessions cost, and what each fix would have saved
+```
+
+<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">
 
 ## Quick start
 
-**See what it would save you first** (no install, reads your local Claude Code history):
+Pick where you work. Each takes about a minute and is fully reversible.
 
-```bash
-npx context-doctor savings
-```
+| You use | Do this |
+|---|---|
+| **Claude Code** (terminal, IDE, desktop app) | Inside Claude Code: `/plugin marketplace add KushalP1/context-doctor`, then `/plugin install context-doctor@context-doctor`. You get the every-prompt check, the MCP tools and `/context-doctor:savings`, `:checkup`, `:overhead`, `:pack`, `:autopilot`, `:compact-window` |
+| **Everything on this machine at once** | `npm install -g context-doctor && context-doctor install` wires Claude Code, Claude Desktop, Cursor, Codex and Gemini CLI. `context-doctor doctor` checks it; `context-doctor uninstall` removes it |
+| **Claude Desktop, Cursor or any MCP client** | Add the server to the client's MCP config (or install the one-click `.mcpb` from the [latest release](https://github.com/KushalP1/context-doctor/releases/latest) in Claude Desktop):<br>`{"mcpServers": {"context-doctor": {"command": "npx", "args": ["-y", "context-doctor", "mcp"]}}}` |
+| **claude.ai, ChatGPT, phone apps** | `npx context-doctor instructions --copy`, then paste into the app's personal preferences |
+| **Your own app on an LLM API** | Run `npx context-doctor proxy --autopilot` and point `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL` (add `/v1`) or `GOOGLE_GEMINI_BASE_URL` at `http://localhost:8787`. No proxy possible? Wrap the SDK client: `withContextDoctor(new Anthropic())` |
+| **GitHub pull requests** | `uses: KushalP1/context-doctor@v0.27.0` comments how much a PR grows CLAUDE.md, AGENTS.md and rules, and can fail over a budget ([setup](#enforce-a-budget-in-ci)) |
 
-<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">
+## What it does
 
-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.
+**Measure, in dollars, on your own history**
+- `savings`: what your recent Claude Code sessions cost and what each fix below would have saved, replayed request by request against what you were billed.
+- `overhead`: what every request re-reads before your message (system prompt, tools, MCP servers, CLAUDE.md, rules, memory), each file priced per month.
+- `session`, `watch`, `analyze`, `report`, `dashboard`: token breakdown and wasted-context findings for any session, conversation file or agent trace.
 
-**Then install it**, whichever way suits you:
+**Keep waste out of the context**
+- `pack` (and the `pack_context` MCP tool): only the chunks of a big document, PDF, log or codebase that a question needs, within a token budget, instead of the whole thing.
+- `overhead split`: turns a heavy CLAUDE.md or memory file into a lean one plus a reference file the agent opens when needed, word for word, nothing lost.
+- `ci` and the GitHub Action: review memory-file growth like any other cost.
 
-```bash
-# Everything, every app it finds (Claude Code, Cursor, Codex, Claude Desktop)
-npm install -g context-doctor
-context-doctor install
-context-doctor autopilot on     # every new Claude Code session keeps its context lean
-```
+**Remove waste automatically**
+- An every-prompt hook (Claude Code, Codex, Gemini CLI; Cursor after each tool call) tells the model its real context size and the largest waste, and offers `/compact` when you return to a big session after the cache expired.
+- `compact-window`: sets Claude Code's own auto-compact window, measured on your history first. Works in the desktop app too.
+- Autopilot: a local proxy (or SDK wrapper) that clears stale tool output only when the prompt cache is cold, so a request never costs more.
 
-```text
-# Or as a Claude Code plugin, from inside Claude Code
-/plugin marketplace add KushalP1/context-doctor
-/plugin install context-doctor@context-doctor
-```
+## What it has measured
 
-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.
+On the author's own Claude Code history (mostly Opus and Fable models with the 1M window, priced at API list prices; `savings` computes yours the same way):
 
-`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`.
+- **Compacting when you come back after the cache expired:** 401 such returns in 133 days; compacting then would have saved **$4,053 net, about $914 a month**. [Details →](#what-it-saves)
+- **A 400k auto-compact window instead of ~970k:** **55% less input cost** over 30 days ($6,119 to $2,757), for 15 compactions a week instead of 5. [The trade-off →](#3-compacting-earlier-automatic)
+- **Autopilot:** **9.8% less input cost, no session made more expensive.**
+- **pack:** 9 of 10 questions about this repository answered from **0.6% of its tokens**. [How →](#before-it-enters-the-context-pack-and-overhead)
+- **Counting 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%. `context-doctor accuracy` re-checks the ratio on your own sessions.
+
+On a Claude subscription you do not pay list price; the same tokens come out of your usage limit instead, so read the dollars as the size of the effect.
+
+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).
+
+A profile looks like this (`npx context-doctor analyze conversation.json`, or `session` for your latest Claude Code session):
 
 ```
 Where the tokens go
@@ -107,15 +124,58 @@ On a Claude subscription you do not pay list price; the same tokens come out of
 | **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 |
+| **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.28 Wider reach**: `/context-doctor:overhead` and `/context-doctor:pack` in the Claude Code plugin; `pack` reads a folder inside a git repository the way git does, so `.gitignore`'d build output and secrets stay out; `withContextDoctor` wraps Google's `@google/genai` client too; `overhead` measures the fixed start-of-session cost of Codex and Gemini CLI sessions as well as Claude Code's, priced with each provider's cache rules.
+- **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.
@@ -191,6 +251,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 (Claude Code, Codex and Gemini CLI sessions), 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`) |
@@ -395,6 +459,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
@@ -408,8 +473,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) and Google's `models.generateContent` / `generateContentStream` 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:
@@ -573,6 +654,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
 ```
@@ -628,7 +732,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.
 

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

@@ -48,6 +48,8 @@ export const CLEARABLE_TOOLS = new Set([
     // 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", "SemanticSearch", "ReadLints", "AwaitShell",
 ]);
@@ -84,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;
@@ -97,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) => {
@@ -171,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();
@@ -179,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, "");
+}