context-doctor 0.6.0 → 0.8.0

package/README.md

@@ -34,14 +34,12 @@ Findings (4)
 npx context-doctor install
 ```
 
-Until the package lands on npm, install straight from GitHub instead (needs Node 18+):
+That single command is also all it takes to **set up context-doctor on anyone else's machine**. Prefer a global install, or want the unreleased `main`? Both work (Node 18+):
 
 ```bash
-npm install -g github:KushalP1/context-doctor && context-doctor install
+npm install -g context-doctor && context-doctor install
 ```
 
-That pair of commands is also all it takes to **set up context-doctor on anyone else's machine**.
-
 Restart your apps, then just ask Claude: *"what's eating my context?"* (`npx context-doctor uninstall` reverses it.)
 
 **No API keys, ever.** Everything is deterministic local code; when an LLM is needed (summarizing pruned history), the model already running in your app does it. The proxy forwards *your app's* credentials untouched — context-doctor itself holds nothing.
@@ -97,6 +95,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor proxy` | Always-on local proxy that optimizes every Anthropic/OpenAI API request in flight (`/stats` for cumulative savings) |
 | `context-doctor watch [file]` | Live monitor of a growing session/agent trace: token/cost line per change, findings as they appear |
 | `context-doctor doctor` | Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes |
+| `context-doctor dashboard` | Local savings dashboard on 127.0.0.1: tokens saved per day, sessions by context in use vs recoverable, budget status |
 | `context-doctor hook` | The every-prompt Claude Code hook (registered by `install`; you never run this yourself). Warning threshold tunable via `CONTEXT_DOCTOR_WARN_TOKENS` (default 80000) |
 | `context-doctor-mcp` | The MCP server itself — stdio by default (what the installer wires); `--http [--port 8808] [--host H]` serves streamable HTTP at `/mcp` for URL-based clients like ChatGPT developer-mode connectors |
 
@@ -163,7 +162,11 @@ The proxy dedupes repeated content, trims stale tool results, and strips base64
 [context-doctor] POST /v1/messages → 200 in 842ms | optimized 7.3k → 518 tokens (2 changes) | session total: 6.9k tokens ≈ $0.021 saved
 ```
 
-`GET http://localhost:8787/stats` returns cumulative savings (requests, tokens, estimated USD) since launch.
+`GET http://localhost:8787/stats` returns cumulative savings (requests, tokens, estimated USD), **exact upstream usage** read from every response (JSON and SSE), and **prompt-cache advisories** — the proxy watches your real traffic and flags big stable prefixes missing `cache_control` or prefix churn that silently re-bills the cache. Per-model behavior via `--config`:
+
+```json
+{ "routes": [{ "modelPrefix": "gpt", "strategies": ["strip-base64"], "keepRecent": 4 }] }
+```
 
 Because prompt caching matches byte-identical prefixes, deterministic strategies are chosen so repeated requests stay stable — but if you rely on aggressive cache prefixes, start with `--strategy strip-base64 --strategy dedupe` and add more as you verify.
 
@@ -279,6 +282,20 @@ One report for your whole machine, led by a headline of **tokens context-doctor
 
 Honest measurement note: proxy numbers are exact. Session numbers are measured-now. What no tool can report is the counterfactual — tokens Claude *avoided* adding because of the hygiene guidance — since the same session can't be re-run without it. The report says so instead of inventing a number.
 
+## Context budgets (`.contextdoctorrc`)
+
+Drop a `.contextdoctorrc` in a project (or your home directory) and context-doctor enforces your limits instead of its defaults:
+
+```json
+{
+  "budget": { "maxTokens": 120000, "maxCostPerMessageUsd": 0.5, "maxWindowPct": 60 },
+  "strategies": ["dedupe", "trim-tool-results"],
+  "keepRecent": 6
+}
+```
+
+The nearest file wins (walking up from the working directory, then `~`). `analyze` and `session` print a budget verdict, the every-prompt hook uses `maxTokens` as its warning threshold and names the breach to the model, and `optimize`/`proxy` pick up the defaults when you do not pass flags.
+
 ## Performance: what context-doctor itself costs
 
 A tool that promises speed must be near-free. Measured overhead per touchpoint:

package/dist/cli.js

@@ -23,6 +23,8 @@ import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
 import { runWatch } from "./watch.js";
 import { exactTokenCount } from "./exact.js";
+import { checkBudget, loadConfig } from "./config.js";
+import { startDashboard } from "./dashboard.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -41,10 +43,17 @@ Usage:
                                                 and remaining recoverable waste in recent sessions
   context-doctor doctor                         Self-check the installation (configs, hook, skill,
                                                 MCP handshake) with one pasteable diagnosis
+  context-doctor dashboard                      Local savings dashboard on 127.0.0.1 (--port n,
+                                                default 8790) — charts from your own machine only
   context-doctor watch [file]                   Live-monitor a growing session/agent trace: running
                                                 token/cost line per change, new findings as they appear
                                                 (--interval-ms n, default 2000)
 
+Project config: an optional .contextdoctorrc (nearest, walking up from cwd, then
+~/.contextdoctorrc) can set a context budget and default strategies:
+  {"budget":{"maxTokens":120000,"maxCostPerMessageUsd":0.5,"maxWindowPct":60},
+   "strategies":["dedupe","trim-tool-results"],"routes":[...]}
+
 Input: a conversation JSON file (OpenAI or Anthropic message format, or a bare
 message array). Use "-" to read from stdin.
 
@@ -61,6 +70,8 @@ Options:
   --max-tool-tokens <n>   (optimize) Token budget for trimmed tool results (default 300)
   --port <n>              (proxy) Port to listen on (default 8787)
   --host <addr>           (proxy) Bind address (default 127.0.0.1; use 0.0.0.0 to expose)
+  --config <file>         (proxy) Per-route overrides: {"routes":[{"modelPrefix":"gpt","strategies":[...],
+                          "keepRecent":n,"maxToolResultTokens":n}]} — first prefix match wins
   --upstream-anthropic <url>  (proxy) Override Anthropic upstream (testing)
   --upstream-openai <url>     (proxy) Override OpenAI upstream (testing)
   -h, --help              Show this help
@@ -115,6 +126,9 @@ function parseArgs(argv) {
             case "--host":
                 args.host = argv[++i];
                 break;
+            case "--config":
+                args.config = argv[++i];
+                break;
             case "--upstream-anthropic":
                 args.upstreamAnthropic = argv[++i];
                 break;
@@ -128,6 +142,22 @@ function parseArgs(argv) {
     args.file = positional[1];
     return args;
 }
+/** Print budget status under a profile when a .contextdoctorrc defines one. */
+function printBudgetStatus(profile, loaded) {
+    const budget = loaded.config.budget;
+    if (!budget || !loaded.path)
+        return;
+    const verdict = checkBudget(budget, profile);
+    console.log("");
+    if (verdict.overBudget) {
+        console.log(`OVER BUDGET (${loaded.path}):`);
+        for (const b of verdict.breaches)
+            console.log(`  x ${b}`);
+    }
+    else {
+        console.log(`Within budget (${loaded.path}).`);
+    }
+}
 function readInput(file) {
     if (file === "-")
         return readFileSync(0, "utf8");
@@ -139,6 +169,10 @@ function main() {
         void runHook();
         return;
     }
+    if (args.command === "dashboard") {
+        startDashboard({ port: args.port, proxyPort: 8787 });
+        return; // server keeps the process alive
+    }
     if (args.command === "watch") {
         runWatch({ file: args.file, intervalMs: args.intervalMs, model: args.model });
         return; // interval keeps the process alive
@@ -183,6 +217,7 @@ function main() {
         else {
             console.log(`Session: ${parsed.title ?? "(untitled)"}\nFile:    ${parsed.path}\n`);
             console.log(renderProfile(profile));
+            printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`)));
         }
         return;
     }
@@ -195,14 +230,26 @@ function main() {
         return;
     }
     if (args.command === "proxy") {
+        const loadedRc = loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`));
+        let routes = loadedRc.config.routes;
+        if (args.config) {
+            try {
+                routes = JSON.parse(readFileSync(args.config, "utf8")).routes;
+            }
+            catch (e) {
+                console.error(`Could not read --config ${args.config}: ${e.message}`);
+                process.exit(1);
+            }
+        }
         startProxy({
+            routes: routes,
             port: args.port,
             host: args.host,
             anthropicUpstream: args.upstreamAnthropic,
             openaiUpstream: args.upstreamOpenai,
-            strategies: args.strategies.length > 0 ? args.strategies : undefined,
-            keepRecent: args.keepRecent,
-            maxToolResultTokens: args.maxToolTokens,
+            strategies: args.strategies.length > 0 ? args.strategies : loadedRc.config.strategies,
+            keepRecent: args.keepRecent ?? loadedRc.config.keepRecent,
+            maxToolResultTokens: args.maxToolTokens ?? loadedRc.config.maxToolResultTokens,
         });
         return; // server keeps the process alive
     }
@@ -219,8 +266,11 @@ function main() {
         process.exit(1);
     }
     if (args.command === "analyze") {
-        const profile = profileConversation(parseConversation(input), args.model);
+        const loaded = loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`));
+        const profile = profileConversation(parseConversation(input), args.model ?? loaded.config.model);
         console.log(args.json ? JSON.stringify(profile, null, 2) : renderProfile(profile));
+        if (!args.json)
+            printBudgetStatus(profile, loaded);
         if (args.exact) {
             void exactTokenCount(input, args.model).then((exact) => {
                 if (exact.tokens !== undefined) {
@@ -237,10 +287,11 @@ function main() {
     if (args.command === "optimize") {
         let result;
         try {
+            const loaded = loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`));
             result = optimizeConversation(input, {
-                strategies: args.strategies.length > 0 ? args.strategies : undefined,
-                keepRecent: args.keepRecent,
-                maxToolResultTokens: args.maxToolTokens,
+                strategies: args.strategies.length > 0 ? args.strategies : loaded.config.strategies,
+                keepRecent: args.keepRecent ?? loaded.config.keepRecent,
+                maxToolResultTokens: args.maxToolTokens ?? loaded.config.maxToolResultTokens,
             });
         }
         catch (e) {

package/dist/config.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Project configuration and context budgets (`.contextdoctorrc`).
+ *
+ * Discovery walks up from the working directory to the filesystem root, then
+ * falls back to ~/.contextdoctorrc — so a repo can set its own budget and a
+ * user can set a machine-wide default. First file found wins (no merging:
+ * one visible file is easier to reason about than a merge chain).
+ *
+ * Everything here is optional. With no rc file the tool behaves exactly as
+ * it always has.
+ */
+import type { StrategyId } from "./optimize.js";
+export declare const RC_FILENAME = ".contextdoctorrc";
+export interface ContextBudget {
+    /** Warn once a session/conversation exceeds this many tokens. */
+    maxTokens?: number;
+    /** Warn once estimated input cost per message exceeds this many USD. */
+    maxCostPerMessageUsd?: number;
+    /** Warn once the context fills this share of the model window (0-100). */
+    maxWindowPct?: number;
+}
+export interface ContextDoctorConfig {
+    budget?: ContextBudget;
+    /** Default optimize strategies for this project. */
+    strategies?: StrategyId[];
+    keepRecent?: number;
+    maxToolResultTokens?: number;
+    /** Proxy per-model overrides, same shape as `proxy --config`. */
+    routes?: Array<{
+        modelPrefix: string;
+        strategies?: StrategyId[];
+        keepRecent?: number;
+        maxToolResultTokens?: number;
+    }>;
+    /** Model used for cost math when a conversation does not name one. */
+    model?: string;
+}
+export interface LoadedConfig {
+    config: ContextDoctorConfig;
+    /** Absolute path of the rc file, or undefined when none was found. */
+    path?: string;
+}
+/**
+ * Load the nearest config. Malformed rc files are reported (so a typo is not
+ * silently ignored) but never throw — the tool keeps working with defaults.
+ */
+export declare function loadConfig(startDir?: string, onWarn?: (msg: string) => void): LoadedConfig;
+export interface BudgetVerdict {
+    /** True when any configured limit is exceeded. */
+    overBudget: boolean;
+    /** Human-readable lines, one per breached limit. */
+    breaches: string[];
+    /** The token limit in force, when one is configured. */
+    maxTokens?: number;
+}
+/** Compare a profile against the configured budget. */
+export declare function checkBudget(budget: ContextBudget | undefined, profile: {
+    totalTokens: number;
+    usagePct?: number;
+    cost?: {
+        perCallUsd: number;
+    };
+}): BudgetVerdict;

package/dist/config.js

@@ -0,0 +1,73 @@
+/**
+ * Project configuration and context budgets (`.contextdoctorrc`).
+ *
+ * Discovery walks up from the working directory to the filesystem root, then
+ * falls back to ~/.contextdoctorrc — so a repo can set its own budget and a
+ * user can set a machine-wide default. First file found wins (no merging:
+ * one visible file is easier to reason about than a merge chain).
+ *
+ * Everything here is optional. With no rc file the tool behaves exactly as
+ * it always has.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, parse as parsePath } from "node:path";
+export const RC_FILENAME = ".contextdoctorrc";
+/** Candidate rc paths: cwd upwards, then the home directory. */
+function candidatePaths(startDir) {
+    const paths = [];
+    let dir = startDir;
+    const { root } = parsePath(dir);
+    for (;;) {
+        paths.push(join(dir, RC_FILENAME));
+        if (dir === root)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const home = join(homedir(), RC_FILENAME);
+    if (!paths.includes(home))
+        paths.push(home);
+    return paths;
+}
+/**
+ * Load the nearest config. Malformed rc files are reported (so a typo is not
+ * silently ignored) but never throw — the tool keeps working with defaults.
+ */
+export function loadConfig(startDir = process.cwd(), onWarn) {
+    for (const path of candidatePaths(startDir)) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (parsed && typeof parsed === "object")
+                return { config: parsed, path };
+            onWarn?.(`${path}: expected a JSON object — ignoring`);
+        }
+        catch (e) {
+            onWarn?.(`${path}: ${e.message} — ignoring`);
+        }
+        return { config: {} };
+    }
+    return { config: {} };
+}
+/** Compare a profile against the configured budget. */
+export function checkBudget(budget, profile) {
+    const breaches = [];
+    if (!budget)
+        return { overBudget: false, breaches };
+    if (budget.maxTokens !== undefined && profile.totalTokens > budget.maxTokens) {
+        breaches.push(`context is ${profile.totalTokens} tokens, over the ${budget.maxTokens} budget`);
+    }
+    if (budget.maxCostPerMessageUsd !== undefined &&
+        profile.cost !== undefined &&
+        profile.cost.perCallUsd > budget.maxCostPerMessageUsd) {
+        breaches.push(`input cost is $${profile.cost.perCallUsd.toFixed(3)} per message, over the $${budget.maxCostPerMessageUsd.toFixed(3)} budget`);
+    }
+    if (budget.maxWindowPct !== undefined && profile.usagePct !== undefined && profile.usagePct > budget.maxWindowPct) {
+        breaches.push(`context fills ${profile.usagePct.toFixed(0)}% of the window, over the ${budget.maxWindowPct}% budget`);
+    }
+    return { overBudget: breaches.length > 0, breaches, maxTokens: budget.maxTokens };
+}

package/dist/dashboard.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `context-doctor dashboard` — a local savings dashboard.
+ *
+ * Serves one self-contained page on localhost from data already on this
+ * machine: the activity ledger, recent session profiles, and the proxy's
+ * /stats when it is running. No network calls, no accounts, no telemetry —
+ * the server reads local files and answers only the loopback interface.
+ */
+import http from "node:http";
+export interface DashboardData {
+    generatedAt: string;
+    totals: {
+        tokensSaved: number;
+        usdSaved: number;
+        checks: number;
+        warnings: number;
+        optimizeRuns: number;
+    };
+    daily: Array<{
+        date: string;
+        saved: number;
+    }>;
+    sessions: Array<{
+        title: string;
+        tokens: number;
+        waste: number;
+        model?: string;
+    }>;
+    proxy: {
+        requests: number;
+        optimizedRequests: number;
+        tokensSaved: number;
+        estUsdSaved: number;
+    } | null;
+    budget: {
+        path: string;
+        overBudget: boolean;
+        breaches: string[];
+    } | null;
+}
+export declare function collectDashboardData(proxyPort?: number): Promise<DashboardData>;
+export declare function startDashboard(opts?: {
+    port?: number;
+    proxyPort?: number;
+}): http.Server;

package/dist/dashboard.js

@@ -0,0 +1,394 @@
+/**
+ * `context-doctor dashboard` — a local savings dashboard.
+ *
+ * Serves one self-contained page on localhost from data already on this
+ * machine: the activity ledger, recent session profiles, and the proxy's
+ * /stats when it is running. No network calls, no accounts, no telemetry —
+ * the server reads local files and answers only the loopback interface.
+ */
+import http from "node:http";
+import { readLedger } from "./ledger.js";
+import { listSessions, parseSessionFile } from "./session.js";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { inputCostUsd, pricingFor } from "./pricing.js";
+import { checkBudget, loadConfig } from "./config.js";
+/** Sessions bigger than this are skipped so the page stays responsive. */
+const MAX_SESSION_BYTES = 30 * 1024 * 1024;
+async function fetchProxyStats(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/stats`, { signal: AbortSignal.timeout(400) });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectDashboardData(proxyPort = 8787) {
+    const ledger = readLedger();
+    const checks = ledger.filter((e) => e.ev === "check" || e.ev === undefined);
+    const optimizes = ledger.filter((e) => e.ev === "optimize");
+    // Observed shrinkage: a session getting SMALLER between two deep checks is a
+    // real reduction, so it counts alongside explicit optimize runs.
+    const perSession = new Map();
+    for (const c of checks) {
+        if (!c.sid || typeof c.tok !== "number")
+            continue;
+        perSession.set(c.sid, [...(perSession.get(c.sid) ?? []), c.tok]);
+    }
+    let shrinkage = 0;
+    for (const toks of perSession.values()) {
+        for (let i = 1; i < toks.length; i++)
+            if (toks[i] < toks[i - 1])
+                shrinkage += toks[i - 1] - toks[i];
+    }
+    const optimizeSaved = optimizes.reduce((s, e) => s + (e.saved ?? 0), 0);
+    let usdSaved = 0;
+    for (const e of optimizes) {
+        const pricing = pricingFor(e.model);
+        if (pricing && e.saved)
+            usdSaved += inputCostUsd(e.saved, pricing);
+    }
+    // Daily series: optimize savings bucketed by local date.
+    const byDay = new Map();
+    for (const e of optimizes) {
+        if (!e.saved)
+            continue;
+        const day = new Date(e.ts).toISOString().slice(0, 10);
+        byDay.set(day, (byDay.get(day) ?? 0) + e.saved);
+    }
+    const daily = [...byDay.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([date, saved]) => ({ date, saved }));
+    const sessions = [];
+    for (const s of listSessions(8)) {
+        if (s.sizeBytes > MAX_SESSION_BYTES)
+            continue;
+        try {
+            const parsed = parseSessionFile(s.path);
+            if (parsed.messageCount === 0)
+                continue;
+            const p = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
+            sessions.push({
+                title: parsed.title ?? (s.path.split("/").pop() ?? "session").slice(0, 24),
+                tokens: p.totalTokens,
+                waste: p.totalEstSavings,
+                model: parsed.model,
+            });
+        }
+        catch {
+            /* unreadable session — skip */
+        }
+    }
+    const proxy = await fetchProxyStats(proxyPort);
+    const loaded = loadConfig();
+    let budget = null;
+    if (loaded.path && loaded.config.budget && sessions.length > 0) {
+        const biggest = sessions.reduce((a, b) => (b.tokens > a.tokens ? b : a));
+        const verdict = checkBudget(loaded.config.budget, { totalTokens: biggest.tokens });
+        budget = { path: loaded.path, overBudget: verdict.overBudget, breaches: verdict.breaches };
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        totals: {
+            tokensSaved: optimizeSaved + shrinkage + (proxy?.tokensSaved ?? 0),
+            usdSaved: usdSaved + (proxy?.estUsdSaved ?? 0),
+            checks: checks.length,
+            warnings: checks.filter((c) => c.warn).length,
+            optimizeRuns: optimizes.length,
+        },
+        daily,
+        sessions,
+        proxy,
+        budget,
+    };
+}
+export function startDashboard(opts = {}) {
+    const port = opts.port ?? 8790;
+    const server = http.createServer(async (req, res) => {
+        try {
+            if ((req.url ?? "").startsWith("/api/data")) {
+                const data = await collectDashboardData(opts.proxyPort);
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify(data));
+                return;
+            }
+            res.setHeader("content-type", "text/html; charset=utf-8");
+            res.end(PAGE);
+        }
+        catch (e) {
+            res.statusCode = 500;
+            res.end(`dashboard error: ${e.message}`);
+        }
+    });
+    // Loopback only: this page exposes local usage data.
+    server.listen(port, "127.0.0.1", () => {
+        console.error(`context-doctor dashboard on http://127.0.0.1:${port}`);
+    });
+    return server;
+}
+/**
+ * The page. Self-contained (no external requests), renders inline SVG from
+ * /api/data. Palette, mark specs and interaction follow the house data-viz
+ * rules: fixed-order categorical slots, thin marks with 4px rounded data-ends,
+ * 2px surface gaps, legend + direct labels for the two-series chart, hover
+ * tooltips, a table view, and dark steps selected for the dark surface.
+ */
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>context-doctor dashboard</title>
+<style>
+  :root {
+    color-scheme: light;
+    --surface-1: #fcfcfb;
+    --surface-2: #f4f3f0;
+    --border: #e2e1dc;
+    --text-primary: #0b0b0b;
+    --text-secondary: #52514e;
+    --text-muted: #75746f;
+    --series-1: #2a78d6;
+    --series-2: #eb6834;
+    --good: #0ca30c;
+    --critical: #d03b3b;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root:where(:not([data-theme="light"])) {
+      color-scheme: dark;
+      --surface-1: #1a1a19;
+      --surface-2: #232322;
+      --border: #383835;
+      --text-primary: #ffffff;
+      --text-secondary: #c3c2b7;
+      --text-muted: #9b9a92;
+      --series-1: #3987e5;
+      --series-2: #d95926;
+    }
+  }
+  :root[data-theme="dark"] {
+    color-scheme: dark;
+    --surface-1: #1a1a19;
+    --surface-2: #232322;
+    --border: #383835;
+    --text-primary: #ffffff;
+    --text-secondary: #c3c2b7;
+    --text-muted: #9b9a92;
+    --series-1: #3987e5;
+    --series-2: #d95926;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 32px 24px 64px;
+    background: var(--surface-1); color: var(--text-primary);
+    font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  }
+  .wrap { max-width: 940px; margin: 0 auto; }
+  header { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; flex-wrap: wrap; }
+  h1 { font-size: 20px; margin: 0; letter-spacing: -0.01em; }
+  .sub { color: var(--text-muted); font-size: 13px; }
+  .tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px; margin: 24px 0 8px; }
+  .tile { background: var(--surface-2); border: 1px solid var(--border); border-radius: 10px; padding: 14px 16px; }
+  .tile .label { font-size: 12px; color: var(--text-secondary); }
+  .tile .value { font-size: 26px; font-weight: 600; letter-spacing: -0.02em; margin-top: 2px; font-variant-numeric: tabular-nums; }
+  .tile .note { font-size: 12px; color: var(--text-muted); margin-top: 2px; }
+  section { margin-top: 28px; }
+  h2 { font-size: 14px; font-weight: 600; margin: 0 0 2px; }
+  .caption { font-size: 12.5px; color: var(--text-secondary); margin: 0 0 12px; }
+  .legend { display: flex; gap: 14px; font-size: 12.5px; color: var(--text-secondary); margin-bottom: 8px; }
+  .legend span { display: inline-flex; align-items: center; gap: 6px; }
+  .swatch { width: 10px; height: 10px; border-radius: 2px; display: inline-block; }
+  .empty { color: var(--text-muted); font-size: 13px; background: var(--surface-2); border: 1px dashed var(--border); border-radius: 10px; padding: 16px; }
+  svg { display: block; width: 100%; height: auto; overflow: visible; }
+  .grid-line { stroke: var(--border); stroke-width: 1; }
+  .axis-text { fill: var(--text-muted); font-size: 11px; }
+  .label-text { fill: var(--text-secondary); font-size: 12px; }
+  .value-text { fill: var(--text-primary); font-size: 12px; font-variant-numeric: tabular-nums; }
+  .tip {
+    position: fixed; pointer-events: none; opacity: 0; transition: opacity .1s;
+    background: var(--surface-1); color: var(--text-primary);
+    border: 1px solid var(--border); border-radius: 8px; padding: 7px 10px;
+    font-size: 12.5px; box-shadow: 0 6px 20px rgba(0,0,0,.12); z-index: 10; white-space: nowrap;
+  }
+  table { border-collapse: collapse; width: 100%; font-size: 13px; margin-top: 10px; }
+  th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--border); }
+  th { color: var(--text-secondary); font-weight: 600; }
+  td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  details summary { cursor: pointer; font-size: 12.5px; color: var(--text-secondary); margin-top: 10px; }
+  .banner { border-radius: 10px; padding: 12px 14px; font-size: 13px; margin-top: 18px; border: 1px solid; }
+  .banner.ok { border-color: var(--good); color: var(--text-primary); }
+  .banner.over { border-color: var(--critical); color: var(--text-primary); }
+  footer { margin-top: 36px; color: var(--text-muted); font-size: 12px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <div>
+      <h1>context-doctor</h1>
+      <div class="sub" id="generated">loading local data…</div>
+    </div>
+    <div class="sub">everything on this page is read from your machine</div>
+  </header>
+
+  <div class="tiles" id="tiles"></div>
+  <div id="budget"></div>
+
+  <section>
+    <h2>Tokens saved per day</h2>
+    <p class="caption">Optimizations applied through the CLI and in-chat tools.</p>
+    <div id="daily"></div>
+  </section>
+
+  <section>
+    <h2>Recent sessions: context in use and still recoverable</h2>
+    <p class="caption">Each bar is one session. The second segment is what optimization would still reclaim today.</p>
+    <div class="legend">
+      <span><i class="swatch" style="background: var(--series-1)"></i>In use</span>
+      <span><i class="swatch" style="background: var(--series-2)"></i>Recoverable</span>
+    </div>
+    <div id="sessions"></div>
+    <details>
+      <summary>Table view</summary>
+      <div id="sessionsTable"></div>
+    </details>
+  </section>
+
+  <footer id="proxyNote"></footer>
+</div>
+<div class="tip" id="tip"></div>
+
+<script>
+const tip = document.getElementById('tip');
+const fmtTokens = (n) => n >= 1e6 ? (n/1e6).toFixed(1)+'M' : n >= 1e4 ? Math.round(n/1e3)+'k' : n >= 1e3 ? (n/1e3).toFixed(1)+'k' : String(Math.round(n));
+const fmtUsd = (n) => n >= 1 ? '$'+n.toFixed(2) : n >= 0.01 ? '$'+n.toFixed(3) : '$'+n.toFixed(4);
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
+
+function bindTip(el, html) {
+  el.addEventListener('pointerenter', (e) => { tip.innerHTML = html; tip.style.opacity = '1'; move(e); });
+  el.addEventListener('pointermove', move);
+  el.addEventListener('pointerleave', () => { tip.style.opacity = '0'; });
+  function move(e) { tip.style.left = (e.clientX + 14) + 'px'; tip.style.top = (e.clientY - 12) + 'px'; }
+}
+
+function renderTiles(d) {
+  const t = d.totals;
+  const tiles = [
+    { label: 'Tokens saved', value: fmtTokens(t.tokensSaved), note: t.optimizeRuns + ' optimization run(s)' },
+    { label: 'Estimated cost saved', value: t.usdSaved > 0 ? fmtUsd(t.usdSaved) : '—', note: t.usdSaved > 0 ? 'input tokens, priced per model' : 'no priced runs yet (model not recorded)' },
+    { label: 'Context checks', value: String(t.checks), note: t.warnings + ' warning(s) delivered' },
+    { label: 'Sessions tracked', value: String(d.sessions.length), note: 'most recent on this machine' },
+  ];
+  document.getElementById('tiles').innerHTML = tiles.map((x) =>
+    '<div class="tile"><div class="label">' + esc(x.label) + '</div><div class="value">' + esc(x.value) +
+    '</div><div class="note">' + esc(x.note) + '</div></div>').join('');
+}
+
+function renderDaily(rows) {
+  const host = document.getElementById('daily');
+  if (!rows.length) {
+    host.innerHTML = '<div class="empty">No optimizations recorded yet. Run <code>context-doctor optimize</code>, or ask Claude to optimize a conversation, and this fills in.</div>';
+    return;
+  }
+  const W = 900, H = 220, padL = 52, padR = 12, padB = 34, padT = 10;
+  const max = Math.max(...rows.map((r) => r.saved));
+  const innerW = W - padL - padR, innerH = H - padT - padB;
+  const slot = innerW / rows.length;
+  const barW = Math.max(6, Math.min(48, slot - 8)); // 2px+ surface gap between bars
+  const ticks = [0, max / 2, max];
+  let svg = '<svg viewBox="0 0 ' + W + ' ' + H + '" role="img" aria-label="Tokens saved per day">';
+  for (const tk of ticks) {
+    const y = padT + innerH - (tk / max) * innerH;
+    svg += '<line class="grid-line" x1="' + padL + '" y1="' + y + '" x2="' + (W - padR) + '" y2="' + y + '"/>';
+    svg += '<text class="axis-text" x="' + (padL - 8) + '" y="' + (y + 4) + '" text-anchor="end">' + fmtTokens(tk) + '</text>';
+  }
+  rows.forEach((r, i) => {
+    const h = Math.max(2, (r.saved / max) * innerH);
+    const x = padL + i * slot + (slot - barW) / 2;
+    const y = padT + innerH - h;
+    // 4px rounded data-end, square foot on the baseline.
+    const rad = Math.min(4, h);
+    svg += '<path data-i="' + i + '" fill="var(--series-1)" d="M' + x + ' ' + (y + rad) +
+      ' a' + rad + ' ' + rad + ' 0 0 1 ' + rad + ' -' + rad +
+      ' h' + (barW - 2 * rad) +
+      ' a' + rad + ' ' + rad + ' 0 0 1 ' + rad + ' ' + rad +
+      ' v' + (h - rad) + ' h-' + barW + ' z"/>';
+    if (rows.length <= 10) {
+      svg += '<text class="axis-text" x="' + (x + barW / 2) + '" y="' + (H - padB + 18) + '" text-anchor="middle">' + esc(r.date.slice(5)) + '</text>';
+    }
+  });
+  svg += '<line class="grid-line" x1="' + padL + '" y1="' + (padT + innerH) + '" x2="' + (W - padR) + '" y2="' + (padT + innerH) + '"/>';
+  svg += '</svg>';
+  host.innerHTML = svg;
+  host.querySelectorAll('path[data-i]').forEach((el) => {
+    const r = rows[Number(el.getAttribute('data-i'))];
+    bindTip(el, '<strong>' + esc(r.date) + '</strong><br>' + fmtTokens(r.saved) + ' tokens saved');
+  });
+}
+
+function renderSessions(rows) {
+  const host = document.getElementById('sessions');
+  if (!rows.length) {
+    host.innerHTML = '<div class="empty">No session transcripts found on this machine yet.</div>';
+    return;
+  }
+  const W = 900, rowH = 34, padL = 200, padR = 96, padT = 6;
+  const H = padT + rows.length * rowH + 8;
+  const max = Math.max(...rows.map((r) => r.tokens));
+  const innerW = W - padL - padR;
+  let svg = '<svg viewBox="0 0 ' + W + ' ' + H + '" role="img" aria-label="Recent sessions by context size">';
+  rows.forEach((r, i) => {
+    const y = padT + i * rowH + 7;
+    const barH = 16, rad = 4;
+    const usedTok = Math.max(0, r.tokens - r.waste);
+    const totalW = (r.tokens / max) * innerW;
+    const usedW = Math.max(rad, (usedTok / max) * innerW);
+    const wasteW = Math.max(0, totalW - usedW - 2); // 2px surface gap between segments
+    svg += '<text class="label-text" x="0" y="' + (y + 12) + '">' + esc(r.title.slice(0, 30)) + '</text>';
+    svg += '<rect data-u="' + i + '" x="' + padL + '" y="' + y + '" width="' + usedW + '" height="' + barH + '" rx="' + rad + '" fill="var(--series-1)"/>';
+    if (wasteW > 1) {
+      svg += '<rect data-w="' + i + '" x="' + (padL + usedW + 2) + '" y="' + y + '" width="' + wasteW + '" height="' + barH + '" rx="' + rad + '" fill="var(--series-2)"/>';
+    }
+    svg += '<text class="value-text" x="' + (W - padR + 8) + '" y="' + (y + 12) + '">' + fmtTokens(r.tokens) + '</text>';
+  });
+  svg += '</svg>';
+  host.innerHTML = svg;
+  host.querySelectorAll('rect[data-u]').forEach((el) => {
+    const r = rows[Number(el.getAttribute('data-u'))];
+    bindTip(el, '<strong>' + esc(r.title) + '</strong><br>' + fmtTokens(r.tokens - r.waste) + ' tokens in use' + (r.model ? '<br>' + esc(r.model) : ''));
+  });
+  host.querySelectorAll('rect[data-w]').forEach((el) => {
+    const r = rows[Number(el.getAttribute('data-w'))];
+    bindTip(el, '<strong>' + esc(r.title) + '</strong><br>' + fmtTokens(r.waste) + ' tokens recoverable');
+  });
+  document.getElementById('sessionsTable').innerHTML =
+    '<table><thead><tr><th>Session</th><th class="num">Total</th><th class="num">In use</th><th class="num">Recoverable</th></tr></thead><tbody>' +
+    rows.map((r) => '<tr><td>' + esc(r.title) + '</td><td class="num">' + fmtTokens(r.tokens) + '</td><td class="num">' +
+      fmtTokens(r.tokens - r.waste) + '</td><td class="num">' + fmtTokens(r.waste) + '</td></tr>').join('') +
+    '</tbody></table>';
+}
+
+function renderBudget(b) {
+  const host = document.getElementById('budget');
+  if (!b) { host.innerHTML = ''; return; }
+  host.innerHTML = b.overBudget
+    ? '<div class="banner over"><strong>Over budget</strong> (' + esc(b.path) + '): ' + esc(b.breaches.join('; ')) + '</div>'
+    : '<div class="banner ok"><strong>Within budget</strong> (' + esc(b.path) + ')</div>';
+}
+
+fetch('/api/data').then((r) => r.json()).then((d) => {
+  document.getElementById('generated').textContent = 'generated ' + new Date(d.generatedAt).toLocaleString();
+  renderTiles(d);
+  renderBudget(d.budget);
+  renderDaily(d.daily);
+  renderSessions(d.sessions);
+  document.getElementById('proxyNote').textContent = d.proxy
+    ? 'Proxy running: ' + d.proxy.optimizedRequests + ' of ' + d.proxy.requests + ' requests optimized, ' + fmtTokens(d.proxy.tokensSaved) + ' tokens saved this run.'
+    : 'Proxy not running — start it with "context-doctor proxy" to add exact per-request savings here.';
+}).catch((e) => {
+  document.getElementById('generated').textContent = 'could not load local data: ' + e.message;
+});
+</script>
+</body>
+</html>`;

package/dist/hook.js

@@ -17,17 +17,32 @@ import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd } from "./pricing.js";
-/** Start nudging at 80k tokens of context (override: CONTEXT_DOCTOR_WARN_TOKENS). */
-const WARN_TOKENS = Number(process.env.CONTEXT_DOCTOR_WARN_TOKENS) > 0 ? Number(process.env.CONTEXT_DOCTOR_WARN_TOKENS) : 80_000;
+import { checkBudget, loadConfig } from "./config.js";
+/** Default nudge threshold; a project budget or env var can lower/raise it. */
+const DEFAULT_WARN_TOKENS = 80_000;
+/**
+ * Threshold precedence: CONTEXT_DOCTOR_WARN_TOKENS env var, then the project
+ * budget's maxTokens (.contextdoctorrc), then the default.
+ */
+function warnThreshold(budgetMaxTokens) {
+    const env = Number(process.env.CONTEXT_DOCTOR_WARN_TOKENS);
+    if (env > 0)
+        return env;
+    if (budgetMaxTokens !== undefined && budgetMaxTokens > 0)
+        return budgetMaxTokens;
+    return DEFAULT_WARN_TOKENS;
+}
 /** Re-nudge only after the context grows another 40% — one reminder, not a nag. */
 const REGROWTH_FACTOR = 1.4;
 /**
  * Fast-path gate: text tokens are at least ~4 bytes each and the transcript
  * carries JSON overhead on top, so a file smaller than this cannot possibly
- * hold WARN_TOKENS of context. Lean sessions cost one stat() call — the
+ * hold that many tokens of context. Lean sessions cost one stat() call — the
  * transcript is never even read.
  */
-const MIN_BYTES_FOR_WARN = WARN_TOKENS * 4;
+function minBytesForWarn(threshold) {
+    return threshold * 4;
+}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -44,8 +59,10 @@ export async function runHook() {
         // Fast path 1: a small transcript cannot exceed the threshold — exit on a
         // single stat() without reading the file. This is the every-prompt cost
         // for lean sessions: ~1ms.
+        const { config } = loadConfig(input.cwd ?? process.cwd());
+        const threshold = warnThreshold(config.budget?.maxTokens);
         const sizeBytes = statSync(transcriptPath).size;
-        if (sizeBytes < MIN_BYTES_FOR_WARN)
+        if (sizeBytes < minBytesForWarn(threshold))
             return;
         // Fast path 2: growth gate BEFORE parsing. If the file hasn't grown ~40%
         // since the last full parse, nothing new can trigger — exit without the
@@ -69,7 +86,7 @@ export async function runHook() {
             return;
         const profile = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
         // Record this parse so the next prompts take fast path 2.
-        const shouldWarn = profile.totalTokens >= WARN_TOKENS && profile.totalTokens >= prev.t * REGROWTH_FACTOR;
+        const shouldWarn = profile.totalTokens >= threshold && profile.totalTokens >= prev.t * REGROWTH_FACTOR;
         const nextState = { t: shouldWarn ? profile.totalTokens : prev.t, b: sizeBytes };
         const entries = Object.entries({ ...state, [sessionId]: nextState });
         writeFileSync(statePath(), JSON.stringify(Object.fromEntries(entries.slice(-100))));
@@ -83,11 +100,16 @@ export async function runHook() {
                 ".",
             "Practice context hygiene from here on: summarize large tool results instead of keeping them verbatim, reference earlier content rather than re-reading or re-quoting it, and keep responses lean.",
         ];
+        // A configured budget is the user's own limit — say so first and by name.
+        const verdict = checkBudget(config.budget, profile);
+        if (verdict.overBudget) {
+            lines.splice(1, 0, `This project's context budget is exceeded: ${verdict.breaches.join("; ")}. Treat compaction as a priority, not an option.`);
+        }
         const topFinding = profile.findings.find((f) => f.estSavings > 0);
         if (topFinding) {
             lines.push(`Largest recoverable waste: ${topFinding.message} (${topFinding.suggestion})`);
         }
-        if (profile.totalTokens > WARN_TOKENS * 2) {
+        if (profile.totalTokens > threshold * 2) {
             lines.push("If it fits the flow, offer the user a compaction of the older history.");
         }
         console.log(JSON.stringify({

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-hist
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.6.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.8.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"),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),

package/dist/proxy.d.ts

@@ -14,6 +14,8 @@
 import http from "node:http";
 import { OptimizeOptions } from "./optimize.js";
 export interface ProxyOptions extends OptimizeOptions {
+    /** Per-model-prefix overrides; first match wins, global options otherwise. */
+    routes?: RouteConfig[];
     port?: number;
     /**
      * Bind address. Defaults to 127.0.0.1 — the proxy relays authenticated
@@ -33,5 +35,18 @@ export interface ProxyStats {
     tokensSaved: number;
     /** USD saved on input tokens, when the request's model has a known price. */
     estUsdSaved: number;
+    /** Exact usage reported by upstream responses (both providers, incl. SSE). */
+    upstreamInputTokens: number;
+    upstreamOutputTokens: number;
+    /** Prompt-cache advisories observed on live traffic (unique, capped). */
+    advice: string[];
+}
+/** Per-model-prefix strategy overrides for the proxy (`--config`). */
+export interface RouteConfig {
+    /** Applies when the request body's model starts with this prefix. */
+    modelPrefix: string;
+    strategies?: OptimizeOptions["strategies"];
+    keepRecent?: number;
+    maxToolResultTokens?: number;
 }
 export declare function startProxy(opts?: ProxyOptions): http.Server;

package/dist/proxy.js

@@ -26,6 +26,29 @@ function upstreamFor(url, opts) {
     }
     return undefined;
 }
+/** Pull exact usage out of a response body — JSON or SSE, either provider. */
+function extractUsage(text) {
+    const last = (re) => {
+        let m;
+        let v = -1;
+        while ((m = re.exec(text)) !== null)
+            v = Number(m[1]);
+        return v;
+    };
+    const input = Math.max(last(/"input_tokens"\s*:\s*(\d+)/g), last(/"prompt_tokens"\s*:\s*(\d+)/g));
+    const output = Math.max(last(/"output_tokens"\s*:\s*(\d+)/g), last(/"completion_tokens"\s*:\s*(\d+)/g));
+    if (input < 0 && output < 0)
+        return null;
+    return { input: Math.max(input, 0), output: Math.max(output, 0) };
+}
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
 export function startProxy(opts = {}) {
     const port = opts.port ?? 8787;
     const stats = {
@@ -36,6 +59,17 @@ export function startProxy(opts = {}) {
         tokensAfter: 0,
         tokensSaved: 0,
         estUsdSaved: 0,
+        upstreamInputTokens: 0,
+        upstreamOutputTokens: 0,
+        advice: [],
+    };
+    /** Last stable-prefix fingerprint per model, for cache-invalidation advice. */
+    const prefixFingerprints = new Map();
+    const advise = (msg) => {
+        if (stats.advice.includes(msg) || stats.advice.length >= 10)
+            return;
+        stats.advice.push(msg);
+        console.error(`[context-doctor] cache advisor: ${msg}`);
     };
     const server = http.createServer(async (req, res) => {
         const url = req.url ?? "/";
@@ -70,7 +104,39 @@ export function startProxy(opts = {}) {
             let note = "passthrough";
             if (req.method === "POST" && body && !isMeasurement) {
                 try {
-                    const result = optimizeConversation(body, opts);
+                    // Per-route overrides: first modelPrefix match wins.
+                    let effective = opts;
+                    let requestModel;
+                    try {
+                        const parsedBody = JSON.parse(body);
+                        requestModel = parsedBody.model;
+                        const route = requestModel ? opts.routes?.find((r) => requestModel.startsWith(r.modelPrefix)) : undefined;
+                        if (route) {
+                            effective = {
+                                strategies: route.strategies ?? opts.strategies,
+                                keepRecent: route.keepRecent ?? opts.keepRecent,
+                                maxToolResultTokens: route.maxToolResultTokens ?? opts.maxToolResultTokens,
+                            };
+                        }
+                        // Prompt-cache advisor (Anthropic requests): the proxy sees real
+                        // sequences, so cache-hostile patterns are observable facts here.
+                        if (url.startsWith("/v1/messages") && requestModel) {
+                            const stablePrefix = JSON.stringify(parsedBody.tools ?? null) + JSON.stringify(parsedBody.system ?? null);
+                            if (stablePrefix.length > 4000 && !body.includes("cache_control")) {
+                                advise(`~${Math.round(stablePrefix.length / 4)}+ tokens of stable system/tools on ${requestModel} without cache_control — adding a breakpoint would cut those to ~10% cost per call`);
+                            }
+                            const fp = fnv1a(stablePrefix);
+                            const prev = prefixFingerprints.get(requestModel);
+                            if (prev !== undefined && prev !== fp) {
+                                advise(`system/tools prefix changed between ${requestModel} requests — every change re-bills the whole cached prefix; keep it byte-stable`);
+                            }
+                            prefixFingerprints.set(requestModel, fp);
+                        }
+                    }
+                    catch {
+                        /* body isn't JSON — global opts apply */
+                    }
+                    const result = optimizeConversation(body, effective);
                     const saved = result.tokensBefore - result.tokensAfter;
                     stats.tokensBefore += result.tokensBefore;
                     stats.tokensAfter += result.tokensAfter;
@@ -109,13 +175,26 @@ export function startProxy(opts = {}) {
                     res.setHeader(key, value);
             });
             if (upstream.body) {
-                // Pipe through chunk-by-chunk so SSE streaming works unchanged.
+                // Pipe through chunk-by-chunk so SSE streaming works unchanged, while
+                // accumulating a bounded copy to read exact usage after the fact.
+                const USAGE_SCAN_CAP = 2 * 1024 * 1024;
+                let scanBuf = "";
+                const decoder = new TextDecoder();
                 const reader = upstream.body.getReader();
                 for (;;) {
                     const { done, value } = await reader.read();
                     if (done)
                         break;
                     res.write(value);
+                    if (scanBuf.length < USAGE_SCAN_CAP)
+                        scanBuf += decoder.decode(value, { stream: true });
+                }
+                if (upstream.ok && !isMeasurement) {
+                    const usage = extractUsage(scanBuf);
+                    if (usage) {
+                        stats.upstreamInputTokens += usage.input;
+                        stats.upstreamOutputTokens += usage.output;
+                    }
                 }
             }
             res.end();

package/dist/test/config.test.d.ts

@@ -0,0 +1,2 @@
+/** Project config discovery + context budget verdicts. */
+export {};

package/dist/test/config.test.js

@@ -0,0 +1,64 @@
+/** Project config discovery + context budget verdicts. */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkBudget, loadConfig, RC_FILENAME } from "../config.js";
+const cliPath = join(dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
+test("loadConfig walks up to the nearest .contextdoctorrc", () => {
+    const root = mkdtempSync(join(tmpdir(), "ctxdoc-cfg-"));
+    const nested = join(root, "packages", "app", "src");
+    mkdirSync(nested, { recursive: true });
+    writeFileSync(join(root, RC_FILENAME), JSON.stringify({ budget: { maxTokens: 1234 } }));
+    const loaded = loadConfig(nested);
+    assert.equal(loaded.config.budget?.maxTokens, 1234);
+    assert.equal(loaded.path, join(root, RC_FILENAME));
+});
+test("a malformed rc warns instead of throwing", () => {
+    const root = mkdtempSync(join(tmpdir(), "ctxdoc-cfg-bad-"));
+    writeFileSync(join(root, RC_FILENAME), "{ not json");
+    const warnings = [];
+    const loaded = loadConfig(root, (m) => warnings.push(m));
+    assert.deepEqual(loaded.config, {});
+    assert.equal(warnings.length, 1);
+});
+test("checkBudget flags each configured limit independently", () => {
+    const profile = { totalTokens: 200_000, usagePct: 65, cost: { perCallUsd: 1.2 } };
+    assert.equal(checkBudget(undefined, profile).overBudget, false);
+    assert.equal(checkBudget({}, profile).overBudget, false);
+    const tokens = checkBudget({ maxTokens: 100_000 }, profile);
+    assert.equal(tokens.overBudget, true);
+    assert.match(tokens.breaches[0], /over the 100000 budget/);
+    const cost = checkBudget({ maxCostPerMessageUsd: 0.5 }, profile);
+    assert.match(cost.breaches[0], /per message/);
+    const window = checkBudget({ maxWindowPct: 50 }, profile);
+    assert.match(window.breaches[0], /% of the window/);
+    const all = checkBudget({ maxTokens: 100_000, maxCostPerMessageUsd: 0.5, maxWindowPct: 50 }, profile);
+    assert.equal(all.breaches.length, 3);
+    const within = checkBudget({ maxTokens: 500_000, maxWindowPct: 90 }, profile);
+    assert.equal(within.overBudget, false);
+});
+test("analyze reports budget status from the project rc", async () => {
+    const root = mkdtempSync(join(tmpdir(), "ctxdoc-cfg-cli-"));
+    writeFileSync(join(root, RC_FILENAME), JSON.stringify({ budget: { maxTokens: 10 } }));
+    const chat = join(root, "chat.json");
+    writeFileSync(chat, JSON.stringify({ messages: [{ role: "user", content: "a fairly long message ".repeat(40) }] }));
+    const out = await new Promise((resolve, reject) => {
+        execFile(process.execPath, [cliPath, "analyze", chat, "--model", "claude-sonnet-5"], { cwd: root }, (err, stdout) => err ? reject(err) : resolve(stdout));
+    });
+    assert.ok(out.includes("OVER BUDGET"), `expected budget breach in output:\n${out}`);
+    assert.ok(out.includes(RC_FILENAME), "names the rc file responsible");
+});
+test("analyze stays quiet about budgets when no rc exists", async () => {
+    const root = mkdtempSync(join(tmpdir(), "ctxdoc-cfg-none-"));
+    const chat = join(root, "chat.json");
+    writeFileSync(chat, JSON.stringify({ messages: [{ role: "user", content: "hello" }] }));
+    const out = await new Promise((resolve, reject) => {
+        // HOME override keeps a real ~/.contextdoctorrc from leaking into the test.
+        execFile(process.execPath, [cliPath, "analyze", chat], { cwd: root, env: { ...process.env, HOME: root } }, (err, stdout) => err ? reject(err) : resolve(stdout));
+    });
+    assert.ok(!out.includes("BUDGET"), "no budget chatter without an rc");
+});

package/dist/test/dashboard.test.d.ts

@@ -0,0 +1,2 @@
+/** Dashboard: local-only server, real data shape, self-contained page. */
+export {};

package/dist/test/dashboard.test.js

@@ -0,0 +1,37 @@
+/** Dashboard: local-only server, real data shape, self-contained page. */
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { startDashboard, collectDashboardData } from "../dashboard.js";
+const server = startDashboard({ port: 0 });
+await new Promise((r) => server.once("listening", () => r()));
+const port = server.address().port;
+after(() => server.close());
+test("binds loopback only", () => {
+    assert.equal(server.address().address, "127.0.0.1");
+});
+test("/api/data returns the documented shape", async () => {
+    const data = (await (await fetch(`http://127.0.0.1:${port}/api/data`)).json());
+    for (const key of ["generatedAt", "totals", "daily", "sessions", "proxy", "budget"]) {
+        assert.ok(key in data, `missing ${key}`);
+    }
+    for (const key of ["tokensSaved", "usdSaved", "checks", "warnings", "optimizeRuns"]) {
+        assert.equal(typeof data.totals[key], "number", `totals.${key} must be numeric`);
+    }
+    assert.ok(Array.isArray(data.daily) && Array.isArray(data.sessions));
+});
+test("page is self-contained: no external requests", async () => {
+    const html = await (await fetch(`http://127.0.0.1:${port}/`)).text();
+    assert.ok(html.startsWith("<!doctype html>"));
+    // Only same-origin data fetch; nothing pulled from the network.
+    assert.ok(!/https?:\/\//.test(html.replace(/http:\/\/127\.0\.0\.1/g, "")), "page must not reference remote origins");
+    assert.ok(html.includes("/api/data"));
+    // Accessibility affordances required by the house chart rules.
+    assert.ok(html.includes("Table view"), "table view present");
+    assert.ok(html.includes('role="img"') || html.includes("aria-label"), "charts labelled");
+    assert.ok(html.includes("prefers-color-scheme: dark"), "dark mode selected, not flipped");
+});
+test("collectDashboardData works without a proxy running", async () => {
+    const data = await collectDashboardData(59999); // nothing listens here
+    assert.equal(data.proxy, null);
+    assert.ok(data.totals.tokensSaved >= 0);
+});

package/dist/test/proxy.test.js

@@ -32,6 +32,7 @@ const upstream = http.createServer((req, res) => {
         receivedApiKey = req.headers["x-api-key"];
         res.writeHead(200, { "content-type": "text/event-stream" });
         res.write("event: message_start\ndata: {}\n\n");
+        res.write('event: message_delta\ndata: {"usage":{"input_tokens":120,"output_tokens":45}}\n\n');
         res.write("event: message_stop\ndata: {}\n\n");
         res.end();
     });
@@ -69,6 +70,49 @@ test("/stats reports cumulative savings with dollar estimate", async () => {
     assert.ok(stats.tokensSaved > 1000, `saved tokens tracked (${stats.tokensSaved})`);
     assert.ok(stats.estUsdSaved > 0, "dollar savings estimated from the request's model");
 });
+test("response usage is captured from the SSE stream; cache advisor fires on prefix churn", async () => {
+    // Second request with a DIFFERENT system prompt on the same model → advisory.
+    const churned = JSON.parse(payload);
+    churned.system = "You are helpful. TODAY IS A NEW DAY."; // classic cache-buster
+    churned.tools = [{ name: "t", description: "x".repeat(5000), input_schema: { type: "object" } }];
+    const first = JSON.parse(payload);
+    first.tools = churned.tools;
+    for (const body of [first, churned]) {
+        await fetch(`http://localhost:${proxyPort}/v1/messages`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-api-key": "sk-test-not-real" },
+            body: JSON.stringify(body),
+        });
+    }
+    const stats = (await (await fetch(`http://localhost:${proxyPort}/stats`)).json());
+    // Mock upstream reports usage in its SSE close event (added below).
+    assert.ok(stats.upstreamInputTokens >= 100, `usage input captured: ${stats.upstreamInputTokens}`);
+    assert.ok(stats.upstreamOutputTokens >= 40, `usage output captured: ${stats.upstreamOutputTokens}`);
+    assert.ok(stats.advice.some((a) => a.includes("prefix changed")), `prefix-churn advisory expected, got: ${JSON.stringify(stats.advice)}`);
+    assert.ok(stats.advice.some((a) => a.includes("cache_control")), "missing-cache_control advisory expected");
+});
+test("per-route config: empty strategy list disables optimization for matching models", async () => {
+    const { startProxy } = await import("../proxy.js");
+    const routed = startProxy({
+        port: 0,
+        anthropicUpstream: `http://localhost:${upstreamPort}`,
+        routes: [{ modelPrefix: "claude-sonnet", strategies: [] }],
+    });
+    await new Promise((r) => routed.once("listening", () => r()));
+    const routedPort = routed.address().port;
+    try {
+        const sent = payload;
+        await fetch(`http://localhost:${routedPort}/v1/messages`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: sent,
+        });
+        assert.equal(received.length, sent.length, "route with no strategies must pass body through unmodified");
+    }
+    finally {
+        routed.close();
+    }
+});
 test("unsupported paths get a clear 404, health stays up", async () => {
     const notFound = await fetch(`http://localhost:${proxyPort}/v1/nope`, { method: "POST", body: "{}" });
     assert.equal(notFound.status, 404);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "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.",
   "keywords": [
     "llm",
@@ -41,7 +41,7 @@
     "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
     "prepublishOnly": "npm run build",
     "dev": "tsc --watch",
-    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/hook.test.js dist/test/mcp-http.test.js dist/test/doctor.test.js dist/test/watch.test.js dist/test/chatgpt-export.test.js"
+    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/hook.test.js dist/test/mcp-http.test.js dist/test/doctor.test.js dist/test/watch.test.js dist/test/chatgpt-export.test.js dist/test/config.test.js dist/test/dashboard.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",