context-doctor 0.27.0 → 0.29.0

package/README.md

@@ -1,58 +1,69 @@
 # 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)
 
-**Cut your Claude Code bill, measured on your own sessions.**
+**See where your AI agent's tokens go, and stop paying for the ones that do nothing.**
+
+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.
+
+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.
 
 ```bash
-npx context-doctor savings
+npx context-doctor savings     # what your recent sessions cost, and what each fix would have saved
 ```
 
-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.
+<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">
 
-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.
+## Quick start
 
-- **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, 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.
+Pick where you work. Each takes about a minute and is fully reversible.
 
-Built and maintained by [gAI Ventures](https://gai.ventures).
+| 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())` |
+| **Python / RAG pipelines** | `pip install context-doctor` (after the first PyPI release; until then `pip install "git+https://github.com/KushalP1/context-doctor#subdirectory=python"`), then `pack_documents(retrieved_docs, question, budget=4000)` trims LangChain or LlamaIndex results to the chunks that matter. [Python README](./python/README.md) |
+| **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)) |
 
-> **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.
+## What it does
 
-## Quick start
+**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.
+- `tasks`: cost per commit, per project, from each session's recorded usage and its own `git commit` calls.
+- `reads`: the files read into session after session, and whether a CLAUDE.md summary or `pack` would pay.
+- `session`, `watch`, `analyze`, `report`, `dashboard`: token breakdown and wasted-context findings for any session, conversation file or agent trace.
 
-**See what it would save you first** (no install, reads your local Claude Code history):
+**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
-npx context-doctor savings
-```
+**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.
 
-<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 has measured
 
-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.
+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):
 
-**Then install it**, whichever way suits you:
+- **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.
 
-```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
-```
+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.
 
-```text
-# Or as a Claude Code plugin, from inside Claude Code
-/plugin marketplace add KushalP1/context-doctor
-/plugin install context-doctor@context-doctor
-```
+Built and maintained by [gAI Ventures](https://gai.ventures).
 
-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.
+> **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).
 
-`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`.
+A profile looks like this (`npx context-doctor analyze conversation.json`, or `session` for your latest Claude Code session):
 
 ```
 Where the tokens go
@@ -166,6 +177,8 @@ MCP servers are part of the same overhead: each one's tool definitions ride on e
 
 ## What's new
 
+- **0.29 Python, and where the work goes**: a dependency-free Python package (`python/`) with `pack_documents` for LangChain and LlamaIndex results, `pack_context`, `estimate_tokens` and `profile_messages`, held byte for byte to the TypeScript by parity tests. `context-doctor reads` shows the files read into session after session; `context-doctor tasks` shows cost per commit per project, from your own transcripts.
+- **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.
@@ -243,7 +256,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `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 [--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 |
@@ -480,7 +493,7 @@ console.log(packed.selected.map((c) => `${c.id} L${c.startLine}-${c.endLine}`),
 
 ### 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.
+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
 

package/dist/cli.js

@@ -42,9 +42,11 @@ import { listCursorChats, parseCursorChat } from "./cursor.js";
 import { analyzeCacheUsage, renderCacheReport } from "./cache.js";
 import { renderToolTimings } from "./timing.js";
 import { packContextSemantic, readSources, renderPack } from "./pack.js";
-import { measureBaseline, measureMcpSizes, overheadReport, renderOverhead } from "./overhead.js";
+import { measureBaselines, measureMcpSizes, overheadReport, renderOverhead } from "./overhead.js";
 import { applySplit, planSplit, renderSplit } from "./split.js";
 import { ciReport, renderCiMarkdown, renderCiText } from "./ci.js";
+import { renderReads, repeatedReads } from "./reads.js";
+import { costPerTask, renderTasks } from "./tasks.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -102,6 +104,10 @@ Usage:
   context-doctor ci [--base <ref>] [--max-tokens n] [--max-increase n] [--markdown]
                                                 For pull requests: memory files (CLAUDE.md, AGENTS.md,
                                                 GEMINI.md, rules) at HEAD vs base; exit 1 over budget
+  context-doctor tasks [--days n]               Cost per commit, per project: session cost at list
+                                                price vs commits made during the sessions
+  context-doctor reads [--days n] [--limit n]   Files read into session after session: reads, tokens,
+                                                cost, and whether a CLAUDE.md summary or pack pays
   context-doctor overhead split <file> [--write]
                                                 Move a memory file's big sections to a reference
                                                 file, leaving pointers (plan first; --write backs up)
@@ -711,6 +717,16 @@ async function main() {
         });
         return; // server keeps the process alive
     }
+    if (args.command === "tasks") {
+        const report = costPerTask(args.days ?? 30);
+        console.log(args.json ? JSON.stringify(report, null, 2) : renderTasks(report, args.limit ?? 12));
+        return;
+    }
+    if (args.command === "reads") {
+        const report = repeatedReads(args.days ?? 30);
+        console.log(args.json ? JSON.stringify(report, null, 2) : renderReads(report, args.limit ?? 15));
+        return;
+    }
     if (args.command === "ci") {
         const report = ciReport({ base: args.base, maxTokens: args.maxTokens, maxIncrease: args.maxIncrease });
         console.log(args.json ? JSON.stringify(report, null, 2) : args.markdown ? renderCiMarkdown(report, { model: args.model, requestsPerDay: args.requestsPerDay }) : renderCiText(report));
@@ -732,7 +748,9 @@ async function main() {
             console.error(`Could not read ${file}: ${e.message}`);
             process.exit(1);
         }
-        console.log(renderSplit(plan, measureBaseline(args.days ?? 30)?.usdPerKPerMonth));
+        // Price the file at the rate of the agent that loads it.
+        const agent = /AGENTS(\.override)?\.md$/i.test(file) ? "Codex" : /GEMINI\.md$/i.test(file) ? "Gemini CLI" : "Claude Code";
+        console.log(renderSplit(plan, measureBaselines(args.days ?? 30).find((b) => b.agent === agent)?.usdPerKPerMonth));
         if (args.write && plan.sections.some((s) => s.moved)) {
             const { backup } = applySplit(plan);
             console.log(`\nWritten. Backup: ${backup}\nUndo: mv "${backup}" "${file}" (and delete or trim ${plan.referencePath}).`);

package/dist/gemini.d.ts

@@ -18,6 +18,8 @@
 import { type ParsedSession, type SessionInfo } from "./session.js";
 /** True when the file's first record looks like a Gemini CLI chat (cheap: reads 4 KB). */
 export declare function isGeminiChat(path: string): boolean;
+/** The ordered, de-duplicated, rewind-applied messages of a chat file. */
+export declare function readGeminiMessages(path: string): any[];
 export declare function parseGeminiChat(path: string): ParsedSession;
 /** Gemini CLI chats on this machine: ~/.gemini/tmp/<project>/chats/session-*.json[l]. */
 export declare function listGeminiChats(home?: string): SessionInfo[];

package/dist/gemini.js

@@ -62,7 +62,7 @@ function resultText(call) {
     return typeof call?.resultDisplay === "string" ? call.resultDisplay : r === undefined ? "" : JSON.stringify(r);
 }
 /** The ordered, de-duplicated, rewind-applied messages of a chat file. */
-function readMessages(path) {
+export function readGeminiMessages(path) {
     const order = [];
     const byId = new Map();
     let anon = 0;
@@ -115,7 +115,7 @@ export function parseGeminiChat(path) {
     const usageSamples = [];
     let model;
     let reportedInputTokens;
-    for (const m of readMessages(path)) {
+    for (const m of readGeminiMessages(path)) {
         if (m.type === "user") {
             const t = text(m.content);
             if (t)

package/dist/index.d.ts

@@ -32,3 +32,5 @@ export * from "./split.js";
 export * from "./mcpschema.js";
 export * from "./wrap.js";
 export * from "./ci.js";
+export * from "./reads.js";
+export * from "./tasks.js";

package/dist/index.js

@@ -27,3 +27,5 @@ export * from "./split.js";
 export * from "./mcpschema.js";
 export * from "./wrap.js";
 export * from "./ci.js";
+export * from "./reads.js";
+export * from "./tasks.js";

package/dist/mcp.js

@@ -52,7 +52,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer({ fileAccess = true } = {}) {
-    const server = new McpServer({ name: "context-doctor", version: "0.27.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.29.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~120 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({

package/dist/overhead.d.ts

@@ -29,6 +29,7 @@ export interface OverheadFinding {
     suggestion: string;
 }
 export interface Baseline {
+    agent: Agent;
     sessions: number;
     /** Median tokens of the first request, minus the first user message. */
     median: number;
@@ -42,7 +43,10 @@ export interface Baseline {
 }
 export interface OverheadReport {
     cwd: string;
+    /** Claude Code's baseline (memory-file prices for Claude Code are quoted against it). */
     baseline?: Baseline;
+    /** Every agent with sessions in the period: Claude Code, Codex, Gemini CLI. */
+    baselines: Baseline[];
     files: MemoryFile[];
     findings: OverheadFinding[];
     mcp: McpSection;
@@ -56,13 +60,16 @@ export interface McpSection {
 /** Every memory file the four agents load for a session started in `cwd`. */
 export declare function findMemoryFiles(cwd?: string, home?: string): MemoryFile[];
 /**
- * Fixed overhead per session, measured: the first main-chain request's input
- * (input + cache read + cache write) minus the first user message, plus the
+ * Fixed overhead per session and agent, measured: each session's first
+ * request (the API's own count) minus the first user message, plus the
  * request and cold-start counts that turn tokens into a monthly bill.
+ * Claude Code, Codex and Gemini CLI sessions, newest `days` only.
  */
+export declare function measureBaselines(days?: number, paths?: string[]): Baseline[];
+/** Claude Code's baseline (the one memory-file prices are quoted against). */
 export declare function measureBaseline(days?: number, paths?: string[]): Baseline | undefined;
 /** What is worth changing in the memory files. */
-export declare function overheadFindings(files: MemoryFile[], baseline?: Baseline): OverheadFinding[];
+export declare function overheadFindings(files: MemoryFile[], baselines?: Baseline | Baseline[]): OverheadFinding[];
 export declare function overheadReport(opts?: {
     cwd?: string;
     home?: string;

package/dist/overhead.js

@@ -18,8 +18,9 @@ import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { forEachLine, listSessions } from "./session.js";
-import { estimateTokens, formatTokens } from "./tokens.js";
+import { estimateTokens, formatTokens, providerFor } from "./tokens.js";
 import { formatUsd, pricingFor } from "./pricing.js";
+import { isGeminiChat, readGeminiMessages } from "./gemini.js";
 import { claudeMcpConfigs, mcpUsage, measureServer, toolPrefixName } from "./mcpschema.js";
 const TTL_MS = 3_600_000;
 const CLAUDE = "claude-opus-5"; // Claude's tokenizer ratios; the model only picks the provider here.
@@ -139,72 +140,147 @@ export function findMemoryFiles(cwd = process.cwd(), home = homedir()) {
             add("Gemini CLI", join(d, "GEMINI.md"), "project");
     return files;
 }
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((b) => (typeof b === "string" ? b : typeof b?.text === "string" ? b.text : "")).filter(Boolean).join("\n");
+}
+/** Claude Code: usage rows on assistant messages (one per API reply id). */
+function claudeUsage(path) {
+    const out = { agent: "Claude Code", reqs: [] };
+    let firstUser;
+    let lastId;
+    forEachLine(path, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (e.type === "user" && out.first === undefined && firstUser === undefined && !e.isMeta) {
+            const text = textOf(e.message?.content);
+            if (text)
+                firstUser = text;
+            return;
+        }
+        if (e.type !== "assistant" || !e.message?.usage || e.message.id === lastId)
+            return;
+        lastId = e.message.id;
+        const u = e.message.usage;
+        const prompt = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+        const at = Date.parse(e.timestamp);
+        if (!(prompt > 0) || !Number.isFinite(at))
+            return;
+        out.first ??= Math.max(0, prompt - estimateTokens(firstUser ?? "", CLAUDE));
+        out.reqs.push({ at, model: e.message.model });
+    });
+    return out;
+}
 /**
- * Fixed overhead per session, measured: the first main-chain request's input
- * (input + cache read + cache write) minus the first user message, plus the
- * request and cold-start counts that turn tokens into a monthly bill.
+ * Codex rollouts: token_count events carry each request's input (cached part
+ * included). Codex sends AGENTS.md and its environment as user messages;
+ * those are overhead, so the first real prompt is the one subtracted.
  */
-export function measureBaseline(days = 30, paths) {
-    const since = Date.now() - days * 86_400_000;
-    const files = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
+function codexUsage(path) {
+    const out = { agent: "Codex", reqs: [] };
+    let firstUser;
+    let model;
+    forEachLine(path, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const p = e?.payload;
+        if (!p)
+            return;
+        if (e.type === "turn_context" && typeof p.model === "string")
+            model = p.model;
+        if (e.type === "response_item" && p.type === "message" && p.role === "user" && firstUser === undefined) {
+            const text = textOf(p.content);
+            if (text && !/^\s*(<user_instructions>|<environment_context>|# AGENTS\.md)/.test(text))
+                firstUser = text;
+        }
+        if (e.type === "event_msg" && p.type === "token_count") {
+            const input = Number(p.info?.last_token_usage?.input_tokens);
+            const at = Date.parse(e.timestamp);
+            if (!(input > 0) || !Number.isFinite(at))
+                return;
+            out.first ??= Math.max(0, input - estimateTokens(firstUser ?? "", model));
+            out.reqs.push({ at, model });
+        }
+    });
+    return out;
+}
+/** Gemini CLI chats: each gemini message records its request's promptTokenCount. */
+function geminiUsage(path) {
+    const out = { agent: "Gemini CLI", reqs: [] };
+    let firstUser;
+    for (const m of readGeminiMessages(path)) {
+        if (m?.type === "user" && firstUser === undefined)
+            firstUser = textOf(m.content) || undefined;
+        if (m?.type !== "gemini")
+            continue;
+        const input = Number(m.tokens?.input);
+        const at = Date.parse(m.timestamp);
+        if (!(input > 0) || !Number.isFinite(at))
+            continue;
+        out.first ??= Math.max(0, input - estimateTokens(firstUser ?? "", m.model));
+        out.reqs.push({ at, model: m.model });
+    }
+    return out;
+}
+function usageOf(path) {
+    if (isGeminiChat(path))
+        return geminiUsage(path);
+    if (/[\\/]\.codex[\\/]/.test(path))
+        return codexUsage(path);
+    return claudeUsage(path);
+}
+/** Cache writes cost 1.25x input on Anthropic; OpenAI and Google charge no write premium. */
+function writeMultiplier(model) {
+    return providerFor(model) === "anthropic" ? 1.25 : 1;
+}
+function aggregate(agent, sessions, since, days) {
     const firsts = [];
-    let requests = 0, coldStarts = 0;
+    let requests = 0, coldStarts = 0, warm = 0;
     const models = new Map();
-    for (const path of files) {
-        let firstUser;
-        let first;
-        let lastId;
+    for (const s of sessions) {
+        if (s.first !== undefined && s.first > 1000)
+            firsts.push(s.first);
         let prevAt;
-        forEachLine(path, (line) => {
-            let e;
-            try {
-                e = JSON.parse(line);
-            }
-            catch {
-                return;
-            }
-            if (!e || e.isSidechain)
-                return;
-            if (e.type === "user" && first === undefined && firstUser === undefined && !e.isMeta) {
-                const c = e.message?.content;
-                const text = typeof c === "string" ? c : Array.isArray(c) ? c.filter((b) => b?.type === "text").map((b) => b.text).join("\n") : "";
-                if (text)
-                    firstUser = text;
-                return;
-            }
-            if (e.type !== "assistant" || !e.message?.usage || e.message.id === lastId)
-                return;
-            lastId = e.message.id;
-            const u = e.message.usage;
-            const prompt = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
-            const at = Date.parse(e.timestamp);
-            if (!(prompt > 0) || !Number.isFinite(at))
-                return;
-            if (first === undefined)
-                first = Math.max(0, prompt - estimateTokens(firstUser ?? "", CLAUDE));
-            if (at >= since) {
+        for (const r of s.reqs) {
+            if (r.at >= since) {
                 requests++;
-                if (prevAt === undefined || at - prevAt > TTL_MS)
+                if (prevAt === undefined || r.at - prevAt > TTL_MS)
                     coldStarts++;
-                if (e.message.model)
-                    models.set(e.message.model, (models.get(e.message.model) ?? 0) + 1);
+                else
+                    warm++;
+                if (r.model)
+                    models.set(r.model, (models.get(r.model) ?? 0) + 1);
             }
-            prevAt = at;
-        });
-        if (first !== undefined && first > 1000)
-            firsts.push(first);
+            prevAt = r.at;
+        }
     }
     if (firsts.length === 0)
         return undefined;
     firsts.sort((a, b) => a - b);
     const model = [...models.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
     const price = pricingFor(model);
-    // Each overhead token is a cache read on warm requests and a cache write
-    // (1.25x input) after every cold start.
+    // Each overhead token is a cache read on warm requests and a full-price
+    // write (with the provider's premium) after every cold start.
     const usdPerKPerMonth = price
-        ? ((1000 * ((requests - coldStarts) * price.cacheReadPerM + coldStarts * 1.25 * price.inputPerM)) / 1e6) * (30 / days)
+        ? ((1000 * (warm * price.cacheReadPerM + coldStarts * writeMultiplier(model) * price.inputPerM)) / 1e6) * (30 / days)
         : undefined;
     return {
+        agent,
         sessions: firsts.length,
         median: firsts[Math.floor(firsts.length / 2)],
         p90: firsts[Math.min(firsts.length - 1, Math.floor(firsts.length * 0.9))],
@@ -215,18 +291,52 @@ export function measureBaseline(days = 30, paths) {
         usdPerKPerMonth,
     };
 }
+/**
+ * Fixed overhead per session and agent, measured: each session's first
+ * request (the API's own count) minus the first user message, plus the
+ * request and cold-start counts that turn tokens into a monthly bill.
+ * Claude Code, Codex and Gemini CLI sessions, newest `days` only.
+ */
+export function measureBaselines(days = 30, paths) {
+    const since = Date.now() - days * 86_400_000;
+    const files = paths ?? listSessions(10_000).filter((s) => s.modifiedAt.getTime() >= since).map((s) => s.path);
+    const byAgent = new Map();
+    for (const path of files) {
+        let u;
+        try {
+            u = usageOf(path);
+        }
+        catch {
+            continue;
+        }
+        (byAgent.get(u.agent) ?? byAgent.set(u.agent, []).get(u.agent)).push(u);
+    }
+    const order = ["Claude Code", "Codex", "Gemini CLI"];
+    return order.flatMap((a) => {
+        const b = byAgent.has(a) ? aggregate(a, byAgent.get(a), since, days) : undefined;
+        return b ? [b] : [];
+    });
+}
+/** Claude Code's baseline (the one memory-file prices are quoted against). */
+export function measureBaseline(days = 30, paths) {
+    return measureBaselines(days, paths).find((b) => b.agent === "Claude Code");
+}
 function normalize(s) {
     return s.toLowerCase().replace(/\s+/g, " ").trim();
 }
 /** What is worth changing in the memory files. */
-export function overheadFindings(files, baseline) {
+export function overheadFindings(files, baselines) {
     const out = [];
-    const cost = (tok) => (baseline?.usdPerKPerMonth ? ` (~${formatUsd((tok / 1000) * baseline.usdPerKPerMonth)}/month at your usage)` : "");
+    const list = Array.isArray(baselines) ? baselines : baselines ? [baselines] : [];
+    const cost = (tok, agent) => {
+        const b = list.find((x) => x.agent === agent);
+        return b?.usdPerKPerMonth ? ` (~${formatUsd((tok / 1000) * b.usdPerKPerMonth)}/month at your usage)` : "";
+    };
     for (const f of files) {
         if (f.tokens >= 2000) {
             out.push({
                 severity: f.tokens >= 5000 ? "warn" : "info",
-                message: `${f.path} is ~${formatTokens(f.tokens)} tokens, read on every ${f.agent} request${f.agent === "Claude Code" ? cost(f.tokens) : ""}.`,
+                message: `${f.path} is ~${formatTokens(f.tokens)} tokens, read on every ${f.agent} request${cost(f.tokens, f.agent)}.`,
                 suggestion: `Keep rules the agent needs on most requests; move reference material to a file it reads when relevant. \`context-doctor overhead split ${f.path}\` shows the split first.`,
             });
         }
@@ -280,9 +390,12 @@ export function overheadReport(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const home = opts.home ?? homedir();
     const files = findMemoryFiles(cwd, home);
-    const baseline = measureBaseline(opts.days ?? 30, opts.paths);
-    const mcp = { configs: claudeMcpConfigs(cwd, home), usage: mcpUsage(opts.days ?? 30, opts.paths) };
-    return { cwd, baseline, files, findings: overheadFindings(files, baseline), mcp };
+    const baselines = measureBaselines(opts.days ?? 30, opts.paths);
+    const baseline = baselines.find((b) => b.agent === "Claude Code");
+    // MCP usage comes from Claude Code transcripts only (the tool-name scheme is theirs).
+    const claudePaths = opts.paths?.filter((p) => !isGeminiChat(p) && !/[\\/]\.codex[\\/]/.test(p));
+    const mcp = { configs: claudeMcpConfigs(cwd, home), usage: mcpUsage(opts.days ?? 30, claudePaths) };
+    return { cwd, baseline, baselines, files, findings: overheadFindings(files, baselines), mcp };
 }
 /** Launch each configured server and size its tool definitions, then add the findings they support. */
 export async function measureMcpSizes(r) {
@@ -323,12 +436,20 @@ export function renderOverhead(r, home = homedir()) {
     else {
         out.push("No Claude Code sessions in the period to measure; memory files are sized below.");
     }
+    for (const o of r.baselines.filter((x) => x.agent !== "Claude Code")) {
+        const tokens = r.files.filter((f) => f.agent === o.agent).reduce((s, f) => s + f.tokens, 0);
+        out.push("", `${o.agent}, last ${o.days} days: ${o.sessions} sessions start at a median ~${formatTokens(o.median)} tokens (p90 ~${formatTokens(o.p90)}); ${tokens ? `memory files loaded here ~${formatTokens(tokens)} of it` : "no memory files of its own here"}.` +
+            (o.usdPerKPerMonth !== undefined
+                ? ` Each 1k tokens ~${formatUsd(o.usdPerKPerMonth)} a month (${o.requests.toLocaleString("en-US")} requests, ${o.coldStarts.toLocaleString("en-US")} cold starts, ${o.model} list prices).`
+                : ""));
+    }
     out.push(...renderMcp(r));
     out.push("", "Memory files loaded in this directory", "─".repeat(56));
     if (r.files.length === 0)
         out.push("  none");
     for (const f of r.files) {
-        const usd = f.agent === "Claude Code" && b?.usdPerKPerMonth !== undefined ? `  ${formatUsd((f.tokens / 1000) * b.usdPerKPerMonth)}/mo` : "";
+        const fb = r.baselines.find((x) => x.agent === f.agent);
+        const usd = fb?.usdPerKPerMonth !== undefined ? `  ${formatUsd((f.tokens / 1000) * fb.usdPerKPerMonth)}/mo` : "";
         out.push(`  ${f.agent.padEnd(11)} ~${formatTokens(f.tokens).padStart(5)}${usd.padEnd(12)}  ${short(f.path)}${f.via === "project" ? "" : `  (${f.via})`}`);
     }
     out.push("", `Findings (${r.findings.length})`, "─".repeat(56));

package/dist/pack.d.ts

@@ -94,11 +94,6 @@ export declare const PACK_LIMITS: {
     fileBytes: number;
     totalBytes: number;
 };
-/**
- * Read files and directories (recursively, skipping build and dependency
- * folders, binaries, and anything past the size limits) into sources.
- * `skipped` says what was left out and why, so nothing vanishes silently.
- */
 export declare function readSources(paths: string[], cwd?: string): {
     sources: PackSource[];
     skipped: string[];

package/dist/pack.js

@@ -13,6 +13,7 @@
  * and no model calls. Lexical ranking misses pure paraphrase; the outline that
  * comes with every result lets the model pick sections by heading when it does.
  */
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, relative } from "node:path";
 import { estimateTokens, formatTokens } from "./tokens.js";
@@ -333,6 +334,19 @@ export const PACK_LIMITS = { files: 500, fileBytes: 5 * 1024 * 1024, totalBytes:
  * folders, binaries, and anything past the size limits) into sources.
  * `skipped` says what was left out and why, so nothing vanishes silently.
  */
+/** Files git would consider part of the repository under `dir` (relative to it), or undefined outside git. */
+function gitFiles(dir) {
+    try {
+        const r = spawnSync("git", ["-C", dir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 30_000 });
+        if (r.status !== 0 || typeof r.stdout !== "string")
+            return undefined;
+        // --cached lists files deleted from the work tree too; only what exists is read.
+        return r.stdout.split("\0").filter((f) => f && existsSync(join(dir, f))).sort();
+    }
+    catch {
+        return undefined;
+    }
+}
 export function readSources(paths, cwd = process.cwd()) {
     const sources = [];
     const skipped = [];
@@ -354,6 +368,15 @@ export function readSources(paths, cwd = process.cwd()) {
         if (st.isDirectory()) {
             if (!top && (SKIP_DIRS.has(basename(p)) || basename(p).startsWith(".")))
                 return;
+            // Inside a git repository the repository says what is source: tracked
+            // files plus untracked ones not ignored, so .gitignore'd build output,
+            // data dumps and secrets stay out. Elsewhere, walk with SKIP_DIRS.
+            const listed = top ? gitFiles(p) : undefined;
+            if (listed) {
+                for (const f of listed)
+                    visit(join(p, f), false);
+                return;
+            }
             for (const e of readdirSync(p).sort())
                 visit(join(p, e), false);
             return;

package/dist/proxy.d.ts

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

package/dist/proxy.js

@@ -20,7 +20,7 @@ import { formatTokens, CHARS_PER_TOKEN, providerFor } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
 import { recordLedger } from "./ledger.js";
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export const PROXY_VERSION = "0.27.0";
+export const PROXY_VERSION = "0.29.0";
 /** Connection-level headers that must not be forwarded. */
 const SKIP_REQUEST_HEADERS = new Set(["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
 const SKIP_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);

package/dist/reads.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `context-doctor reads`: the same files, read into session after session.
+ *
+ * Agents orient themselves by reading the same files at the start of most
+ * sessions: the README, the main module, a config. Each read is written into
+ * that session's context and re-read on every later request, and the next
+ * session pays for it again. This counts Read calls across recent Claude Code
+ * transcripts, groups them by file, and says per file whether a short summary
+ * in the project's CLAUDE.md would pay (read in most of the project's
+ * sessions) or not (CLAUDE.md is paid on every request, so an occasional read
+ * is cheaper left as a read; `pack` can cut it to the part a question needs).
+ */
+export interface RepeatedRead {
+    path: string;
+    project: string;
+    /** Sessions that read it at least once. */
+    sessions: number;
+    /** Sessions of that project in the period. */
+    projectSessions: number;
+    reads: number;
+    /** Tokens of all its results, summed over every read. */
+    tokens: number;
+    /** Floor of the cost: each read written to the prompt cache once (1.25x input). */
+    usd?: number;
+    advice: "summarize" | "pack";
+}
+export interface ReadsReport {
+    days: number;
+    sessions: number;
+    reads: number;
+    readTokens: number;
+    files: RepeatedRead[];
+}
+export declare function repeatedReads(days?: number, paths?: string[], minSessions?: number): ReadsReport;
+export declare function renderReads(r: ReadsReport, limit?: number, home?: string): string;

package/dist/reads.js

@@ -0,0 +1,151 @@
+/**
+ * `context-doctor reads`: the same files, read into session after session.
+ *
+ * Agents orient themselves by reading the same files at the start of most
+ * sessions: the README, the main module, a config. Each read is written into
+ * that session's context and re-read on every later request, and the next
+ * session pays for it again. This counts Read calls across recent Claude Code
+ * transcripts, groups them by file, and says per file whether a short summary
+ * in the project's CLAUDE.md would pay (read in most of the project's
+ * sessions) or not (CLAUDE.md is paid on every request, so an occasional read
+ * is cheaper left as a read; `pack` can cut it to the part a question needs).
+ */
+import { forEachLine, listSessions } from "./session.js";
+import { estimateTokens, formatTokens } from "./tokens.js";
+import { formatUsd, pricingFor } from "./pricing.js";
+const CLAUDE = "claude-opus-5";
+/** An image in a tool result bills as an image (~1.6k tokens for a full-size screenshot), not as its base64. */
+const IMAGE_TOKENS = 1600;
+function resultTokens(content) {
+    if (typeof content === "string")
+        return estimateTokens(content, CLAUDE);
+    if (!Array.isArray(content))
+        return estimateTokens(JSON.stringify(content ?? ""), CLAUDE);
+    let n = 0;
+    for (const part of content) {
+        if (part?.type === "image")
+            n += IMAGE_TOKENS;
+        else if (typeof part?.text === "string")
+            n += estimateTokens(part.text, CLAUDE);
+        else
+            n += estimateTokens(JSON.stringify(part ?? ""), CLAUDE);
+    }
+    return n;
+}
+/** Read calls in one transcript: path -> {reads, tokens}, plus the session's model and project directory. */
+function sessionReads(path) {
+    const pending = new Map();
+    const files = new Map();
+    let cwd;
+    let model;
+    forEachLine(path, (line) => {
+        if (!line.includes('"tool_use"') && !line.includes('"tool_result"') && cwd !== undefined)
+            return;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (!cwd && typeof e.cwd === "string")
+            cwd = e.cwd;
+        const content = e.message?.content;
+        if (!Array.isArray(content))
+            return;
+        if (e.type === "assistant") {
+            if (typeof e.message.model === "string")
+                model = e.message.model;
+            for (const b of content) {
+                if (b?.type === "tool_use" && b.name === "Read" && typeof b.input?.file_path === "string")
+                    pending.set(b.id, b.input.file_path);
+            }
+        }
+        else if (e.type === "user") {
+            for (const b of content) {
+                if (b?.type !== "tool_result")
+                    continue;
+                const file = pending.get(b.tool_use_id);
+                if (!file)
+                    continue;
+                pending.delete(b.tool_use_id);
+                const f = files.get(file) ?? { reads: 0, tokens: 0 };
+                f.reads++;
+                f.tokens += resultTokens(b.content);
+                files.set(file, f);
+            }
+        }
+    });
+    return { cwd, model, files };
+}
+export function repeatedReads(days = 30, paths, minSessions = 3) {
+    const since = Date.now() - days * 86_400_000;
+    const list = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
+    const byFile = new Map();
+    const projectSessions = new Map();
+    let reads = 0, readTokens = 0;
+    for (const p of list) {
+        const s = sessionReads(p);
+        const project = s.cwd ?? "?";
+        projectSessions.set(project, (projectSessions.get(project) ?? 0) + 1);
+        const price = pricingFor(s.model);
+        for (const [file, f] of s.files) {
+            reads += f.reads;
+            readTokens += f.tokens;
+            const agg = byFile.get(file) ?? { project, sessions: 0, reads: 0, tokens: 0, usd: 0, priced: false };
+            agg.sessions++;
+            agg.reads += f.reads;
+            agg.tokens += f.tokens;
+            if (price) {
+                agg.usd += (f.tokens * 1.25 * price.inputPerM) / 1e6;
+                agg.priced = true;
+            }
+            byFile.set(file, agg);
+        }
+    }
+    const files = [...byFile.entries()]
+        .filter(([, a]) => a.sessions >= minSessions)
+        .map(([path, a]) => {
+        const ps = projectSessions.get(a.project) ?? a.sessions;
+        return {
+            path,
+            project: a.project,
+            sessions: a.sessions,
+            projectSessions: ps,
+            reads: a.reads,
+            tokens: a.tokens,
+            usd: a.priced ? a.usd : undefined,
+            // In most of the project's sessions: a summary in CLAUDE.md is read anyway, so it replaces the reads.
+            advice: a.sessions / ps >= 0.5 ? "summarize" : "pack",
+        };
+    })
+        .sort((a, b) => b.tokens - a.tokens);
+    return { days, sessions: list.length, reads, readTokens, files };
+}
+export function renderReads(r, limit = 15, home = process.env.HOME ?? "") {
+    const short = (p) => (home && p.startsWith(home) ? "~" + p.slice(home.length) : p);
+    const out = ["FILES READ INTO SESSION AFTER SESSION", "═".repeat(56)];
+    out.push(`Claude Code, last ${r.days} days: ${r.reads.toLocaleString("en-US")} file reads across ${r.sessions} sessions, ~${formatTokens(r.readTokens)} tokens.`);
+    if (r.files.length === 0) {
+        out.push("No file was read in 3 or more sessions. Nothing to consolidate.");
+        return out.join("\n");
+    }
+    const repeated = r.files.reduce((s, f) => s + f.tokens, 0);
+    out.push(`${r.files.length} files were read in 3+ sessions: ~${formatTokens(repeated)} tokens of reads (${Math.round((repeated / Math.max(1, r.readTokens)) * 100)}% of all read tokens).`, "");
+    for (const f of r.files.slice(0, limit)) {
+        const usd = f.usd !== undefined ? `  ≥${formatUsd(f.usd)}` : "";
+        out.push(`  ${String(f.sessions).padStart(3)}/${f.projectSessions} sessions  ${String(f.reads).padStart(4)} reads  ~${formatTokens(f.tokens).padStart(6)}${usd.padEnd(10)}  ${short(f.path)}`);
+    }
+    if (r.files.length > limit)
+        out.push(`  … ${r.files.length - limit} more (--json for all)`);
+    const summarize = r.files.filter((f) => f.advice === "summarize").slice(0, 5);
+    out.push("");
+    if (summarize.length) {
+        out.push(`Read in most of their project's sessions: ${summarize.map((f) => short(f.path)).join(", ")}.`, "   → A few lines in that project's CLAUDE.md saying what sessions need from each file replace most of these reads (CLAUDE.md is read on every request, so keep it to what is needed each time).");
+    }
+    out.push("   → For the rest, read the part a task needs: `pack_context` (MCP) or `context-doctor pack <file> -q \"…\"` returns the relevant chunks with line ranges.");
+    out.push("   (≥ = floor of the cost: each read written to the prompt cache once; every later request of that session re-reads it too.)");
+    return out.join("\n");
+}

package/dist/tasks.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `context-doctor tasks`: what a unit of finished work costs, per project.
+ *
+ * Tokens and dollars per session say little on their own; a session that
+ * shipped five commits and one that shipped none can cost the same. This
+ * prices each recent Claude Code session from the usage its transcript
+ * records (input, cache writes at 1.25x, cache reads at 0.1x, output), counts
+ * the commits the session itself made (successful `git commit` calls in its
+ * shell tool, in whichever repository), and reports per project: sessions,
+ * cost, commits, cost per commit, and how much went to sessions that
+ * committed nothing.
+ *
+ * Counting from the transcript attributes each commit to exactly one session
+ * and finds commits in nested repositories; a time window over `git log`
+ * did neither (a parent folder's repo showed none, a busy repo's unrelated
+ * history showed hundreds). Commits made by hand are not counted, nor is
+ * subagent traffic.
+ */
+export interface SessionCost {
+    path: string;
+    cwd?: string;
+    model?: string;
+    start: number;
+    end: number;
+    usd: number;
+    requests: number;
+    /** Successful `git commit` calls the session made. */
+    commits: number;
+}
+export interface ProjectTasks {
+    project: string;
+    sessions: number;
+    usd: number;
+    commits: number;
+    /** Sessions in which the project's repository got no commit, and what they cost. */
+    idleSessions: number;
+    idleUsd: number;
+    usdPerCommit?: number;
+}
+export interface TasksReport {
+    days: number;
+    projects: ProjectTasks[];
+    usd: number;
+    commits: number;
+}
+/** One session's bill, priced as the prompt cache bills it, from the usage the transcript records. */
+export declare function sessionCost(path: string): SessionCost | undefined;
+/** `git commit` invocations in a shell command (not --amend, --dry-run or commit-tree). */
+export declare function commitCount(cmd: string): number;
+export declare function costPerTask(days?: number, paths?: string[]): TasksReport;
+export declare function renderTasks(r: TasksReport, limit?: number): string;

package/dist/tasks.js

@@ -0,0 +1,140 @@
+/**
+ * `context-doctor tasks`: what a unit of finished work costs, per project.
+ *
+ * Tokens and dollars per session say little on their own; a session that
+ * shipped five commits and one that shipped none can cost the same. This
+ * prices each recent Claude Code session from the usage its transcript
+ * records (input, cache writes at 1.25x, cache reads at 0.1x, output), counts
+ * the commits the session itself made (successful `git commit` calls in its
+ * shell tool, in whichever repository), and reports per project: sessions,
+ * cost, commits, cost per commit, and how much went to sessions that
+ * committed nothing.
+ *
+ * Counting from the transcript attributes each commit to exactly one session
+ * and finds commits in nested repositories; a time window over `git log`
+ * did neither (a parent folder's repo showed none, a busy repo's unrelated
+ * history showed hundreds). Commits made by hand are not counted, nor is
+ * subagent traffic.
+ */
+import { basename } from "node:path";
+import { forEachLine, listSessions } from "./session.js";
+import { formatUsd, pricingFor } from "./pricing.js";
+/** One session's bill, priced as the prompt cache bills it, from the usage the transcript records. */
+export function sessionCost(path) {
+    let cwd, model, lastId;
+    let start = Infinity, end = 0, usd = 0, requests = 0, commits = 0;
+    const commitCalls = new Map();
+    forEachLine(path, (line) => {
+        if (!line.includes('"usage"') && !line.includes('"tool_result"') && cwd !== undefined)
+            return;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!e || e.isSidechain)
+            return;
+        if (!cwd && typeof e.cwd === "string")
+            cwd = e.cwd;
+        const content = Array.isArray(e.message?.content) ? e.message.content : [];
+        if (e.type === "assistant") {
+            for (const b of content) {
+                const cmd = b?.type === "tool_use" && (b.name === "Bash" || b.name === "shell") ? String(b.input?.command ?? "") : "";
+                const n = commitCount(cmd);
+                if (n)
+                    commitCalls.set(b.id, n);
+            }
+        }
+        else if (e.type === "user") {
+            for (const b of content) {
+                if (b?.type !== "tool_result" || !commitCalls.has(b.tool_use_id))
+                    continue;
+                if (!b.is_error)
+                    commits += commitCalls.get(b.tool_use_id);
+                commitCalls.delete(b.tool_use_id);
+            }
+            return;
+        }
+        if (e.type !== "assistant" || !e.message?.usage || e.message.id === lastId)
+            return;
+        lastId = e.message.id;
+        const at = Date.parse(e.timestamp);
+        if (Number.isFinite(at)) {
+            start = Math.min(start, at);
+            end = Math.max(end, at);
+        }
+        if (typeof e.message.model === "string")
+            model = e.message.model;
+        const price = pricingFor(e.message.model ?? model);
+        if (!price)
+            return;
+        const u = e.message.usage;
+        const n = (k) => (typeof u[k] === "number" && u[k] > 0 ? u[k] : 0);
+        usd += (n("input_tokens") * price.inputPerM + n("cache_creation_input_tokens") * price.inputPerM * 1.25 +
+            n("cache_read_input_tokens") * price.cacheReadPerM + n("output_tokens") * price.outputPerM) / 1e6;
+        requests++;
+    });
+    if (!requests || !Number.isFinite(start))
+        return undefined;
+    return { path, cwd, model, start, end, usd, requests, commits };
+}
+/** `git commit` invocations in a shell command (not --amend, --dry-run or commit-tree). */
+export function commitCount(cmd) {
+    let n = 0;
+    for (const part of cmd.split(/&&|\|\||;|\n/)) {
+        if (/^\s*git(\s+-[cC]\s+\S+)*\s+commit(\s|$)/.test(part) && !/--amend|--dry-run/.test(part))
+            n++;
+    }
+    return n;
+}
+export function costPerTask(days = 30, paths) {
+    const since = Date.now() - days * 86_400_000;
+    const list = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
+    const byProject = new Map();
+    for (const p of list) {
+        const s = sessionCost(p);
+        if (!s || s.end < since)
+            continue;
+        const project = s.cwd ?? "?";
+        const agg = byProject.get(project) ?? { sessions: 0, usd: 0, commits: 0, idle: 0, idleUsd: 0 };
+        agg.sessions++;
+        agg.usd += s.usd;
+        agg.commits += s.commits;
+        if (s.commits === 0) {
+            agg.idle++;
+            agg.idleUsd += s.usd;
+        }
+        byProject.set(project, agg);
+    }
+    const projects = [...byProject.entries()]
+        .map(([project, a]) => ({
+        project,
+        sessions: a.sessions,
+        usd: a.usd,
+        commits: a.commits,
+        idleSessions: a.idle,
+        idleUsd: a.idleUsd,
+        usdPerCommit: a.commits ? a.usd / a.commits : undefined,
+    }))
+        .sort((a, b) => b.usd - a.usd);
+    return { days, projects, usd: projects.reduce((s, p) => s + p.usd, 0), commits: projects.reduce((s, p) => s + p.commits, 0) };
+}
+export function renderTasks(r, limit = 12) {
+    const out = ["COST PER TASK (the sessions' own commits as the unit of finished work)", "═".repeat(56)];
+    if (r.projects.length === 0)
+        return [...out, `No Claude Code sessions in the last ${r.days} days.`].join("\n");
+    out.push(`Last ${r.days} days at API list prices: ${formatUsd(r.usd)} across ${r.projects.reduce((s, p) => s + p.sessions, 0)} sessions, ${r.commits} commits.`, "");
+    out.push("  project                      sessions     cost  commits  per commit   no-commit sessions");
+    for (const p of r.projects.slice(0, limit)) {
+        const name = (p.project === "?" ? "?" : basename(p.project)).slice(0, 26).padEnd(26);
+        const per = p.usdPerCommit !== undefined ? formatUsd(p.usdPerCommit) : "—";
+        const idle = `${p.idleSessions} (${formatUsd(p.idleUsd)})`;
+        out.push(`  ${name} ${String(p.sessions).padStart(8)} ${formatUsd(p.usd).padStart(8)} ${String(p.commits).padStart(8)} ${per.padStart(11)}   ${idle}`);
+    }
+    if (r.projects.length > limit)
+        out.push(`  … ${r.projects.length - limit} more (--json for all)`);
+    out.push("", "Commits are the sessions' own successful `git commit` calls, in any repository; commits made by hand are not counted.", "Sessions with no commit are not waste by definition (research, reviews, deploys); a large share there is worth a look.");
+    return out.join("\n");
+}

package/dist/wrap.d.ts

@@ -7,9 +7,12 @@
  *   import { withContextDoctor } from "context-doctor";
  *   const client = withContextDoctor(new Anthropic());
  *
- * Works on the official Anthropic and OpenAI SDK clients (and anything shaped
- * like them): messages.create/stream, chat.completions.create/stream/parse and
- * responses.create/stream/parse, beta namespaces included. Each request goes
+ * Works on the official Anthropic, OpenAI and Google Gen AI SDK clients (and
+ * anything shaped like them): messages.create/stream,
+ * chat.completions.create/stream/parse, responses.create/stream/parse (beta
+ * namespaces included) and models.generateContent/generateContentStream.
+ * Gemini chat sessions (ai.chats) keep their history inside the SDK, out of
+ * reach; use generateContent with your own history to get autopilot. Each request goes
  * through the same AutoClearer the proxy uses: stale tool output is cleared
  * only when the prompt cache is cold, so a request never costs more.
  *

package/dist/wrap.js

@@ -7,9 +7,12 @@
  *   import { withContextDoctor } from "context-doctor";
  *   const client = withContextDoctor(new Anthropic());
  *
- * Works on the official Anthropic and OpenAI SDK clients (and anything shaped
- * like them): messages.create/stream, chat.completions.create/stream/parse and
- * responses.create/stream/parse, beta namespaces included. Each request goes
+ * Works on the official Anthropic, OpenAI and Google Gen AI SDK clients (and
+ * anything shaped like them): messages.create/stream,
+ * chat.completions.create/stream/parse, responses.create/stream/parse (beta
+ * namespaces included) and models.generateContent/generateContentStream.
+ * Gemini chat sessions (ai.chats) keep their history inside the SDK, out of
+ * reach; use generateContent with your own history to get autopilot. Each request goes
  * through the same AutoClearer the proxy uses: stale tool output is cleared
  * only when the prompt cache is cold, so a request never costs more.
  *
@@ -39,6 +42,9 @@ const WRAPPED = new Set([
     "responses.create",
     "responses.stream",
     "responses.parse",
+    // Google's @google/genai: ai.models.generateContent({ model, contents, config })
+    "models.generateContent",
+    "models.generateContentStream",
 ]);
 const PARENTS = new Set([...WRAPPED].flatMap((p) => p.split(".").slice(0, -1).map((_, i, a) => a.slice(0, i + 1).join("."))));
 const STATS = Symbol.for("context-doctor.stats");
@@ -53,15 +59,22 @@ export function withContextDoctor(client, options = {}) {
     const prepare = (method, params) => {
         if (!params || typeof params !== "object" || Array.isArray(params))
             return params;
+        // Copy the top level and deep-clone only the history, the one part
+        // autopilot rewrites: the rest can hold things that do not clone
+        // (an AbortSignal or callable tools in @google/genai's config).
+        stats.requests++;
+        const src = params;
+        const field = ["messages", "input", "contents"].find((k) => Array.isArray(src[k]));
+        if (!field)
+            return params;
         let body;
         try {
-            body = structuredClone(params);
+            body = { ...src, [field]: structuredClone(src[field]) };
         }
         catch {
-            return params; // something uncloneable (a function, a stream): leave the request alone
+            return params; // something uncloneable inside the history: leave the request alone
         }
         const result = clearer.apply(body);
-        stats.requests++;
         if (result.changed) {
             stats.changed++;
             stats.tokensRemoved += result.tokensRemoved;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Cut your Claude Code bill, measured on your own sessions: `npx context-doctor savings` shows what each lever saves, then the hook, autopilot and an earlier auto-compact window do it. Also Cursor, Codex, Claude Desktop and any Anthropic or OpenAI API app. MCP server and Claude Code plugin.",
   "keywords": [
     "agent",