context-doctor 0.14.3 → 0.17.0

package/README.md

@@ -89,7 +89,8 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 
 | Command | What it does |
 |---|---|
-| `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor, the Agent Skill, the every-prompt hook |
+| `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor/Codex, the Agent Skill, the every-prompt hook |
+| `context-doctor instructions [--copy]` | The ~90-token standing rules 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 |
 | `context-doctor session [file]` | Profile a Claude Code session: live context, findings, **measured tokens and prompt-cache economics**, **where the wall clock went** per tool, and **what its subagents cost** (their own windows, your bill; never in the parent's profile). Also reads ChatGPT data exports (`conversations.json`) |
@@ -182,15 +183,29 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 
 ## Use with the Claude & ChatGPT apps
 
-`context-doctor` ships an MCP server, so the AI itself can profile and slim context on demand.
+`context-doctor` ships an MCP server, so the AI itself can profile and slim context on demand. Before the setup table, the honest question: **on which surfaces does it act by itself, and on which does it only nudge?** MCP gives a server no way to see the conversation or intercept a turn; only a hook or a place in the data path can do that.
+
+| Surface | Runs by itself | What that means |
+|---|---|---|
+| **Claude Code** | Yes: hook on every prompt, status line on every refresh | Past ~80k tokens the model receives hygiene guidance naming the largest waste; compaction is offered. Measured: 115 automatic checks, 48 warnings, across 32 sessions on one machine |
+| **Cursor** | **Yes**, since 0.15: Cursor loads Claude Code's hook config (`~/.claude/settings.json`) and runs the same hook on every agent prompt, passing its own transcript. Output is accepted through Cursor's Claude-compat layer | Same guidance as Claude Code, inside Cursor's agent, for everyone who ran `install`. Before 0.15 the hook fired but could not read Cursor's transcript format, so it said nothing |
+| **API traffic through the proxy** | Yes: every request rewritten in flight | Fewer tokens, guaranteed, model not consulted |
+| **Claude Desktop** | The standing instruction in every chat (we confirmed in the app bundle that Desktop's `LocalMcpServerManager` reads it), a one-click `context_checkup` prompt, and since 0.17 a `profile_context` the model can actually afford to call from chat | Until 0.17 the tool wanted the whole conversation as its argument, so calling it from chat meant re-typing 50k tokens; nobody did, and Desktop's log showed zero calls in a month. Now the model passes a ~100-token **sketch** (turn count, the large or repeated blocks) and gets a sized estimate, findings and the fix to apply. Still a nudge, not a hook: Desktop chat has no hook API and no transcript on disk |
+| **Codex (OpenAI): ChatGPT.app's Codex tab, the Codex IDE extension, the `codex` CLI** | **Yes**, since 0.16: `install` writes the hook to `~/.codex/hooks.json`, the MCP server to `~/.codex/config.toml`, and the skill to `~/.codex/skills/`. Codex uses Claude Code's hook contract almost verbatim and passes its own rollout transcript, which carries the API's real usage figures | Same guidance as Claude Code, from measured tokens. One extra step, Codex's rule not ours: a new hook runs only after you trust it once (type `/hooks` in Codex). `session` and `session --list` read Codex rollouts too |
+| **ChatGPT chat UI** | No | No MCP, no hooks, no data path in the chat product itself. Use Codex, or a developer-mode connector at a URL you host |
+
+So "every chat inherently better" is true for Claude Code, Cursor, Codex and the proxy; for Claude Desktop it is "the rules ride in every chat and the checkup is one cheap tool call away"; and not a claim we make for the ChatGPT chat UI.
+
+**Where there is no hook and no MCP at all** (claude.ai on the web, the Claude and ChatGPT phone apps, plain ChatGPT): the app's per-account preferences are read on every turn, which is the closest those surfaces have to a hook. `context-doctor instructions --copy` puts the ~90-token rules on your clipboard and tells you where to paste them (claude.ai Settings > Profile; ChatGPT Settings > Personalization > Custom instructions).
 
 **Do you need to configure anything by hand? Usually no:**
 
 | App | Setup |
 |---|---|
-| Claude Desktop | `npx context-doctor install` writes the config — just restart the app |
+| Claude Desktop | `npx context-doctor install` writes the config — just restart the app. Or one click: download `context-doctor-<version>.mcpb` from the [latest release](https://github.com/KushalP1/context-doctor/releases) and open it (Settings > Extensions). The bundle runs on Desktop's own Node, no npm needed |
 | Claude Code | Same command — MCP + skill + every-prompt hook, all automatic |
-| Cursor | Same command — writes `~/.cursor/mcp.json` |
+| Cursor | Same command — writes `~/.cursor/mcp.json`; the every-prompt hook is picked up from Claude Code's config, which Cursor reads |
+| Codex (OpenAI) | Same command — `~/.codex/config.toml`, `~/.codex/hooks.json`, `~/.codex/skills/`. Then, once, `/hooks` in Codex to trust the hook |
 | ChatGPT (developer mode) | **Manual + a reachable URL** — ChatGPT connects to servers over the internet, never local commands. Run `context-doctor-mcp --http` on a host/tunnel, then add the URL as a connector. Normal ChatGPT (no dev mode) has no MCP — use the CLI |
 
 For any other MCP client, the server entry is:
@@ -208,10 +223,14 @@ For any other MCP client, the server entry is:
 
 ### How it works in Claude Desktop, step by step
 
-1. Run `npx context-doctor install` (writes the config above for you) and restart Claude Desktop.
-2. From then on, **every conversation automatically carries context-doctor's standing instructions** — the MCP server hands Claude hygiene rules on connect: summarize big pastes instead of re-quoting them, offer profiling when the chat gets long, never inline base64.
-3. Chat normally. When a conversation grows heavy, Claude proactively offers: *"this chat is getting large — want me to profile it?"* — or you ask *"what's eating my context?"* and it calls `profile_context` and shows the token/cost breakdown.
-4. Say *"optimize it"* and Claude applies the safe fixes; if you agree to pruning old history, **Claude itself writes the replacement summary** (that's the no-API-key summarization).
+1. Run `npx context-doctor install` (writes the config above for you) and restart Claude Desktop. Or open the `.mcpb` from the latest release: same server, no npm, installs as an Extension.
+2. From then on, **every conversation carries context-doctor's standing instructions**. The MCP server hands them to Desktop on connect and Desktop puts them in front of Claude: summarize big pastes instead of re-quoting them, refer to earlier content by name, never inline base64, and past ~30 turns or on any question about tokens, cost, speed or limits, call `profile_context` before answering.
+3. That call is cheap on purpose. Claude cannot export a Desktop chat, so it passes a **sketch**: how many turns, which blocks are large, repeated, stale or images, with one size hint each (~100 tokens). The server sizes it (±30%, and it says so), prices the per-turn re-read (on a subscription that is what spends your usage limit), and returns ranked findings with the action for each: "summarize *the nginx config* into the points still needed", "refer to *test output* by name", "offer a 300-token handoff summary for a fresh chat". The reply ends with an instruction to apply the top one, not just suggest it.
+4. One click instead of asking: the `context_checkup` prompt in the **+** menu sends that request for you.
+5. Say *"optimize it"* on an exported conversation and Claude applies the safe fixes; if you agree to pruning old history, **Claude itself writes the replacement summary** (that's the no-API-key summarization).
+6. For the same rules on your phone and on claude.ai, where no MCP server runs: `context-doctor instructions --copy`, then paste into Settings > Profile > personal preferences.
+
+What this does not do: read the chat behind Claude's back or trim it for you. Desktop chat has no hook API and no transcript on disk (checked in the app bundle, v2.2553). The model does the trimming, when the rules and the checkup tell it to.
 
 ### How it works in ChatGPT, step by step (honest version)
 
@@ -223,15 +242,15 @@ ChatGPT's MCP support differs fundamentally from Claude Desktop's: **it never sp
 
 Security note for step 2: the HTTP endpoint is unauthenticated — put it behind your tunnel's auth or a reverse proxy if it stays up long-term.
 
-### claude.ai on the web
+### claude.ai on the web and the phone apps
 
-Your local MCP server can't reach the website, but the behavior can: upload `skills/context-doctor/SKILL.md` under Settings → Capabilities → Skills, and web conversations gain the same standing context-hygiene habits (summarize-don't-requote, offer compaction when heavy).
+Your local MCP server can't reach the website, but the behavior can. Two options: `context-doctor instructions --copy` and paste into Settings > Profile > personal preferences (applies everywhere you are signed in, phone included), or upload `skills/context-doctor/SKILL.md` under Settings → Capabilities → Skills. Either way web and mobile conversations gain the same standing habits: summarize, don't re-quote, offer a handoff when heavy.
 
 ### MCP tools
 
 | Tool | What it does |
 |---|---|
-| `profile_context` | Token breakdown by category, largest messages, findings with estimated savings |
+| `profile_context` | Token breakdown by category, largest messages, findings with estimated savings. Takes either `conversation` (full JSON or text) or `sketch` (turns + large/repeated blocks, for chat apps) |
 | `optimize_context` | Rewrites the conversation: dedupe, trim stale tool results, strip base64, optional history pruning |
 | `context_best_practices` | Curated checklist, optionally specialized for Anthropic / OpenAI |
 
@@ -367,7 +386,7 @@ Everything the optimizer does is inspectable: it prints exactly which messages c
 
 ## The Agent Skill
 
-`skills/context-doctor/SKILL.md` (installed by `npx context-doctor install`) teaches Claude to practice context hygiene proactively: summarize big tool results after consuming them, never re-paste duplicated content, keep stable content cache-friendly, and offer compaction when a session gets heavy — so sessions get inherently leaner without you asking.
+`skills/context-doctor/SKILL.md` (installed by `npx context-doctor install`) teaches Claude to practice context hygiene proactively: summarize big tool results after consuming them, never re-paste duplicated content, keep stable content cache-friendly, and offer compaction when a session gets heavy. In Claude Code and Cursor the every-prompt hook enforces the heavy-session part; the skill covers the habits in between.
 
 ## Measuring the impact: `context-doctor report`
 
@@ -467,9 +486,10 @@ Contributions welcome — this project is small on purpose. Open an issue before
 
 ```bash
 npm version patch        # or minor/major — bumps package.json + git tag
-npm test                 # 14 tests must pass; CI runs the same on 3 OSes
+npm test                 # 131 tests must pass; CI runs the same on 3 OSes x Node 20/22/24
 npm publish              # prompts for the npm 2FA code
 git push --follow-tags
+npm run build:mcpb       # context-doctor-<version>.mcpb for Claude Desktop; attach it to the GitHub release
 ```
 
 **What the npm download number measures.** `install` writes `npx -y context-doctor-mcp` into MCP configs, and npx re-fetches the tarball whenever a new version exists. So every release is downloaded once by every active install within about a day, and the daily count is almost entirely those refreshes: on this package, release days run ~170 downloads and non-release days ~27. Read it as "size of the active installed base × number of releases", not as new users — a quiet week with no releases will look like a decline while nothing has changed. Two corollaries: the release-day figure is a live count of machines running context-doctor, and a broken release reaches all of them automatically, which is why `prepublishOnly` runs the full test suite. npm's stats also lag by several days and occasionally record a day as zero; a zero on a release day is a gap in their pipeline, not in usage.

package/dist/cli.js

@@ -20,6 +20,7 @@ import { runInstall, runUninstall } from "./install.js";
 import { listSessions, parseSessionFile } from "./session.js";
 import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
+import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
 import { measureAccuracy, renderAccuracy } from "./accuracy.js";
@@ -46,6 +47,8 @@ Usage:
   context-doctor install                        Wire the MCP server + skill into Claude Desktop,
                                                 Claude Code, and Cursor automatically
   context-doctor uninstall                      Undo install
+  context-doctor instructions [--copy]          Standing context rules to paste into claude.ai or
+                                                ChatGPT preferences (works on web and mobile too)
   context-doctor session [file]                 Profile a Claude Code session transcript or a
                                                 ChatGPT export (default: most recent; --list to browse)
   context-doctor cursor [--list]                Profile a Cursor chat from its local history
@@ -184,6 +187,9 @@ function parseArgs(argv) {
             case "--dry-run":
                 args.dryRun = true;
                 break;
+            case "--copy":
+                args.copy = true;
+                break;
             case "--allow-dirty":
                 args.allowDirty = true;
                 break;
@@ -431,6 +437,10 @@ function main() {
             process.exitCode = 1;
         return;
     }
+    if (args.command === "instructions") {
+        console.log(renderPreferences(args.copy ? copyToClipboard(CHAT_PREFERENCES) : undefined));
+        return;
+    }
     if (args.command === "uninstall") {
         runUninstall();
         return;

package/dist/doctor.js

@@ -135,6 +135,35 @@ export async function runDoctor() {
     else {
         checks.push({ label: "Every-prompt hook", status: "skip", detail: "Claude Code not detected" });
     }
+    // Codex (OpenAI): MCP table in config.toml, hook in hooks.json, skill.
+    const codexHome = join(homedir(), ".codex");
+    if (existsSync(codexHome)) {
+        const toml = existsSync(join(codexHome, "config.toml")) ? readFileSync(join(codexHome, "config.toml"), "utf8") : "";
+        checks.push(toml.includes("[mcp_servers.context-doctor]")
+            ? { label: "Codex MCP", status: "ok", detail: "wired in ~/.codex/config.toml" }
+            : { label: "Codex MCP", status: "fail", detail: "Codex detected but not wired — run: context-doctor install" });
+        try {
+            const hooksPath = join(codexHome, "hooks.json");
+            const hooks = existsSync(hooksPath) ? JSON.parse(readFileSync(hooksPath, "utf8")) : {};
+            const entries = hooks.hooks?.UserPromptSubmit ?? [];
+            const ours = entries.map((e) => e.hooks?.[0]?.command ?? "").find((c) => /context-doctor|cli\.js"?\s+hook/.test(c));
+            if (!ours) {
+                checks.push({ label: "Codex hook", status: "fail", detail: "not registered — run: context-doctor install" });
+            }
+            else {
+                const missing = hookBinaryMissing(ours);
+                checks.push(missing
+                    ? { label: "Codex hook", status: "fail", detail: `registered, but ${missing} no longer exists — re-run: context-doctor install` }
+                    : { label: "Codex hook", status: "ok", detail: "registered in ~/.codex/hooks.json (Codex must trust it once: /hooks)" });
+            }
+        }
+        catch (e) {
+            checks.push({ label: "Codex hook", status: "fail", detail: `~/.codex/hooks.json unreadable (${e.message})` });
+        }
+    }
+    else {
+        checks.push({ label: "Codex", status: "skip", detail: "not detected (ChatGPT's Codex agent, IDE extension or CLI)" });
+    }
     // Status line (opt-in, so absence is a note, not a failure)
     if (existsSync(settingsPath)) {
         try {

package/dist/index.d.ts

@@ -18,3 +18,5 @@ export type { ModelPricing } from "./pricing.js";
 export { estimateTokens, contextWindowFor, providerFor, formatTokens } from "./tokens.js";
 export type { Provider } from "./tokens.js";
 export { renderStatusLine, tailUsage } from "./statusline.js";
+export * from "./sketch.js";
+export * from "./preferences.js";

package/dist/index.js

@@ -13,3 +13,5 @@ export { estimateTokens, contextWindowFor, providerFor, formatTokens } from "./t
 // Status-line building blocks, for editor integrations (the VS Code / Cursor
 // extension in ./vscode) that show the same number in their own status bar.
 export { renderStatusLine, tailUsage } from "./statusline.js";
+export * from "./sketch.js";
+export * from "./preferences.js";

package/dist/install.d.ts

@@ -27,6 +27,18 @@ export declare function npxLauncher(platformName: string): {
  * ours. Returns what happened so install can print the truth.
  */
 export declare function installStatusLine(): "installed" | "already" | "kept-foreign" | "no-claude-code";
+export declare function codexDir(): string;
+/**
+ * Add or replace our [mcp_servers.context-doctor] table in config.toml without
+ * a TOML library: the file is the user's, so everything outside our own table
+ * is copied through byte for byte. Our table is delimited by its header and the
+ * next header (or EOF).
+ */
+export declare function upsertCodexMcpTable(toml: string, entry: {
+    command: string;
+    args: string[];
+}): string;
+export declare function removeCodexMcpTable(toml: string): string;
 /** Outcome of an install run, so the CLI can set a truthful exit code. */
 export interface InstallResult {
     /** Detected targets that could not be configured, with the reason. */

package/dist/install.js

@@ -196,9 +196,17 @@ function isOurHookEntry(entry) {
  * Claude Code query gets a context-size check. Idempotent.
  */
 function installHook() {
-    const settingsPath = join(homedir(), ".claude", "settings.json");
-    if (!existsSync(join(homedir(), ".claude")))
-        return null; // no Claude Code here
+    return installHookInto(join(homedir(), ".claude", "settings.json"), join(homedir(), ".claude"));
+}
+/**
+ * Register the UserPromptSubmit hook in a hooks file. Claude Code's
+ * settings.json and Codex's hooks.json share the exact same shape
+ * ({hooks:{UserPromptSubmit:[{hooks:[{type:"command",command}]}]}}), so one
+ * writer serves both; only the path differs.
+ */
+function installHookInto(settingsPath, gateDir) {
+    if (!existsSync(gateDir))
+        return null; // that app is not on this machine
     const settings = readJson(settingsPath);
     settings.hooks = settings.hooks ?? {};
     const entries = settings.hooks.UserPromptSubmit ?? [];
@@ -227,7 +235,10 @@ function installHook() {
     return settingsPath;
 }
 function uninstallHook() {
-    const settingsPath = join(homedir(), ".claude", "settings.json");
+    uninstallHookFrom(join(homedir(), ".claude", "settings.json"), "Claude Code every-prompt hook");
+    uninstallHookFrom(join(homedir(), ".codex", "hooks.json"), "Codex every-prompt hook");
+}
+function uninstallHookFrom(settingsPath, label) {
     if (!existsSync(settingsPath))
         return;
     const settings = readJson(settingsPath);
@@ -240,20 +251,135 @@ function uninstallHook() {
         if (filtered.length === 0)
             delete settings.hooks.UserPromptSubmit;
         writeJsonWithBackup(settingsPath, settings);
-        console.log("✓ Claude Code every-prompt hook removed");
+        console.log(`✓ ${label} removed`);
     }
 }
 function installSkill() {
+    return installSkillInto(join(homedir(), ".claude", "skills", "context-doctor"));
+}
+/** Agent Skills are one format across Claude Code and Codex; only the home differs. */
+function installSkillInto(skillDest) {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     // dist/install.js → package root is one level up; skills/ ships in the package.
     const skillSource = join(selfDir, "..", "skills", "context-doctor", "SKILL.md");
     if (!existsSync(skillSource))
         return null;
-    const skillDest = join(homedir(), ".claude", "skills", "context-doctor");
     mkdirSync(skillDest, { recursive: true });
     copyFileSync(skillSource, join(skillDest, "SKILL.md"));
     return join(skillDest, "SKILL.md");
 }
+// -- Codex (OpenAI's agent: the Codex tab in ChatGPT.app, the IDE extension, the CLI)
+//
+// Codex supports the same three integration points as Claude Code, in almost
+// the same formats: MCP servers ([mcp_servers.<name>] in ~/.codex/config.toml),
+// hooks (~/.codex/hooks.json, identical shape to Claude's settings.json, same
+// hookSpecificOutput.additionalContext response), and Agent Skills
+// (~/.codex/skills/<name>/SKILL.md). One difference matters: Codex requires the
+// user to trust a new hook once, via /hooks inside Codex, before it runs.
+export function codexDir() {
+    return join(homedir(), ".codex");
+}
+/**
+ * Add or replace our [mcp_servers.context-doctor] table in config.toml without
+ * a TOML library: the file is the user's, so everything outside our own table
+ * is copied through byte for byte. Our table is delimited by its header and the
+ * next header (or EOF).
+ */
+export function upsertCodexMcpTable(toml, entry) {
+    const header = "[mcp_servers.context-doctor]";
+    const table = `${header}\n` +
+        `command = ${JSON.stringify(entry.command)}\n` +
+        `args = [${entry.args.map((a) => JSON.stringify(a)).join(", ")}]\n`;
+    const lines = toml.split("\n");
+    const start = lines.findIndex((l) => l.trim() === header);
+    if (start === -1) {
+        const sep = toml.length === 0 || toml.endsWith("\n\n") ? "" : toml.endsWith("\n") ? "\n" : "\n\n";
+        return toml + sep + table;
+    }
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end]))
+        end++;
+    // Trim trailing blank lines inside our block so we do not accumulate them.
+    const before = lines.slice(0, start).join("\n");
+    const after = lines.slice(end).join("\n");
+    return `${before}${before.length ? "\n" : ""}${table}${after.length ? "\n" + after : ""}`;
+}
+export function removeCodexMcpTable(toml) {
+    const header = "[mcp_servers.context-doctor]";
+    const lines = toml.split("\n");
+    const start = lines.findIndex((l) => l.trim() === header);
+    if (start === -1)
+        return toml;
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end]))
+        end++;
+    return [...lines.slice(0, start), ...lines.slice(end)].join("\n").replace(/\n{3,}/g, "\n\n");
+}
+function installCodex(entry, failures) {
+    const dir = codexDir();
+    if (!existsSync(dir))
+        return; // Codex is not on this machine
+    const configPath = join(dir, "config.toml");
+    try {
+        const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+        const next = upsertCodexMcpTable(current, entry);
+        if (next !== current) {
+            if (existsSync(configPath))
+                copyFileSync(configPath, configPath + ".context-doctor.backup");
+            writeFileSync(configPath, next);
+        }
+        console.log(`✓ Codex: MCP server added (${configPath})`);
+    }
+    catch (e) {
+        console.error(`✗ Codex MCP: ${e.message}`);
+        failures.push("Codex MCP");
+    }
+    try {
+        const skill = installSkillInto(join(dir, "skills", "context-doctor"));
+        if (skill)
+            console.log(`✓ Agent Skill installed for Codex (${skill})`);
+    }
+    catch (e) {
+        console.error(`✗ Codex skill: ${e.message}`);
+        failures.push("Codex skill");
+    }
+    try {
+        const hook = installHookInto(join(dir, "hooks.json"), dir);
+        if (hook) {
+            console.log(`✓ Codex every-prompt hook installed (${hook})`);
+            console.log("  Codex runs a new hook only after you trust it once: open Codex, type /hooks, and trust context-doctor.");
+        }
+    }
+    catch (e) {
+        console.error(`✗ Codex hook: ${e.message}`);
+        failures.push("Codex hook");
+    }
+}
+function uninstallCodex() {
+    const dir = codexDir();
+    if (!existsSync(dir))
+        return;
+    const configPath = join(dir, "config.toml");
+    try {
+        if (existsSync(configPath)) {
+            const current = readFileSync(configPath, "utf8");
+            const next = removeCodexMcpTable(current);
+            if (next !== current) {
+                copyFileSync(configPath, configPath + ".context-doctor.backup");
+                writeFileSync(configPath, next);
+                console.log("✓ Codex: MCP server removed");
+            }
+        }
+    }
+    catch (e) {
+        console.error(`✗ Codex MCP: ${e.message}`);
+    }
+    const skillDir = join(dir, "skills", "context-doctor");
+    if (existsSync(skillDir)) {
+        rmSync(skillDir, { recursive: true });
+        console.log("✓ Codex skill removed");
+    }
+}
 /**
  * Install into every detected app.
  *
@@ -267,7 +393,7 @@ function installSkill() {
 export function runInstall(options = {}) {
     const entry = serverEntry();
     const found = targets().filter((t) => t.detect());
-    if (found.length === 0) {
+    if (found.length === 0 && !existsSync(codexDir())) {
         console.log("No supported AI apps detected (Claude Desktop, Claude Code, Cursor).");
         console.log("Manual setup — add to your app's MCP config:");
         console.log(JSON.stringify({ mcpServers: { "context-doctor": entry } }, null, 2));
@@ -314,6 +440,7 @@ export function runInstall(options = {}) {
         console.error(`✗ Claude Code every-prompt hook: ${e.message}`);
         failures.push("Claude Code hook");
     }
+    installCodex(entry, failures);
     if (options.statusLine) {
         try {
             switch (installStatusLine()) {
@@ -343,6 +470,8 @@ export function runInstall(options = {}) {
     else {
         console.log("\nDone. Restart the apps to pick up the new tools, then try:");
         console.log('  "What\'s eating my context?" — or paste a conversation and ask for a profile.');
+        console.log("Chat apps (Claude Desktop, claude.ai, ChatGPT, phones) have no hook. To make the rules standing there:");
+        console.log("  context-doctor instructions --copy   then paste into the app's preferences (it tells you where).");
     }
     return { failures };
 }
@@ -369,6 +498,7 @@ export function runUninstall() {
     }
     uninstallHook();
     uninstallStatusLine();
+    uninstallCodex();
     // Remove our bookkeeping files too — uninstall means gone.
     for (const file of [".context-doctor-hook-state.json", ".context-doctor-ledger.jsonl"]) {
         const p = join(homedir(), ".claude", file);

package/dist/mcp.js

@@ -21,6 +21,7 @@ import { optimizeConversation } from "./optimize.js";
 import { renderProfile } from "./report.js";
 import { formatTokens } from "./tokens.js";
 import { recordLedger } from "./ledger.js";
+import { runSketch } from "./sketch.js";
 /**
  * Server instructions are injected by MCP clients (Claude Desktop, Cursor, …)
  * into the system context of EVERY conversation where this server is enabled.
@@ -28,8 +29,19 @@ import { recordLedger } from "./ledger.js";
  * "standing context-hygiene instructions in every chat" — no hook needed.
  */
 // Kept deliberately terse: these ride in EVERY conversation's context, and a
-// context-saving tool must not itself be context overhead (~110 tokens).
-const SERVER_INSTRUCTIONS = `Context hygiene, always: summarize large pastes/tool results instead of carrying them verbatim; reference earlier content, don't re-quote; never inline base64. Past ~30 turns or several large pastes, proactively offer to run profile_context. Any question about tokens, cost, or latency: call profile_context, don't estimate. If optimize_context returns a pruned-turns digest, you write the ≤150-token replacement summary.`;
+// context-saving tool must not itself be context overhead (~130 tokens).
+//
+// Written as conditions and actions, not offers. On Claude Desktop this string
+// is the only channel that reaches the model without the user asking — MCP has
+// no hook and no data path there — so "offer to run" leaves it to a model that
+// will usually not, while "when X, call Y before answering" is followed. The
+// thresholds keep it from firing on every turn, which would cost more context
+// than it saves.
+const SERVER_INSTRUCTIONS = `Context hygiene rules (always on):
+1. Summarize any paste or tool result over ~2k tokens into the points you will use, then work from the summary; never carry it verbatim.
+2. Reference earlier content by name; never re-quote it. Never inline base64.
+3. When the conversation passes ~30 turns, or holds 3+ large pastes, or the user asks about tokens, cost, speed or limits: call profile_context BEFORE answering and act on its top finding. In a chat app pass a \`sketch\` (turn count + the large/repeated blocks, ~100 tokens), not the conversation. Do not estimate token counts yourself.
+4. If optimize_context returns a pruned-turns digest, you write the ≤150-token replacement summary.`;
 const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-base64", "prune-history"];
 /**
  * Build a fully-configured server instance. A factory (not a singleton) so the
@@ -37,11 +49,35 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.14.3" }, { instructions: SERVER_INSTRUCTIONS });
-    server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
-        conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
+    const server = new McpServer({ name: "context-doctor", version: "0.17.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, ~100 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({
+            turns: z.number().int().nonnegative().describe("User+assistant exchanges so far"),
+            model: z.string().optional().describe("Model this chat runs as, e.g. claude-sonnet-5, gpt-5"),
+            blocks: z.array(z.object({
+                turn: z.number().int().positive().describe("1-based turn the block sits in"),
+                kind: z.enum(["paste", "code", "tool_result", "image", "base64", "text"]),
+                label: z.string().describe("Short name you can refer to later, e.g. 'the nginx config'"),
+                approx_tokens: z.number().positive().optional(),
+                approx_lines: z.number().positive().optional(),
+                approx_words: z.number().positive().optional(),
+                approx_chars: z.number().positive().optional(),
+                repeated: z.number().int().positive().optional().describe("Times this same content appears (2+ = duplicate)"),
+                stale: z.boolean().optional().describe("Already acted on; nothing in it is still needed"),
+            })).describe("Only the blocks over ~500 tokens, repeated, or images. Plain turns need not be listed."),
+        }).optional().describe("Coarse description of the conversation for chat apps. Give one size hint per block (lines, words, chars or tokens)."),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),
-    }, async ({ conversation, model }) => {
+    }, async ({ conversation, sketch, model }) => {
+        if (sketch) {
+            return { content: [{ type: "text", text: runSketch({ ...sketch, model: sketch.model ?? model }) }] };
+        }
+        if (!conversation) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "Pass either `conversation` (full JSON or text) or `sketch` (turns + large/repeated blocks). In a chat app, use `sketch`." }],
+            };
+        }
         const profile = profileConversation(parseConversation(conversation), model);
         return { content: [{ type: "text", text: renderProfile(profile) }] };
     });
@@ -93,6 +129,23 @@ function createServer() {
         }
         return { content };
     });
+    // A prompt shows up in Claude Desktop's "+" menu, so a user can run a checkup
+    // with one click instead of typing a request. It is the only proactive
+    // surface MCP offers besides `instructions`.
+    server.prompt("context_checkup", "Profile this conversation's context and apply the top fix. One click, no typing.", async () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "Run profile_context on our conversation so far: pass a `sketch` (turn count, the model you are running as, and every block over ~500 tokens, repeated, or an image; one size hint each). " +
+                        "Report the total, the top three findings, and the estimated recoverable tokens in under 120 words. " +
+                        "Then, if the top finding is recoverable, apply it: summarize the offending content into the points still needed and tell me what you dropped. " +
+                        "Do not re-quote the content you are summarizing.",
+                },
+            },
+        ],
+    }));
     server.tool("context_best_practices", "Get a curated checklist of context-management best practices, optionally specialized for a provider (anthropic, openai).", {
         provider: z.enum(["general", "anthropic", "openai"]).optional().describe("Provider to specialize tips for (default: general)"),
     }, async ({ provider }) => {

package/dist/preferences.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Standing context rules for chat apps that have no hook and, on phones and the
+ * web, no MCP server either: claude.ai "personal preferences" and ChatGPT
+ * "custom instructions" are read on every turn of every chat, which is the
+ * closest thing those surfaces have to a UserPromptSubmit hook.
+ *
+ * Kept short (~90 tokens): it rides in every conversation.
+ */
+export declare const CHAT_PREFERENCES: string;
+/** Where to paste, per app. Paths are the UI labels, not URLs, so they survive redesigns. */
+export declare const PREFERENCE_TARGETS: string[];
+/** Copy text to the system clipboard; false when no clipboard tool is available. */
+export declare function copyToClipboard(text: string, platform?: NodeJS.Platform): boolean;
+export declare function renderPreferences(copied: boolean | undefined): string;

package/dist/preferences.js

@@ -0,0 +1,47 @@
+/**
+ * Standing context rules for chat apps that have no hook and, on phones and the
+ * web, no MCP server either: claude.ai "personal preferences" and ChatGPT
+ * "custom instructions" are read on every turn of every chat, which is the
+ * closest thing those surfaces have to a UserPromptSubmit hook.
+ *
+ * Kept short (~90 tokens): it rides in every conversation.
+ */
+import { spawnSync } from "node:child_process";
+export const CHAT_PREFERENCES = [
+    "Context hygiene: when I paste something long, summarize it into the points you will use and work from the summary;",
+    "do not carry it verbatim or re-quote it later, refer to it by name. Never inline base64.",
+    "Past ~30 turns, or when I ask about tokens, limits, cost or speed: if a profile_context tool is available,",
+    "call it with a sketch before answering and act on its top finding; otherwise offer me a 300-token handoff",
+    "summary (decisions, current state, open items) to start a fresh chat.",
+].join(" ");
+/** Where to paste, per app. Paths are the UI labels, not URLs, so they survive redesigns. */
+export const PREFERENCE_TARGETS = [
+    "claude.ai / Claude Desktop / Claude mobile: Settings > Profile > \"What personal preferences should Claude consider in responses?\"",
+    "ChatGPT: Settings > Personalization > Custom instructions > \"How would you like ChatGPT to respond?\"",
+];
+/** Copy text to the system clipboard; false when no clipboard tool is available. */
+export function copyToClipboard(text, platform = process.platform) {
+    const candidates = platform === "darwin" ? [["pbcopy", []]]
+        : platform === "win32" ? [["clip", []]]
+            : [["wl-copy", []], ["xclip", ["-selection", "clipboard"]], ["xsel", ["--clipboard", "--input"]]];
+    for (const [cmd, args] of candidates) {
+        const r = spawnSync(cmd, args, { input: text, stdio: ["pipe", "ignore", "ignore"] });
+        if (!r.error && r.status === 0)
+            return true;
+    }
+    return false;
+}
+export function renderPreferences(copied) {
+    const lines = [
+        "Paste this into your chat app's standing preferences. It applies to every chat, including on your phone:",
+        "",
+        CHAT_PREFERENCES,
+        "",
+        ...PREFERENCE_TARGETS.map((t) => `  ${t}`),
+    ];
+    if (copied === true)
+        lines.push("", "Copied to the clipboard.");
+    if (copied === false)
+        lines.push("", "No clipboard tool found; copy the text above by hand.");
+    return lines.join("\n");
+}

package/dist/session.js

@@ -49,6 +49,37 @@ export function listSessions(limit = 20) {
             sessions.push({ path, project, modifiedAt: stat.mtime, sizeBytes: stat.size });
         }
     }
+    // Codex keeps rollouts by date: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl.
+    const codexRoot = join(homedir(), ".codex", "sessions");
+    if (existsSync(codexRoot)) {
+        const walk = (dir, depth) => {
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                return;
+            }
+            for (const name of entries) {
+                const path = join(dir, name);
+                let stat;
+                try {
+                    stat = statSync(path);
+                }
+                catch {
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    if (depth < 3)
+                        walk(path, depth + 1);
+                }
+                else if (name.endsWith(".jsonl")) {
+                    sessions.push({ path, project: "codex", modifiedAt: stat.mtime, sizeBytes: stat.size });
+                }
+            }
+        };
+        walk(codexRoot, 0);
+    }
     return sessions.sort((a, b) => b.modifiedAt.getTime() - a.modifiedAt.getTime()).slice(0, limit);
 }
 /**
@@ -156,6 +187,93 @@ function startsWithArray(path) {
         closeSync(fd);
     }
 }
+/**
+ * Codex (OpenAI's agent: the Codex tab in ChatGPT.app, the IDE extension, the
+ * CLI) writes rollouts to ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl as
+ * {timestamp, type, payload}. Convert one line into the Claude-shaped entry the
+ * rest of this parser understands, or return null for lines that carry no
+ * context (reasoning is encrypted, world_state is bookkeeping).
+ *
+ *   response_item/message                  → user or assistant text
+ *   response_item/function_call | custom_tool_call → assistant tool_use
+ *   response_item/*_call_output            → user tool_result
+ *   event_msg/token_count                  → the API's own usage figures
+ *   turn_context                           → model
+ */
+function fromCodexLine(entry) {
+    const payload = entry.payload;
+    if (!payload || typeof payload !== "object")
+        return null;
+    const timestamp = entry.timestamp;
+    if (entry.type === "turn_context") {
+        return typeof payload.model === "string" ? { codexModel: payload.model } : null;
+    }
+    if (entry.type === "event_msg" && payload.type === "token_count") {
+        const last = payload.info?.last_token_usage;
+        if (!last || !(last.input_tokens > 0))
+            return null;
+        // Codex's input_tokens already includes the cached portion, so it maps to
+        // Anthropic's (input + cache_read) with cached carried separately.
+        const cached = last.cached_input_tokens ?? 0;
+        return {
+            type: "assistant",
+            timestamp,
+            codexUsageOnly: true,
+            message: {
+                role: "assistant",
+                content: [],
+                usage: {
+                    input_tokens: Math.max(0, last.input_tokens - cached),
+                    cache_read_input_tokens: cached,
+                    cache_creation_input_tokens: last.cache_write_input_tokens ?? 0,
+                    output_tokens: last.output_tokens ?? 0,
+                },
+            },
+        };
+    }
+    if (entry.type !== "response_item")
+        return null;
+    const text = (parts) => Array.isArray(parts)
+        ? parts.map((b) => (typeof b === "string" ? b : typeof b?.text === "string" ? b.text : "")).join("\n")
+        : typeof parts === "string" ? parts : "";
+    switch (payload.type) {
+        case "message": {
+            const role = payload.role === "assistant" ? "assistant" : payload.role === "user" ? "user" : null;
+            if (!role)
+                return null;
+            return { type: role, timestamp, message: { role, content: text(payload.content) } };
+        }
+        case "function_call":
+        case "custom_tool_call":
+        case "web_search_call": {
+            const id = payload.call_id ?? payload.id;
+            let input = payload.arguments ?? payload.input ?? payload.action ?? {};
+            if (typeof input === "string") {
+                try {
+                    input = JSON.parse(input);
+                }
+                catch {
+                    input = { input };
+                }
+            }
+            return {
+                type: "assistant",
+                timestamp,
+                message: { role: "assistant", content: [{ type: "tool_use", id, name: payload.name ?? payload.type, input }] },
+            };
+        }
+        case "function_call_output":
+        case "custom_tool_call_output": {
+            return {
+                type: "user",
+                timestamp,
+                message: { role: "user", content: [{ type: "tool_result", tool_use_id: payload.call_id, content: text(payload.output) }] },
+            };
+        }
+        default:
+            return null;
+    }
+}
 export function parseSessionFile(path) {
     // ChatGPT exports are one big JSON array, not JSONL — and small enough to
     // read whole. Only peek first, so multi-hundred-MB JSONL is never slurped.
@@ -197,6 +315,37 @@ export function parseSessionFile(path) {
             title = entry.customTitle;
         if (entry.type === "ai-title" && entry.aiTitle && !title)
             title = entry.aiTitle;
+        // Codex rollouts: translate, then fall through to the shared handling.
+        if (entry.payload && typeof entry.payload === "object" && typeof entry.type === "string" && ["response_item", "event_msg", "turn_context"].includes(entry.type)) {
+            const converted = fromCodexLine(entry);
+            if (!converted)
+                return;
+            if (converted.codexModel) {
+                model = converted.codexModel;
+                return;
+            }
+            if (converted.codexUsageOnly) {
+                // A usage-only line attaches to the conversation position, not a message.
+                const u = converted.message.usage;
+                const total = usageNumber(u.input_tokens) + usageNumber(u.cache_read_input_tokens) + usageNumber(u.cache_creation_input_tokens);
+                if (total > 0) {
+                    reportedInputTokens = total;
+                    usageSamples.push({ index: messages.length, input: total });
+                }
+                return;
+            }
+            entry = converted;
+        }
+        // Cursor's agent transcripts (~/.cursor/projects/*/agent-transcripts/) are
+        // one {role, message:{content}} per line: no `type`, no `message.role`, no
+        // usage. Cursor hands this path to hooks it loads from ~/.claude/settings.json,
+        // so until this shape parsed, our hook fired on every Cursor prompt and
+        // returned nothing.
+        if (!entry.type && (entry.role === "user" || entry.role === "assistant") && entry.message && entry.message.content != null) {
+            const message = entry.message;
+            messages.push({ role: entry.role, content: message.content });
+            return;
+        }
         if ((entry.type !== "user" && entry.type !== "assistant") || !entry.message)
             return;
         if (entry.isSidechain)

package/dist/sketch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Profile a conversation from a SKETCH instead of the conversation itself.
+ *
+ * Why this exists: in a chat app (Claude Desktop, ChatGPT) the model cannot
+ * export the conversation, so asking it to call profile_context with the full
+ * JSON means re-typing 50k+ tokens as a tool argument. No model does that, and
+ * it would double the context it is meant to measure. A sketch is ~100 output
+ * tokens: turn count plus the handful of blocks that matter (pastes, tool
+ * results, images, repeats). The estimate is coarse (±30%) and says so, but it
+ * turns "call profile_context" from an impossible instruction into a cheap one.
+ */
+export type SketchKind = "paste" | "code" | "tool_result" | "image" | "base64" | "text";
+export interface SketchBlock {
+    /** 1-based turn the block sits in. */
+    turn: number;
+    kind: SketchKind;
+    /** Short name the model can refer to later ("the nginx config", "test output #2"). */
+    label: string;
+    approx_tokens?: number;
+    approx_lines?: number;
+    approx_words?: number;
+    approx_chars?: number;
+    /** Times this same content appears in the conversation (2+ = duplicate). */
+    repeated?: number;
+    /** Already acted on; nothing in it is still needed. */
+    stale?: boolean;
+}
+export interface ConversationSketch {
+    /** User+assistant exchanges so far. */
+    turns: number;
+    /** Model the chat runs as, for window and price math. */
+    model?: string;
+    blocks: SketchBlock[];
+}
+export interface SketchFinding {
+    id: "large_block" | "duplicate_block" | "base64_blob" | "many_images" | "long_history" | "near_window_limit";
+    severity: "info" | "warn" | "high";
+    estSavings: number;
+    message: string;
+    action: string;
+}
+export interface SketchProfile {
+    totalTokens: number;
+    baselineTokens: number;
+    blockTokens: number;
+    turns: number;
+    model?: string;
+    contextWindow?: number;
+    usagePct?: number;
+    findings: SketchFinding[];
+    totalEstSavings: number;
+    perTurnUsd?: number;
+    perTurnCachedUsd?: number;
+}
+export declare function blockTokens(b: SketchBlock): number;
+export declare function profileSketch(sketch: ConversationSketch): SketchProfile;
+export declare function renderSketchProfile(p: SketchProfile): string;
+/** Profile a sketch, log it to the ledger like a hook check, and render. */
+export declare function runSketch(sketch: ConversationSketch): string;

package/dist/sketch.js

@@ -0,0 +1,170 @@
+/**
+ * Profile a conversation from a SKETCH instead of the conversation itself.
+ *
+ * Why this exists: in a chat app (Claude Desktop, ChatGPT) the model cannot
+ * export the conversation, so asking it to call profile_context with the full
+ * JSON means re-typing 50k+ tokens as a tool argument. No model does that, and
+ * it would double the context it is meant to measure. A sketch is ~100 output
+ * tokens: turn count plus the handful of blocks that matter (pastes, tool
+ * results, images, repeats). The estimate is coarse (±30%) and says so, but it
+ * turns "call profile_context" from an impossible instruction into a cheap one.
+ */
+import { contextWindowFor } from "./tokens.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
+import { recordLedger } from "./ledger.js";
+// A plain chat turn without attachments: a short user message and a normal
+// assistant reply. Measured across Claude Code transcripts the median user turn
+// is ~120 tokens and the median assistant turn ~450; chat apps run similar.
+const BASELINE_TOKENS_PER_TURN = 570;
+// Tokens per unit when the model reports size in lines/words/chars. Code and
+// tool output are denser per line than prose; words are ~1.35 tokens each.
+const TOKENS_PER_LINE = {
+    code: 12, tool_result: 12, paste: 14, text: 14, base64: 40, image: 0,
+};
+const TOKENS_PER_WORD = 1.35;
+const CHARS_PER_TOKEN = 4;
+// When a block carries no size at all. Images are billed at a near-fixed rate.
+const DEFAULT_TOKENS = {
+    image: 1500, paste: 800, code: 800, tool_result: 800, base64: 4000, text: 300,
+};
+const LARGE_BLOCK_TOKENS = 2000;
+const LONG_HISTORY_TURNS = 30;
+const HANDOFF_SUMMARY_TOKENS = 300;
+const RECENT_TURNS_KEPT = 6;
+export function blockTokens(b) {
+    if (b.kind === "image")
+        return b.approx_tokens ?? DEFAULT_TOKENS.image;
+    if (b.approx_tokens && b.approx_tokens > 0)
+        return Math.round(b.approx_tokens);
+    if (b.approx_lines && b.approx_lines > 0)
+        return Math.round(b.approx_lines * TOKENS_PER_LINE[b.kind]);
+    if (b.approx_words && b.approx_words > 0)
+        return Math.round(b.approx_words * TOKENS_PER_WORD);
+    if (b.approx_chars && b.approx_chars > 0)
+        return Math.round(b.approx_chars / CHARS_PER_TOKEN);
+    return DEFAULT_TOKENS[b.kind];
+}
+export function profileSketch(sketch) {
+    const turns = Math.max(0, Math.floor(sketch.turns || 0));
+    const blocks = Array.isArray(sketch.blocks) ? sketch.blocks : [];
+    const baselineTokens = turns * BASELINE_TOKENS_PER_TURN;
+    // A repeated block costs its size every time it appears.
+    const sized = blocks.map((b) => ({ block: b, tokens: blockTokens(b), copies: Math.max(1, Math.floor(b.repeated ?? 1)) }));
+    const blockTotal = sized.reduce((n, s) => n + s.tokens * s.copies, 0);
+    const totalTokens = baselineTokens + blockTotal;
+    const findings = [];
+    for (const { block, tokens, copies } of sized) {
+        if (copies > 1) {
+            findings.push({
+                id: "duplicate_block",
+                severity: "warn",
+                estSavings: tokens * (copies - 1),
+                message: `"${block.label}" appears ${copies} times (~${formatTokens(tokens)} each).`,
+                action: `Refer to "${block.label}" by name from now on; never re-quote it.`,
+            });
+        }
+        if (block.kind === "base64") {
+            findings.push({
+                id: "base64_blob",
+                severity: "high",
+                estSavings: Math.max(0, tokens - 50),
+                message: `"${block.label}" is inline base64 (~${formatTokens(tokens)}), which the model cannot read anyway.`,
+                action: `Drop it: describe "${block.label}" in one line and ask the user to attach it as a file if needed.`,
+            });
+            continue;
+        }
+        if (block.kind !== "image" && tokens >= LARGE_BLOCK_TOKENS) {
+            // A summary keeps roughly 30% of a block that is still in use; a stale
+            // block needs only a one-line pointer.
+            const est = block.stale ? Math.max(0, tokens - 100) : Math.round(tokens * 0.7);
+            findings.push({
+                id: "large_block",
+                severity: tokens >= 4 * LARGE_BLOCK_TOKENS ? "high" : "warn",
+                estSavings: est,
+                message: `"${block.label}" (turn ${block.turn}, ${block.kind}) is ~${formatTokens(tokens)}${block.stale ? " and already acted on" : ""}.`,
+                action: block.stale
+                    ? `Replace "${block.label}" with a one-line note of what it was and what came of it.`
+                    : `Summarize "${block.label}" into the points still needed (facts, identifiers, decisions) and work from the summary.`,
+            });
+        }
+    }
+    const images = sized.filter((s) => s.block.kind === "image");
+    if (images.length >= 3) {
+        const imgTokens = images.reduce((n, s) => n + s.tokens * s.copies, 0);
+        findings.push({
+            id: "many_images",
+            severity: "info",
+            estSavings: 0,
+            message: `${images.length} images (~${formatTokens(imgTokens)}) ride along on every turn.`,
+            action: "Once an image has been read, describe what it showed in a sentence so it need not be looked at again; new chats should get only the images still needed.",
+        });
+    }
+    if (turns >= LONG_HISTORY_TURNS) {
+        const afterHandoff = RECENT_TURNS_KEPT * BASELINE_TOKENS_PER_TURN + HANDOFF_SUMMARY_TOKENS;
+        findings.push({
+            id: "long_history",
+            severity: totalTokens > 100_000 ? "high" : "warn",
+            estSavings: Math.max(0, totalTokens - afterHandoff),
+            message: `${turns} turns: every new message re-reads ~${formatTokens(totalTokens)}.`,
+            action: `Offer a handoff: write a ≤${HANDOFF_SUMMARY_TOKENS}-token summary (decisions, current state, open items, key identifiers) for the user to start a new chat with. A fresh chat re-reads ~${formatTokens(afterHandoff)} instead.`,
+        });
+    }
+    const contextWindow = contextWindowFor(sketch.model);
+    const usagePct = contextWindow ? Math.round((totalTokens / contextWindow) * 100) : undefined;
+    if (usagePct !== undefined && usagePct >= 70) {
+        findings.push({
+            id: "near_window_limit",
+            severity: "high",
+            estSavings: 0,
+            message: `~${usagePct}% of the ${formatTokens(contextWindow)} window. Quality drops and the app may start dropping early turns.`,
+            action: "Do the handoff now rather than at the next problem.",
+        });
+    }
+    const order = { high: 0, warn: 1, info: 2 };
+    findings.sort((a, b) => order[a.severity] - order[b.severity] || b.estSavings - a.estSavings);
+    // A handoff to a fresh chat subsumes every per-block fix, so "recoverable" is
+    // the larger of the two routes, not their sum, capped at what is there.
+    const handoff = findings.find((f) => f.id === "long_history")?.estSavings ?? 0;
+    const perBlock = findings.filter((f) => f.id !== "long_history").reduce((n, f) => n + f.estSavings, 0);
+    const totalEstSavings = Math.min(totalTokens, Math.max(handoff, perBlock));
+    const pricing = pricingFor(sketch.model);
+    return {
+        totalTokens, baselineTokens, blockTokens: blockTotal, turns, model: sketch.model, contextWindow, usagePct,
+        findings, totalEstSavings,
+        perTurnUsd: pricing ? inputCostUsd(totalTokens, pricing) : undefined,
+        perTurnCachedUsd: pricing ? (totalTokens / 1_000_000) * pricing.cacheReadPerM : undefined,
+    };
+}
+export function renderSketchProfile(p) {
+    const lines = [];
+    const window = p.usagePct !== undefined ? ` (~${p.usagePct}% of ${formatTokens(p.contextWindow)})` : "";
+    lines.push(`Context estimate from sketch: ~${formatTokens(p.totalTokens)} tokens${window}, ${p.turns} turns.`);
+    lines.push(`  ${formatTokens(p.baselineTokens)} plain conversation + ${formatTokens(p.blockTokens)} in pastes, tool output and images. Estimate, ±30%.`);
+    if (p.perTurnUsd !== undefined) {
+        lines.push(`  Re-read on every turn: ${formatUsd(p.perTurnUsd)} at list price, ${formatUsd(p.perTurnCachedUsd)} when cached. On a subscription this is what spends the usage limit.`);
+    }
+    else {
+        lines.push("  Re-read on every turn. On a subscription this is what spends the usage limit.");
+    }
+    if (p.findings.length === 0) {
+        lines.push("No findings: nothing large, repeated, or stale in the sketch. Keep going.");
+        return lines.join("\n");
+    }
+    lines.push("");
+    lines.push(`Findings (recoverable ~${formatTokens(p.totalEstSavings)} tokens):`);
+    p.findings.forEach((f, i) => {
+        const save = f.estSavings > 0 ? ` [~${formatTokens(f.estSavings)}]` : "";
+        lines.push(`${i + 1}. ${f.severity.toUpperCase()}${save} ${f.message}`);
+        lines.push(`   → ${f.action}`);
+    });
+    lines.push("");
+    lines.push("Act on #1 in your reply (do it, do not just suggest it), and tell the user in one line what you dropped and roughly what it saves per turn.");
+    return lines.join("\n");
+}
+/** Profile a sketch, log it to the ledger like a hook check, and render. */
+export function runSketch(sketch) {
+    const profile = profileSketch(sketch);
+    recordLedger({ ev: "check", sid: "mcp-sketch", src: "mcp", tok: profile.totalTokens, warn: profile.findings.some((f) => f.severity !== "info"), model: sketch.model });
+    return renderSketchProfile(profile);
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "context-doctor",
-  "version": "0.14.3",
-  "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude, GPT, Gemini, and any MCP-capable AI app.",
+  "version": "0.17.0",
+  "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude Code, Claude Desktop, Cursor, Codex (OpenAI), and any MCP-capable AI app.",
   "keywords": [
-    "llm",
+    "claude",
+    "claude-code",
+    "codex",
+    "context-management",
     "context-window",
-    "tokens",
-    "prompt-engineering",
+    "cursor",
+    "llm",
     "mcp",
     "model-context-protocol",
-    "claude",
     "openai",
-    "context-management",
-    "prompt-caching"
+    "prompt-caching",
+    "prompt-engineering",
+    "tokens"
   ],
   "license": "MIT",
   "author": "gAI Ventures (https://gai.ventures)",
@@ -42,7 +45,8 @@
     "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
     "prepublishOnly": "npm test",
     "dev": "tsc --watch",
-    "test": "npm run build && node scripts/test.mjs"
+    "test": "npm run build && node scripts/test.mjs",
+    "build:mcpb": "npm run build && node scripts/build-mcpb.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",