context-doctor 0.26.0 → 0.28.0

package/dist/split.js

@@ -0,0 +1,165 @@
+/**
+ * `context-doctor overhead split <file>`: turn a heavy memory file into a lean
+ * one plus a reference file the agent opens when a task needs it.
+ *
+ * A memory file (CLAUDE.md, AGENTS.md, an auto-memory index) is re-read on
+ * every request. Rules belong there; reference material (architecture notes,
+ * long examples, field lists) is needed on few requests. Sections over a size
+ * threshold, or made mostly of code, move to `<name>.reference.md` next to the
+ * file, and each leaves a one-line pointer naming the file and section: a
+ * plain path, not an @import, so it is read on demand instead of loaded.
+ *
+ * Shown as a plan first; written only with --write, after a backup. Nothing
+ * is summarized or dropped: every moved line is in the reference file.
+ */
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import { estimateTokens, formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+const CLAUDE = "claude-opus-5";
+/** Sections at the file's top heading level below the title (## in most memory files). */
+function sections(text) {
+    const lines = text.split("\n");
+    const headingLevels = [];
+    let fence = false;
+    for (const l of lines) {
+        if (/^\s*(```|~~~)/.test(l))
+            fence = !fence;
+        const m = !fence && /^(#{1,6})\s+\S/.exec(l);
+        if (m)
+            headingLevels.push(m[1].length);
+    }
+    // Split at the shallowest level that occurs more than once (a lone H1 is the title).
+    const counts = new Map();
+    for (const h of headingLevels)
+        counts.set(h, (counts.get(h) ?? 0) + 1);
+    const level = [...counts.keys()].sort((a, b) => a - b).find((h) => counts.get(h) > 1) ?? 2;
+    const preamble = [];
+    const list = [];
+    fence = false;
+    for (const l of lines) {
+        if (/^\s*(```|~~~)/.test(l))
+            fence = !fence;
+        const m = !fence && /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(l);
+        if (m && m[1].length === level)
+            list.push({ heading: m[2], level, lines: [l] });
+        else if (list.length)
+            list[list.length - 1].lines.push(l);
+        else
+            preamble.push(l);
+    }
+    return { preamble, list, level };
+}
+function codeShare(text) {
+    let code = 0;
+    for (const m of text.matchAll(/```[\s\S]*?```/g))
+        code += m[0].length;
+    return text.length ? code / text.length : 0;
+}
+export function referencePathFor(path) {
+    const ext = extname(path) || ".md";
+    return join(dirname(path), `${basename(path, ext)}.reference${ext}`);
+}
+/** A section made mostly of link lines is an index: it is what lets the agent find everything else. */
+function isIndex(lines) {
+    const items = lines.slice(1).filter((l) => l.trim());
+    return items.length > 0 && items.filter((l) => /\]\([^)]+\)/.test(l)).length / items.length >= 0.5;
+}
+/**
+ * Plan the split; pure apart from reading the file. An auto-memory MEMORY.md
+ * is meant to be an index (Claude Code loads it on every request and reads
+ * topic files on demand), so everything in it that is not an index moves,
+ * whatever its size.
+ */
+export function planSplit(path, { minTokens = 400 } = {}) {
+    const text = readFileSync(path, "utf8");
+    const referencePath = referencePathFor(path);
+    const refName = basename(referencePath);
+    const memoryIndex = basename(path) === "MEMORY.md";
+    const { preamble, list } = sections(text);
+    const kept = [...preamble];
+    const moved = [];
+    const out = [];
+    let group = [];
+    // Consecutive moved sections share one pointer, so the lean file does not fill up with them.
+    const flush = () => {
+        if (group.length === 0)
+            return;
+        const names = group.map((g) => g.heading);
+        const tokens = group.reduce((t, g) => t + g.tokens, 0);
+        if (memoryIndex) {
+            kept.push(`- [${names.join("; ")}](${refName}) — moved out of the index (~${formatTokens(tokens)} tokens); read when a task involves them`, "");
+        }
+        else if (group.length === 1) {
+            kept.push(`## ${names[0]}`, `Moved to ${refName} § "${names[0]}" (~${formatTokens(tokens)} tokens). Read that section when a task involves it.`, "");
+        }
+        else {
+            kept.push(`Sections moved to ${refName} (~${formatTokens(tokens)} tokens): ${names.map((n) => `"${n}"`).join(", ")}. Read the one a task involves.`, "");
+        }
+        group = [];
+    };
+    for (const s of list) {
+        const body = s.lines.join("\n");
+        const tokens = estimateTokens(body, CLAUDE);
+        const reason = isIndex(s.lines)
+            ? undefined
+            : memoryIndex
+                ? "not index"
+                : tokens >= minTokens
+                    ? "large"
+                    : tokens >= 150 && codeShare(body) > 0.5
+                        ? "code"
+                        : undefined;
+        const section = { heading: s.heading, tokens, moved: !!reason, reason };
+        out.push(section);
+        if (!reason) {
+            flush();
+            kept.push(...s.lines);
+            continue;
+        }
+        moved.push(body.replace(/\n\s*$/, ""), "");
+        group.push(section);
+    }
+    flush();
+    const keptText = kept.join("\n").replace(/\n{3,}/g, "\n\n");
+    const header = `# Reference moved out of ${basename(path)}\n\nRead a section when a task needs it; ${basename(path)} points here by section name.\n\n`;
+    const movedText = moved.length ? header + moved.join("\n") : "";
+    return {
+        path,
+        referencePath,
+        sections: out,
+        keptText,
+        movedText,
+        tokensBefore: estimateTokens(text, CLAUDE),
+        tokensAfter: estimateTokens(keptText, CLAUDE),
+    };
+}
+/** Write the plan: back up the original, write the lean file, append to (or create) the reference file. */
+export function applySplit(plan, now = Date.now()) {
+    const backup = `${plan.path}.context-doctor-backup-${now}`;
+    copyFileSync(plan.path, backup);
+    if (existsSync(plan.referencePath)) {
+        const prev = readFileSync(plan.referencePath, "utf8");
+        writeFileSync(plan.referencePath, prev.trimEnd() + "\n\n" + plan.movedText.replace(/^# Reference moved out of[^\n]*\n\n[^\n]*\n\n/, ""));
+    }
+    else {
+        writeFileSync(plan.referencePath, plan.movedText);
+    }
+    writeFileSync(plan.path, plan.keptText);
+    return { backup };
+}
+export function renderSplit(plan, usdPerKPerMonth) {
+    const out = [];
+    const saved = plan.tokensBefore - plan.tokensAfter;
+    out.push(`SPLIT PLAN for ${plan.path}`, "═".repeat(56));
+    if (!plan.sections.some((s) => s.moved)) {
+        out.push(`Nothing to move: no section reaches the threshold. ~${formatTokens(plan.tokensBefore)} tokens stay as they are.`);
+        return out.join("\n");
+    }
+    for (const s of plan.sections) {
+        out.push(`  ${s.moved ? "→ move" : "  keep"}  ~${formatTokens(s.tokens).padStart(5)}  ${s.heading}${s.reason === "code" ? "  (mostly code)" : s.reason === "not index" ? "  (not an index entry)" : ""}`);
+    }
+    const usd = usdPerKPerMonth ? `, ~${formatUsd((saved / 1000) * usdPerKPerMonth)}/month at your usage` : "";
+    out.push("", `Every request: ~${formatTokens(plan.tokensBefore)} → ~${formatTokens(plan.tokensAfter)} tokens (−${formatTokens(saved)}${usd}).`, `Moved sections go to ${plan.referencePath}, word for word; each leaves a pointer the agent follows when a task needs it.`, "Nothing is written yet. Add --write to apply (the original is backed up first).");
+    return out.join("\n");
+}

package/dist/wrap.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Autopilot in process: `withContextDoctor(client)` for apps that cannot send
+ * their API traffic through the local proxy (serverless and edge functions,
+ * managed hosts, anything without a sidecar).
+ *
+ *   import Anthropic from "@anthropic-ai/sdk";
+ *   import { withContextDoctor } from "context-doctor";
+ *   const client = withContextDoctor(new Anthropic());
+ *
+ * Works on the official Anthropic, OpenAI and Google Gen AI SDK clients (and
+ * anything shaped like them): messages.create/stream,
+ * chat.completions.create/stream/parse, responses.create/stream/parse (beta
+ * namespaces included) and models.generateContent/generateContentStream.
+ * Gemini chat sessions (ai.chats) keep their history inside the SDK, out of
+ * reach; use generateContent with your own history to get autopilot. Each request goes
+ * through the same AutoClearer the proxy uses: stale tool output is cleared
+ * only when the prompt cache is cold, so a request never costs more.
+ *
+ * The request is cloned before it is changed. Apps keep their history in the
+ * arrays they pass, and rewriting those in place would be the silent history
+ * rewriting this project rules out; only the copy that goes on the wire is
+ * slimmer.
+ *
+ * State lives in this process. Run one process per conversation stream (a
+ * server, a worker, an agent) and it behaves like the proxy. A conversation
+ * this instance has not seen is treated as warm, so a fresh serverless
+ * instance never clears blind; pass `statePath` on shared storage when many
+ * instances serve the same conversations.
+ */
+import { AutoClearer, type AutoClearOptions, type AutoClearResult } from "./autoclear.js";
+export interface WrapOptions extends AutoClearOptions {
+    /** Called after each request is prepared: what autopilot did, and the model. */
+    onRequest?: (info: AutoClearResult & {
+        method: string;
+        model?: string;
+    }) => void;
+    /** Share one clearer between several clients (default: one per wrapped client). */
+    clearer?: AutoClearer;
+}
+export interface WrapStats {
+    requests: number;
+    changed: number;
+    tokensRemoved: number;
+}
+/** Totals for a wrapped client: requests seen, how many autopilot slimmed, tokens not sent. */
+export declare function contextDoctorStats(client: object): WrapStats | undefined;
+export declare function withContextDoctor<T extends object>(client: T, options?: WrapOptions): T;

package/dist/wrap.js

@@ -0,0 +1,109 @@
+/**
+ * Autopilot in process: `withContextDoctor(client)` for apps that cannot send
+ * their API traffic through the local proxy (serverless and edge functions,
+ * managed hosts, anything without a sidecar).
+ *
+ *   import Anthropic from "@anthropic-ai/sdk";
+ *   import { withContextDoctor } from "context-doctor";
+ *   const client = withContextDoctor(new Anthropic());
+ *
+ * Works on the official Anthropic, OpenAI and Google Gen AI SDK clients (and
+ * anything shaped like them): messages.create/stream,
+ * chat.completions.create/stream/parse, responses.create/stream/parse (beta
+ * namespaces included) and models.generateContent/generateContentStream.
+ * Gemini chat sessions (ai.chats) keep their history inside the SDK, out of
+ * reach; use generateContent with your own history to get autopilot. Each request goes
+ * through the same AutoClearer the proxy uses: stale tool output is cleared
+ * only when the prompt cache is cold, so a request never costs more.
+ *
+ * The request is cloned before it is changed. Apps keep their history in the
+ * arrays they pass, and rewriting those in place would be the silent history
+ * rewriting this project rules out; only the copy that goes on the wire is
+ * slimmer.
+ *
+ * State lives in this process. Run one process per conversation stream (a
+ * server, a worker, an agent) and it behaves like the proxy. A conversation
+ * this instance has not seen is treated as warm, so a fresh serverless
+ * instance never clears blind; pass `statePath` on shared storage when many
+ * instances serve the same conversations.
+ */
+import { AutoClearer } from "./autoclear.js";
+const WRAPPED = new Set([
+    "messages.create",
+    "messages.stream",
+    "beta.messages.create",
+    "beta.messages.stream",
+    "chat.completions.create",
+    "chat.completions.stream",
+    "chat.completions.parse",
+    "beta.chat.completions.create",
+    "beta.chat.completions.stream",
+    "beta.chat.completions.parse",
+    "responses.create",
+    "responses.stream",
+    "responses.parse",
+    // Google's @google/genai: ai.models.generateContent({ model, contents, config })
+    "models.generateContent",
+    "models.generateContentStream",
+]);
+const PARENTS = new Set([...WRAPPED].flatMap((p) => p.split(".").slice(0, -1).map((_, i, a) => a.slice(0, i + 1).join("."))));
+const STATS = Symbol.for("context-doctor.stats");
+/** Totals for a wrapped client: requests seen, how many autopilot slimmed, tokens not sent. */
+export function contextDoctorStats(client) {
+    return client[STATS];
+}
+export function withContextDoctor(client, options = {}) {
+    const { onRequest, clearer: shared, ...clearOpts } = options;
+    const clearer = shared ?? new AutoClearer({ unseenIsWarm: true, ...clearOpts });
+    const stats = { requests: 0, changed: 0, tokensRemoved: 0 };
+    const prepare = (method, params) => {
+        if (!params || typeof params !== "object" || Array.isArray(params))
+            return params;
+        // Copy the top level and deep-clone only the history, the one part
+        // autopilot rewrites: the rest can hold things that do not clone
+        // (an AbortSignal or callable tools in @google/genai's config).
+        stats.requests++;
+        const src = params;
+        const field = ["messages", "input", "contents"].find((k) => Array.isArray(src[k]));
+        if (!field)
+            return params;
+        let body;
+        try {
+            body = { ...src, [field]: structuredClone(src[field]) };
+        }
+        catch {
+            return params; // something uncloneable inside the history: leave the request alone
+        }
+        const result = clearer.apply(body);
+        if (result.changed) {
+            stats.changed++;
+            stats.tokensRemoved += result.tokensRemoved;
+        }
+        try {
+            onRequest?.({ ...result, method, model: typeof body.model === "string" ? body.model : undefined });
+        }
+        catch {
+            /* a logging callback must not fail the request */
+        }
+        return result.changed ? body : params;
+    };
+    const wrap = (target, path) => new Proxy(target, {
+        get(obj, prop, receiver) {
+            if (prop === STATS && path === "")
+                return stats;
+            const value = Reflect.get(obj, prop, receiver);
+            if (typeof prop !== "string")
+                return value;
+            const full = path ? `${path}.${prop}` : prop;
+            if (WRAPPED.has(full) && typeof value === "function") {
+                return function (params, ...rest) {
+                    return value.call(obj, prepare(full, params), ...rest);
+                };
+            }
+            if (PARENTS.has(full) && value && typeof value === "object")
+                return wrap(value, full);
+            return value;
+        },
+    });
+    return wrap(client, "");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "context-doctor",
-  "version": "0.26.0",
-  "description": "See what your Claude Code sessions cost and cut it: offers /compact when you return to a large session after the cache expired (every surface, desktop app included), and a cache-safe autopilot for terminal, IDE and API traffic. Token profiler, hooks, MCP tools and a Claude Code plugin.",
+  "version": "0.28.0",
+  "description": "Cut your Claude Code bill, measured on your own sessions: `npx context-doctor savings` shows what each lever saves, then the hook, autopilot and an earlier auto-compact window do it. Also Cursor, Codex, Claude Desktop and any Anthropic or OpenAI API app. MCP server and Claude Code plugin.",
   "keywords": [
     "agent",
     "ai-agents",

package/skills/context-doctor/SKILL.md

@@ -28,9 +28,10 @@ Proactively (do not wait to be asked):
 If the `context-doctor` MCP tools are available:
 - `profile_context` — pass a conversation JSON (OpenAI or Anthropic format) or raw text; returns a token breakdown, largest messages, findings with estimated savings.
 - `optimize_context` — applies deterministic fixes (dedupe, trim stale tool results, strip base64; opt-in `trim-tool-calls` for big inline file writes and `prune-history`). When the result contains pruned-turn source material and asks for a summary, **you write that summary** (≤150 tokens, dense, factual) and place it where the stub indicates — this is how summarization works without any API key.
+- `pack_context` — before reading a large document, log or folder to answer a question (not to edit it), pass `paths` and the `query`: it returns only the best-matching chunks within `max_tokens` (default 4000), each with an id and line range, plus the next-best ids. No query = an outline to pick from with `ids`.
 - `context_best_practices` — provider-specific checklist to share with the user.
 
-If the tools are not connected, the CLI does the same: `npx context-doctor analyze <file> --model <model>` and `npx context-doctor optimize <file>`. For always-on optimization of the user's own apps: `npx context-doctor proxy` then point `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` at it.
+If the tools are not connected, the CLI does the same: `npx context-doctor analyze <file> --model <model>` and `npx context-doctor optimize <file>`, and `npx context-doctor pack <files> --query "<question>"` for big documents. For always-on optimization of the user's own apps: `npx context-doctor proxy` then point `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` at it.
 
 ## When the user pastes a conversation or asks about their token usage