context-doctor 0.16.0 → 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`) |
@@ -189,17 +190,19 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 | **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** | Only the ~150-token standing instruction, plus a one-click `context_checkup` prompt in the + menu | The instruction now tells the model *when* to call `profile_context` (past ~30 turns, 3+ large pastes, any cost/speed question) rather than offering. It is a strong nudge, not enforcement: Desktop chat has no hook and no data path, and we checked the app bundle to be sure |
+| **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; an honest "reminded in every chat, tools one click away" for Claude Desktop; and not a claim we make for the ChatGPT chat UI.
+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`; 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 |
@@ -220,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)
 
@@ -235,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 |
 
@@ -479,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/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.js

@@ -470,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 };
 }

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.
@@ -39,7 +40,7 @@ import { recordLedger } from "./ledger.js";
 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 on the conversation BEFORE answering and act on its top finding. Do not estimate token counts yourself.
+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"];
 /**
@@ -48,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.16.0" }, { 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) }] };
     });
@@ -113,7 +138,7 @@ function createServer() {
                 role: "user",
                 content: {
                     type: "text",
-                    text: "Run profile_context on our conversation so far (model: the one you are running as). " +
+                    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.",

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/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,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.16.0",
+  "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": [
     "claude",
@@ -45,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",