context-doctor 0.19.0 → 0.20.0

package/README.md

@@ -1,15 +1,30 @@
 # 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)
+[![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)
 
-**See what's eating your LLM context window — and fix it.**
+**Keep every AI session's context lean, automatically, without ever making it more expensive.**
 
-Every long-running LLM conversation slowly fills up with junk: duplicated documents, 10k-token tool outputs nobody reads again, base64 blobs, stale history. You pay for those tokens on **every single call**, and model quality drops as the window fills.
+Long agent sessions fill up with tool output nobody reads again: file dumps, shell logs, search results, screenshots. You pay for all of it on every request, the model gets slower, and it drifts as the window fills. `context-doctor` measures that, and with **autopilot** it removes it from every Claude Code (and GPT API) request on your machine, only at moments when doing so costs nothing extra.
 
-`context-doctor` is a zero-config profiler + optimizer for LLM contexts. It works with **Claude, GPT, Gemini** message formats, and plugs into **Claude Desktop, ChatGPT (developer mode), Cursor, Claude Code** — any MCP-capable app — or runs standalone from the terminal.
+- **9.8% less input cost, no session worse.** Replaying 130 days of the author's real Claude Code use (43 sessions) through the shipped code: **3.8 billion input tokens not sent, $4,694 saved at API list price, about $1,080 a month**, and not one session more expensive. Up to 37.7% on a long session. [What it saves →](#what-it-saves)
+- **Counts Claude correctly.** Current Claude models pack 2.75 characters per token, not the 4 most tools assume; estimates built on 4 undercount Claude by about 40%. The ratios here were measured from the API's own counts, and `context-doctor accuracy` re-checks them on yours. [How →](#why-token-counts-are--and-where-they-are-exact)
+- **Works where you work:** Claude Code, Cursor, Codex, Claude Desktop, any Anthropic or OpenAI API app, VS Code, CI. macOS, Linux and Windows, Node 20+.
+- **Local and keyless.** No account, no telemetry, no API key. Your own login passes through untouched. MIT.
 
 Built and maintained by [gAI Ventures](https://gai.ventures).
 
+## Quick start
+
+```bash
+npm install -g context-doctor
+context-doctor install          # hooks, MCP server and skill in every AI app it finds
+context-doctor autopilot on     # every new Claude Code session keeps its context lean
+```
+
+Then start a new Claude Code session and work as usual. `context-doctor autopilot status` shows what it did; `context-doctor doctor` checks the whole setup. Everything is reversible: `context-doctor autopilot off`, `context-doctor uninstall`.
+
+Just want a look first? `npx context-doctor session` profiles your latest Claude Code or Codex session in place, no install.
+
 ```
 Where the tokens go
 ────────────────────────────────────────────────────────
@@ -26,35 +41,66 @@ Findings (4)
    → Truncate or summarize large tool outputs before they enter history.
 ```
 
-## Quick start (30 seconds)
+## What it saves
 
-**One command sets up everything** — detects Claude Desktop, Claude Code, and Cursor on your machine, wires in the MCP server, installs the Agent Skill, and registers the Claude Code every-prompt hook:
+Measured, not modelled: every Claude Code session on the author's machine from 18 May to 25 September 2026 (43 sessions, 130 days, mostly Opus 5 and Fable 5 with the 1M window) was replayed request by request through the shipped autopilot code, with the real timestamps, and priced the way the prompt cache bills it (cached reads 0.1x, writes 1.25x). Run it on your own history with `node scripts/replay-autopilot.mjs`.
 
-```bash
-npx context-doctor install
-```
+| | Without autopilot | With autopilot | Saved |
+|---|---|---|---|
+| Input tokens sent | 41.4 billion | 37.6 billion | **3.8 billion (9.2%)** |
+| Input cost at API list price | $48,962 | $44,268 | **$4,694 (9.8%)** |
+| Per 30 days | | | **~875 million tokens, ~$1,080** |
+| Sessions made more expensive | | | **0 of 43** |
 
-`install` configures every app it detects and does not stop at the first problem: a corrupt Claude Desktop config still gets you Claude Code and Cursor. It does not pretend either. Any target that failed is named with a ✗ line, the summary reads "Done with N problem(s)" instead of "Done.", and the **exit code is 1**, so dotfiles and onboarding scripts can react. A broken config file is never overwritten; fix it and re-run.
+How it spreads: the median session saves 1.9%, the best 37.7%. Short sessions barely change, because they rarely pile up 20k tokens of stale tool output before they end. Long sessions are where the money is: on this machine 94% of input cost came from requests above 200k tokens, and those are the requests autopilot makes smaller. Savings scale with how long your sessions run and how much they read, so a lighter user saves proportionally less, and never pays more.
 
-That single command is also all it takes to **set up context-doctor on anyone else's machine**. Prefer a global install, or want the unreleased `main`? Both work (Node 20+):
+On a Claude subscription you do not pay list price; the same tokens come out of your usage limit instead. Anthropic does not publish how limits weight cached tokens, so read the dollar column as the size of the effect, not as your bill. The token column holds either way, and every request that is 9% smaller is also faster to first token and further from auto-compaction.
 
-```bash
-npm install -g context-doctor && context-doctor install
-```
+What is not counted here: the proxy's full optimizer for your own API apps, the hook's guidance to the model, and fixes you make from `session` findings. Those save more on top, but they depend on what the model or you do with the advice, so they are not in this table.
+
+## What happens on each platform
+
+| Where you work | Automatic, every request | What you get on top |
+|---|---|---|
+| **Claude Code** (terminal, VS Code, JetBrains, desktop app's Code tab) | **Autopilot** clears stale tool output (cold cache only, never more expensive). **Hook** on every prompt warns the model with the real context size and its largest waste | Status bar context meter, `/context-doctor` skill, `session`, `watch`, `report`, dashboard |
+| **Cursor** (agent) | Cursor runs Claude Code's hooks, so the same every-prompt check fires inside Cursor | MCP tools, editor status bar extension, `cursor` profiler. With your own OpenAI key, autopilot too via a tokened tunnel ([how](#putting-the-proxy-on-a-public-url-cursor-with-your-own-openai-key-remote-apps)) |
+| **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 |
+| **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.
+
+## What's new
+
+- **0.20 Autopilot**: stale tool output cleared from every Claude Code request, only when the prompt cache is cold, so it cannot cost more (measured: 9.8% less input cost, ~$1,080 a month on the author's usage, no session worse); runs as a login service on macOS, Linux and Windows; now also for GPT via OpenAI's Chat Completions and Responses APIs.
+- **0.19 Measured Claude tokenizer**: estimates were 40% low for Claude; fixed from the API's own counts, with a per-model check in `accuracy`.
+- **0.18** `proxy --token` for putting the proxy on a public URL safely. **0.17** Claude Desktop: a `profile_context` the model can afford to call from chat, `.mcpb` bundle, standing preferences for web and mobile. **0.16** Codex. **0.15** Cursor.
+
+Full history with the measurements behind each change: [ROADMAP.md](./ROADMAP.md).
 
-Restart your apps, then just ask Claude: *"what's eating my context?"* (`npx context-doctor uninstall` reverses it.)
+## Setup details
+
+`install` configures every app it detects and does not stop at the first problem: a corrupt Claude Desktop config still gets you Claude Code and Cursor. It does not pretend either. Any target that failed is named with a ✗ line, the summary reads "Done with N problem(s)" instead of "Done.", and the **exit code is 1**, so dotfiles and onboarding scripts can react. A broken config file is never overwritten; fix it and re-run.
+
+`npx context-doctor install` works too, but autopilot needs the global install: a background service cannot point into npx's cache, which npm deletes at will.
 
 **No API keys, ever.** Everything is deterministic local code; when an LLM is needed (summarizing pruned history), the model already running in your app does it. The proxy forwards *your app's* credentials untouched — context-doctor itself holds nothing.
 
 ## What `install` actually does — and what happens in every session after
 
-One run of `npx context-doctor install` writes five things (each config edit makes a `.backup` first; `uninstall` reverses all of it):
+One run of `context-doctor install` writes these (each config edit makes a `.backup` first; `uninstall` reverses all of it):
 
 1. **Claude Desktop config** (`claude_desktop_config.json`) — registers the MCP server
 2. **Claude Code config** (`~/.claude.json`) — registers the MCP server
 3. **Cursor config** (`~/.cursor/mcp.json`) — registers the MCP server
 4. **Agent Skill** → `~/.claude/skills/context-doctor/` — context-hygiene playbook for Claude Code
-5. **Every-prompt hook** → `~/.claude/settings.json` — the per-query context check for Claude Code
+5. **Every-prompt hook** → `~/.claude/settings.json` — the per-query context check for Claude Code (Cursor runs it too)
+6. **Codex**, when present: MCP server in `~/.codex/config.toml`, the hook in `~/.codex/hooks.json`, the skill in `~/.codex/skills/`
+7. With `--statusline`: live context size, cache share and cost in Claude Code's status bar
+
+`context-doctor autopilot on` is separate and opt-in: it adds the background proxy service and one line (`env.ANTHROPIC_BASE_URL`) to `~/.claude/settings.json`, after the proxy has answered a health check.
 
 **In every chat afterward (Claude Desktop, Cursor):** when the conversation starts, the app launches the MCP server, which hands the model standing instructions that stay in force for the whole chat:
 
@@ -72,11 +118,12 @@ One run of `npx context-doctor install` writes five things (each config edit mak
 
 ## Do you need MCP? Only sometimes — all the ways to use context-doctor
 
-MCP is just one of six delivery mechanisms. It's only required when you want the AI **inside a chat app** to run the tools itself. Everything else works without it:
+MCP is just one of seven delivery mechanisms. It's only required when you want the AI **inside a chat app** to run the tools itself. Everything else works without it:
 
 | How you use it | MCP needed? | What it requires |
 |---|---|---|
 | **CLI** — `analyze`, `optimize`, `session` on files/transcripts | ❌ No | Nothing but `npx` — works in any terminal, scripts, CI |
+| **Autopilot** — every Claude Code session, and GPT API apps | ❌ No | `context-doctor autopilot on` (a login service + one line in `~/.claude/settings.json`) |
 | **Proxy** — always-on optimization of your API apps | ❌ No | `context-doctor proxy` + one env var in your app |
 | **Claude Code every-prompt hook** | ❌ No | Written by `install`; Claude Code invokes it directly |
 | **Agent Skill** — hygiene behavior in Claude Code / claude.ai | ❌ No | A markdown file; `install` places it (or upload to claude.ai) |
@@ -90,6 +137,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | Command | What it does |
 |---|---|
 | `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor/Codex, the Agent Skill, the every-prompt hook |
+| `context-doctor 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 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 |
@@ -112,14 +160,13 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 
 | Where you run LLMs | Mechanism | Guarantee |
 |---|---|---|
-| Your own apps/agents (API) | `context-doctor proxy` rewrites every request in flight | **Every call, automatic** |
+| Claude Code sessions, with autopilot on | The login-service proxy clears stale tool output from every request, only when the cache is cold | **Every request; never more expensive (measured)** |
+| Your own apps/agents (API) | `context-doctor proxy` rewrites every request in flight, or `proxy --autopilot` for the cache-safe mode | **Every call, automatic** |
 | Claude Code / Cowork sessions | `install` registers a **UserPromptSubmit hook**: every query measures the session; heavy sessions get injected hygiene guidance (silent when lean, rate-limited, never blocks a prompt) | **Every query checked** |
 | Claude Desktop chat / Cursor | **MCP server instructions** — standing hygiene directives injected into every conversation where the server is enabled, plus prescriptive tool triggers | **Every conversation carries the rules** |
-| claude.ai (web) / ChatGPT app | Upload `skills/context-doctor/SKILL.md` in the app's Skills settings for the same standing behavior | Manual one-time upload |
-
-Nothing runs in the background for the Claude apps — the hook, skill, MCP server, and its instructions are all delivered by the app itself at the right moment. The proxy is the only long-running piece, and only your API-calling apps need it.
+| claude.ai (web) / ChatGPT / phone apps | `context-doctor instructions --copy`, pasted once into the account's preferences (or upload `skills/context-doctor/SKILL.md` as a skill) | Every chat on that account carries the rules |
 
-Optional belt-and-braces for any chat app: add one line to your profile preferences — *"Practice context hygiene: summarize large content instead of re-quoting it, and use context-doctor's tools when conversations get heavy."*
+Without autopilot nothing runs in the background: the hook, skill, MCP server and its instructions are delivered by the apps themselves at the right moment. With autopilot, one small proxy runs as a login service (launchd / systemd user service / logon task) and is restarted by the service or by the next prompt's hook if it ever stops.
 
 Or use the CLI directly, no install needed:
 
@@ -150,6 +197,35 @@ npx context-doctor session --list    # browse sessions
 
 Parses the transcripts Claude Code writes locally and answers "where did my tokens go today?" — it will happily tell you that one giant skill load is 67% of your context.
 
+## Autopilot: every Claude Code session keeps its own context lean
+
+```bash
+context-doctor autopilot on        # once; survives reboots
+context-doctor autopilot status    # what it has done
+context-doctor autopilot pause     # instant passthrough, nothing restarts
+context-doctor autopilot off       # remove it
+```
+
+`autopilot on` runs the local proxy as a background service (launchd on macOS, a systemd user service on Linux, a logon task on Windows), waits until it answers, and only then points Claude Code at it through `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`. Every Claude Code session started afterwards, in the terminal, an IDE, or the desktop app's Code tab, sends its requests through it. Your login (subscription or API key) passes through untouched.
+
+**What it does to each request:** once old tool output adds up to 20k+ tokens (file reads, shell output, search and web results, screenshots inside them), it replaces that output with a one-line note, keeping the 3 most recent results. The tool call stays in the history, so the model can simply run it again if it needs the output. Your messages, its answers, answers you gave to its questions, subagent reports and MCP results are never touched.
+
+**Why it cannot make a session more expensive.** A prompt cache matches a byte-identical prefix, and changing old history re-bills everything after the change at the write rate (1.25x instead of 0.1x). So autopilot changes history only when the cache is cold anyway: after an idle gap longer than the cache lifetime the request itself declares (1 hour for Claude Code on a subscription, 5 minutes otherwise), when the whole prompt is re-written regardless. Once cleared, an output stays cleared on every later request, so the prefix is identical between clearings and the cache keeps hitting.
+
+**Measured before it shipped**, by replaying every Claude Code session on the author's machine (43 sessions, 130 days) request by request through the shipped code, priced as the cache bills it, with real timestamps: 3.8 billion input tokens not sent and $4,694 at list price, ~$1,080 a month ([details](#what-it-saves)). `scripts/replay-autopilot.mjs` does this on yours:
+
+| Policy | Input cost saved | Worst session |
+|---|---|---|
+| **Autopilot: clear only when the cache is cold (default)** | **9.8%** (9.2% of raw input tokens; best session 37.7%) | **0.00%, no session worse** |
+| Also clear on a warm cache when the saving "should" repay the rewrite | 9.9% | −0.13% (one session worse) |
+| The proxy's general strategies (dedupe, trim, strip-base64) | 6.7% | −13% (one session worse) |
+
+94% of input cost on that machine came from requests above 200k tokens, which is where the clearing lands. Smaller requests also mean later auto-compaction and a faster first token.
+
+**Never in the way:** anything it cannot parse is forwarded unchanged; only Anthropic `/v1/messages` requests are touched. It adds about 7 ms to a 2.9 MB (~1M token) request. If the proxy dies, the service restarts it within seconds, and the every-prompt hook checks it before each prompt and starts it if needed (measured: 0.6 s once, when it had to). `pause` turns it into a passthrough without restarting anything; `off` removes the setting before stopping the service, and sessions started while it was on need a restart.
+
+**What it cannot reach** (no process on your machine sends those requests): Claude Desktop's chat tab and claude.ai, which use the standing instructions and the `profile_context` sketch instead; Cursor's own models (Cursor's servers call the model; with your own OpenAI key, see the tunnel section below); and Codex signed in with ChatGPT, where the every-prompt hook still reports context size.
+
 ## Always-on: optimize every request automatically
 
 Run the proxy and every Anthropic/OpenAI API call your apps make gets optimized in flight — no code changes:

package/dist/autoclear.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Autopilot: clear stale tool output from agent requests in flight, without
+ * ever costing more than it saves.
+ *
+ * Why this and not the proxy's general strategies: replayed over 33 real
+ * Claude Code sessions with prompt-cache pricing, the general trim saved 6.7%
+ * overall but made one session 13% MORE expensive, because every change to
+ * history the cache already holds re-bills everything after it at the write
+ * rate. Most of the bill sits in long sessions (94% of input cost came from
+ * requests above 200k tokens), so the win is real, but only if each change
+ * pays for its cache rewrite.
+ *
+ * The rules, modelled on the microcompact logic Claude Code ships (and keeps
+ * switched off by a server flag), tightened for "never worse":
+ *
+ *  1. Only output of read-only, re-runnable tools is eligible (file reads,
+ *     shell, search, web fetch). Answers the user gave, subagent reports and
+ *     MCP results are never touched.
+ *  2. The most recent `keepRecent` tool results always stay.
+ *  3. Clearing happens in batches of at least `minClearTokens`, so each cache
+ *     rewrite buys a lot.
+ *  4. A cleared result stays cleared on every later request (ids are
+ *     remembered, across restarts), so the prefix is byte-stable between
+ *     batches and the cache keeps hitting.
+ *  5. By default a batch is taken ONLY when the cache is cold anyway (idle
+ *     longer than the request's own cache TTL), because the whole prompt is
+ *     re-written on that request regardless, so clearing costs nothing and
+ *     every later request is smaller. That makes it never-worse by
+ *     construction, and measured: replaying every Claude Code session on the
+ *     author's machine through this class, with real timestamps and cache
+ *     pricing, it saved 9.8% of cache-weighted input cost (9.2% of raw input
+ *     tokens, up to 37.7% in one long session) and made no session worse.
+ *     Clearing on a warm cache when the saving "should" repay the rewrite
+ *     (`paybackSafety` > 0) added 0.1% and made one session 0.13% worse: the
+ *     future is not knowable, so it is off unless asked for.
+ *
+ * The model sees a one-line note in place of the output and can simply re-run
+ * the tool; the file, command or URL is still in the tool call.
+ */
+/** Tools whose output can be regenerated by calling them again (read-only or re-runnable). */
+export declare const CLEARABLE_TOOLS: Set<string>;
+export interface AutoClearOptions {
+    /** Most recent tool results that always stay. Default 3. */
+    keepRecent?: number;
+    /** Smallest batch worth a cache rewrite. Default 20,000 tokens. */
+    minClearTokens?: number;
+    /**
+     * Warm-cache rule: clear only if the saving over the requests still to come
+     * repays the rewrite this many times over. Requests still to come are
+     * estimated as the number already made in this conversation. Default 0:
+     * warm clearing off, cold cache only (the never-worse setting).
+     */
+    paybackSafety?: number;
+    /** Where cleared ids persist so a restart does not un-clear (and re-bill) them. */
+    statePath?: string;
+}
+export interface AutoClearResult {
+    changed: boolean;
+    /** Results cleared by this request's new batch (0 when none was taken). */
+    newlyCleared: number;
+    /** Tokens removed from this request, old batches included. */
+    tokensRemoved: number;
+    cold: boolean;
+    reason: string;
+    /** Index of the first message rewritten on this request (the cache breaks from here), or -1. */
+    firstChanged: number;
+}
+interface Found {
+    /** Index of the message / input item that holds the result (cache breaks from here). */
+    unit: number;
+    id: string;
+    tokens: number;
+    content: unknown;
+    set: (note: string) => void;
+}
+/**
+ * One request, whatever its API: the units that make up history, tool names
+ * by call id, the tool results in order, and the cache lifetime to assume.
+ * Anthropic Messages (Claude Code, Anthropic SDKs), OpenAI Chat Completions
+ * (role "tool" messages) and OpenAI Responses (function_call_output items,
+ * as Codex with an API key sends).
+ */
+interface View {
+    format: "anthropic" | "openai-chat" | "openai-responses";
+    units: Array<Record<string, unknown>>;
+    toolName: Map<string, string>;
+    results: Array<Omit<Found, "tokens">>;
+    firstUser: unknown;
+    firstToolId: string;
+    ttlMs: number;
+}
+export declare function clearedNote(tokens: number): string;
+/**
+ * How long the provider may keep this prompt cached, taking the LONGER
+ * possibility when unsure: calling a warm cache cold would pay a rewrite,
+ * calling a cold one warm only delays a free clearing.
+ *  - Anthropic: the request's own cache_control, "1h" or the 5-minute default.
+ *  - OpenAI: caches live up to an hour (in-memory retention), or 24 hours when
+ *    the request sets prompt_cache_retention "24h".
+ */
+export declare function requestTtlMs(body: Record<string, unknown>): number;
+export declare function viewOf(body: Record<string, unknown>): View | undefined;
+export declare class AutoClearer {
+    private cleared;
+    /** Tool results never change once sent, so their size is computed once per id. */
+    private sizes;
+    private convs;
+    private opts;
+    private dirty;
+    constructor(options?: AutoClearOptions);
+    /**
+     * 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;
+    /**
+     * 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
+     * the cleared tokens at the read rate (0.1x) on every later request.
+     * Later requests are estimated as the number made so far (a conversation's
+     * age is the best predictor of how long it keeps going), and the saving must
+     * cover the rewrite `paybackSafety` times over.
+     */
+    private shouldClearWarm;
+    private load;
+    private save;
+}
+export {};

package/dist/autoclear.js

@@ -0,0 +1,295 @@
+/**
+ * Autopilot: clear stale tool output from agent requests in flight, without
+ * ever costing more than it saves.
+ *
+ * Why this and not the proxy's general strategies: replayed over 33 real
+ * Claude Code sessions with prompt-cache pricing, the general trim saved 6.7%
+ * overall but made one session 13% MORE expensive, because every change to
+ * history the cache already holds re-bills everything after it at the write
+ * rate. Most of the bill sits in long sessions (94% of input cost came from
+ * requests above 200k tokens), so the win is real, but only if each change
+ * pays for its cache rewrite.
+ *
+ * The rules, modelled on the microcompact logic Claude Code ships (and keeps
+ * switched off by a server flag), tightened for "never worse":
+ *
+ *  1. Only output of read-only, re-runnable tools is eligible (file reads,
+ *     shell, search, web fetch). Answers the user gave, subagent reports and
+ *     MCP results are never touched.
+ *  2. The most recent `keepRecent` tool results always stay.
+ *  3. Clearing happens in batches of at least `minClearTokens`, so each cache
+ *     rewrite buys a lot.
+ *  4. A cleared result stays cleared on every later request (ids are
+ *     remembered, across restarts), so the prefix is byte-stable between
+ *     batches and the cache keeps hitting.
+ *  5. By default a batch is taken ONLY when the cache is cold anyway (idle
+ *     longer than the request's own cache TTL), because the whole prompt is
+ *     re-written on that request regardless, so clearing costs nothing and
+ *     every later request is smaller. That makes it never-worse by
+ *     construction, and measured: replaying every Claude Code session on the
+ *     author's machine through this class, with real timestamps and cache
+ *     pricing, it saved 9.8% of cache-weighted input cost (9.2% of raw input
+ *     tokens, up to 37.7% in one long session) and made no session worse.
+ *     Clearing on a warm cache when the saving "should" repay the rewrite
+ *     (`paybackSafety` > 0) added 0.1% and made one session 0.13% worse: the
+ *     future is not knowable, so it is off unless asked for.
+ *
+ * The model sees a one-line note in place of the output and can simply re-run
+ * the tool; the file, command or URL is still in the tool call.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { estimateTokens } from "./tokens.js";
+/** Tools whose output can be regenerated by calling them again (read-only or re-runnable). */
+export const CLEARABLE_TOOLS = new Set([
+    // Claude Code
+    "Read", "Bash", "BashOutput", "Grep", "Glob", "LS", "WebFetch", "WebSearch", "NotebookRead",
+    // Codex and other OpenAI-API agents
+    "shell", "exec_command", "local_shell", "read_file", "list_dir", "grep_search", "file_search", "web_search",
+    // Cursor's agent
+    "Shell", "ReadFile", "rg", "run_terminal_cmd", "codebase_search",
+]);
+/** Tokens billed for one image inside a tool result (a full-size screenshot is ~1.6k on Claude). */
+const IMAGE_TOKENS = 1600;
+const HOUR = 3_600_000;
+export function clearedNote(tokens) {
+    return `[context-doctor: old tool output cleared to keep context lean (~${tokens} tokens). Run the tool again if you need it.]`;
+}
+function resultTokens(content, model) {
+    if (typeof content === "string")
+        return estimateTokens(content, model);
+    if (!Array.isArray(content))
+        return estimateTokens(JSON.stringify(content ?? ""), model);
+    let n = 0;
+    for (const part of content) {
+        if (part?.type === "image" || part?.type === "image_url" || part?.type === "input_image")
+            n += IMAGE_TOKENS;
+        else if (typeof part?.text === "string")
+            n += estimateTokens(part.text, model);
+        else
+            n += estimateTokens(JSON.stringify(part ?? ""), model);
+    }
+    return n;
+}
+/**
+ * How long the provider may keep this prompt cached, taking the LONGER
+ * possibility when unsure: calling a warm cache cold would pay a rewrite,
+ * calling a cold one warm only delays a free clearing.
+ *  - Anthropic: the request's own cache_control, "1h" or the 5-minute default.
+ *  - OpenAI: caches live up to an hour (in-memory retention), or 24 hours when
+ *    the request sets prompt_cache_retention "24h".
+ */
+export function requestTtlMs(body) {
+    const openai = Array.isArray(body.input) || (Array.isArray(body.messages) && isOpenAIChat(body.messages));
+    if (openai)
+        return body.prompt_cache_retention === "24h" ? 24 * HOUR : HOUR;
+    const json = JSON.stringify(body.system ?? "") + JSON.stringify(body.tools ?? "") + JSON.stringify(body.messages?.slice(-3) ?? "");
+    return /"ttl"\s*:\s*"1h"/.test(json) ? HOUR : 300_000;
+}
+function isOpenAIChat(messages) {
+    return messages.some((m) => m?.role === "tool" || (m?.role === "assistant" && Array.isArray(m.tool_calls)) || m?.role === "system" || m?.role === "developer");
+}
+export function viewOf(body) {
+    const toolName = new Map();
+    const results = [];
+    let firstToolId = "";
+    if (Array.isArray(body.input)) {
+        const units = body.input;
+        units.forEach((it, i) => {
+            const t = it?.type;
+            if ((t === "function_call" || t === "custom_tool_call" || t === "local_shell_call") && typeof it.call_id === "string") {
+                toolName.set(it.call_id, t === "local_shell_call" ? "shell" : String(it.name ?? ""));
+                firstToolId ||= it.call_id;
+            }
+            else if ((t === "function_call_output" || t === "custom_tool_call_output" || t === "local_shell_call_output") && typeof it.call_id === "string") {
+                results.push({ unit: i, id: it.call_id, content: it.output, set: (note) => { units[i] = { ...it, output: note }; } });
+            }
+        });
+        const firstUser = units.find((u) => u?.role === "user")?.content;
+        return { format: "openai-responses", units, toolName, results, firstUser, firstToolId, ttlMs: requestTtlMs(body) };
+    }
+    const messages = body.messages;
+    if (!Array.isArray(messages) || messages.length === 0)
+        return undefined;
+    const firstUser = messages.find((m) => m?.role === "user")?.content;
+    if (isOpenAIChat(messages)) {
+        messages.forEach((m, i) => {
+            if (m?.role === "assistant" && Array.isArray(m.tool_calls)) {
+                for (const c of m.tool_calls) {
+                    if (typeof c?.id !== "string")
+                        continue;
+                    toolName.set(c.id, String(c.function?.name ?? c.name ?? ""));
+                    firstToolId ||= c.id;
+                }
+            }
+            else if (m?.role === "tool" && typeof m.tool_call_id === "string") {
+                results.push({ unit: i, id: m.tool_call_id, content: m.content, set: (note) => { messages[i] = { ...m, content: note }; } });
+            }
+        });
+        return { format: "openai-chat", units: messages, toolName, results, firstUser, firstToolId, ttlMs: requestTtlMs(body) };
+    }
+    messages.forEach((m, i) => {
+        if (!Array.isArray(m?.content))
+            return;
+        const blocks = m.content;
+        blocks.forEach((b, j) => {
+            if (m.role === "assistant" && b?.type === "tool_use" && typeof b.id === "string") {
+                toolName.set(b.id, String(b.name ?? ""));
+                firstToolId ||= b.id;
+            }
+            else if (m.role === "user" && b?.type === "tool_result" && typeof b.tool_use_id === "string") {
+                results.push({ unit: i, id: b.tool_use_id, content: b.content, set: (note) => { blocks[j] = { ...b, content: note }; } });
+            }
+        });
+    });
+    return { format: "anthropic", units: messages, toolName, results, firstUser, firstToolId, ttlMs: requestTtlMs(body) };
+}
+/**
+ * A conversation's identity: its first user message plus its first tool call
+ * id. The message alone can repeat across sessions (the same project context
+ * opens every session in a folder); tool call ids are unique per session.
+ * The model is left out on purpose: switching models mid-session keeps the
+ * conversation (and the cleared set) but not the cache, which the TTL check
+ * cannot see, so a model switch is treated as warm, the safe direction.
+ */
+function conversationKey(view) {
+    return createHash("sha1").update(JSON.stringify(view.firstUser ?? "").slice(0, 4000)).update(view.firstToolId).digest("hex");
+}
+export class AutoClearer {
+    cleared = new Map();
+    /** Tool results never change once sent, so their size is computed once per id. */
+    sizes = new Map();
+    convs = new Map();
+    opts;
+    dirty = false;
+    constructor(options = {}) {
+        this.opts = {
+            keepRecent: options.keepRecent ?? 3,
+            minClearTokens: options.minClearTokens ?? 20_000,
+            paybackSafety: options.paybackSafety ?? 0,
+            statePath: options.statePath,
+        };
+        this.load();
+    }
+    /**
+     * 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()) {
+        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;
+            const key = conversationKey(view);
+            const conv = this.convs.get(key);
+            const cold = !conv || now - conv.last > view.ttlMs;
+            this.convs.set(key, { last: now, requests: (conv?.requests ?? 0) + 1 });
+            if (this.convs.size > 2000)
+                this.convs.delete(this.convs.keys().next().value);
+            const results = view.results.map((r) => {
+                let tokens = this.sizes.get(r.id);
+                if (tokens === undefined) {
+                    tokens = resultTokens(r.content, model);
+                    this.sizes.set(r.id, tokens);
+                    if (this.sizes.size > 100_000)
+                        this.sizes.delete(this.sizes.keys().next().value);
+                }
+                return { ...r, tokens };
+            });
+            const eligible = results.slice(0, Math.max(0, results.length - this.opts.keepRecent))
+                .filter((r) => CLEARABLE_TOOLS.has(view.toolName.get(r.id) ?? ""));
+            const pending = eligible.filter((r) => !this.cleared.has(r.id) && r.tokens > 200);
+            const pendingTokens = pending.reduce((n, r) => n + r.tokens, 0);
+            let reason = "nothing to clear";
+            let taken = [];
+            if (pendingTokens >= this.opts.minClearTokens) {
+                if (cold) {
+                    taken = pending;
+                    reason = "cache cold: cleared for free";
+                }
+                else if (this.opts.paybackSafety > 0 && this.shouldClearWarm(view.units, pending, pendingTokens, model, (conv?.requests ?? 0) + 1)) {
+                    taken = pending;
+                    reason = "cache warm: saving repays the rewrite";
+                }
+                else {
+                    reason = "cache warm: waiting, rewrite would not pay back yet";
+                }
+            }
+            else if (pendingTokens > 0) {
+                reason = `waiting for a ${Math.round(this.opts.minClearTokens / 1000)}k batch`;
+            }
+            for (const r of taken)
+                this.cleared.set(r.id, r.tokens);
+            if (taken.length)
+                this.dirty = true;
+            // Apply every clearing ever decided for this conversation, so the
+            // prefix is identical to what was sent last time.
+            let removed = 0;
+            let changed = false;
+            let firstChanged = -1;
+            for (const r of results) {
+                if (!this.cleared.has(r.id))
+                    continue;
+                const note = clearedNote(this.cleared.get(r.id));
+                if (r.content === note)
+                    continue;
+                removed += Math.max(0, r.tokens - estimateTokens(note, model));
+                r.set(note);
+                changed = true;
+                if (firstChanged === -1 || r.unit < firstChanged)
+                    firstChanged = r.unit;
+            }
+            this.save();
+            return { changed, newlyCleared: taken.length, tokensRemoved: removed, cold, reason, firstChanged };
+        }
+        catch {
+            return none("error: request forwarded unchanged");
+        }
+    }
+    /**
+     * 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
+     * the cleared tokens at the read rate (0.1x) on every later request.
+     * Later requests are estimated as the number made so far (a conversation's
+     * age is the best predictor of how long it keeps going), and the saving must
+     * cover the rewrite `paybackSafety` times over.
+     */
+    shouldClearWarm(messages, pending, pendingTokens, model, requestsSoFar) {
+        const first = Math.min(...pending.map((r) => r.unit));
+        let suffix = -pendingTokens;
+        for (let i = first; i < messages.length; i++)
+            suffix += estimateTokens(JSON.stringify(messages[i]), model);
+        const rewriteCost = 1.15 * Math.max(0, suffix);
+        const saving = 0.1 * pendingTokens * requestsSoFar;
+        return saving >= this.opts.paybackSafety * rewriteCost;
+    }
+    load() {
+        if (!this.opts.statePath || !existsSync(this.opts.statePath))
+            return;
+        try {
+            const data = JSON.parse(readFileSync(this.opts.statePath, "utf8"));
+            for (const [id, tokens] of data.cleared ?? [])
+                this.cleared.set(id, tokens);
+        }
+        catch {
+            /* a corrupt state file only means results may be re-cleared once */
+        }
+    }
+    save() {
+        if (!this.dirty || !this.opts.statePath)
+            return;
+        this.dirty = false;
+        try {
+            // Newest 50k ids: far more than any live session holds.
+            const entries = [...this.cleared.entries()].slice(-50_000);
+            mkdirSync(dirname(this.opts.statePath), { recursive: true });
+            writeFileSync(this.opts.statePath, JSON.stringify({ cleared: entries }));
+        }
+        catch {
+            /* persistence is best effort */
+        }
+    }
+}