context-doctor 0.8.0 → 0.10.0

package/README.md

@@ -88,9 +88,10 @@ 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 analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates |
+| `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; `--strategy prune-history` for consented lossy compaction |
-| `context-doctor session [file]` | Profile a Claude Code session transcript (defaults to your most recent; `--list` to browse) — also reads ChatGPT data exports (`conversations.json`) |
+| `context-doctor session [file]` | Profile a Claude Code session: live context, findings, **measured tokens and prompt-cache economics**. Also reads ChatGPT data exports (`conversations.json`) |
+| `context-doctor cursor [--list]` | Profile a chat from Cursor's local history (both storage formats) |
 | `context-doctor report` | Machine-wide impact report: exact proxy savings, hook activity, recoverable waste in recent sessions |
 | `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 |
@@ -245,6 +246,8 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 - **Oversized tool results** — the #1 context killer in agent loops
 - **Duplicate content** — the same doc/result pasted twice
 - **Near-duplicates** — the same doc re-pasted with different surrounding words (shingle similarity, ≥60%)
+- **Repeated file reads** — the same file pulled in three or more times, every copy still in context
+- **Retained error output** — stack traces and failed commands kept verbatim long after the fix landed
 - **Repeated identical tool calls** — a signal your agent forgot earlier results
 - **Base64 / binary blobs** in text content
 - **Long history** past the point where models track the middle
@@ -296,6 +299,26 @@ Drop a `.contextdoctorrc` in a project (or your home directory) and context-doct
 
 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.
 
+## Prompt-cache economics (Claude Code sessions)
+
+Caching is the largest lever on LLM cost, and transcripts record exactly how it went — so `session` reports it as fact rather than estimate:
+
+```
+Prompt cache: 95.6% of input served from cache across 1117 requests
+  read 558.6M · written 25.5M · uncached 2k
+  input cost $438.88 — caching saved $2481.89 against $2920.76 uncached (list prices)
+```
+
+A cache read bills at ~10% of input while a write bills at ~125%, so a session that keeps invalidating its prefix can cost *more* than one with no caching at all. context-doctor warns on the two failure modes: a **low hit rate** (something early in the prompt changes every request) and **cache churn** (writes rivalling reads).
+
+## Enforce a budget in CI
+
+```bash
+npx context-doctor analyze conversation.json --fail-over-budget
+```
+
+Exits 1 when the `.contextdoctorrc` budget is breached, so a pull request can be gated on context size the same way it is gated on tests.
+
 ## Performance: what context-doctor itself costs
 
 A tool that promises speed must be near-free. Measured overhead per touchpoint:
@@ -310,9 +333,16 @@ A tool that promises speed must be near-free. Measured overhead per touchpoint:
 
 Net effect is strongly negative overhead: the tokens these touchpoints save on every subsequent call dwarf what they cost.
 
-## Why token counts are "~" (and how to make them exact)
+## Why token counts are "~" (and where they are exact)
+
+Counting exactly needs each provider's tokenizer, so the default is a calibrated chars-per-token heuristic (denser for code and JSON). It is good enough to rank what is heavy and to measure the effect of a fix, and it keeps the tool offline and zero-config.
 
-Want exact numbers? `analyze --exact` uses the **Anthropic count-tokens API** for Claude models (set `ANTHROPIC_API_KEY`; opt-in network call, key never stored) or **tiktoken** for GPT models (install it next to context-doctor) — and reports how far off the heuristic was.
+Two ways to get real numbers instead:
+
+- **`analyze --exact`** uses the Anthropic count-tokens API for Claude models (set `ANTHROPIC_API_KEY`; opt-in network call, key never stored) or tiktoken for GPT models (install it alongside), and reports how far the heuristic drifted.
+- **Sessions report measured tokens automatically.** Claude Code transcripts record what the API actually charged, so `session`, the hook and the reports use that figure when it is present — no key, no estimate.
+
+One honest caveat worth knowing: a transcript stores the conversation, **not** the harness's system prompt, tool schemas or skills. Measured against the API's own numbers here, a message-only estimate undercounts the true context by roughly 60%. That is why sessions prefer the reported figure, and why the message breakdown is labelled as covering messages only.
 
 
 
@@ -337,6 +367,10 @@ Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doc
 
 Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, and remember `dist/` is committed — run `npm run build` before committing so the CI dist-sync check passes.
 
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the six rules that keep this tool trustworthy (no API keys, nothing leaves the machine, no silent data loss, measurements not guesses, the hot path stays cheap, tests with every change) and a list of good first issues. What is planned next lives in [ROADMAP.md](./ROADMAP.md).
+
 ## License
 
 MIT © [gAI Ventures](https://gai.ventures)

package/dist/cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt-cache analysis for Claude Code sessions.
+ *
+ * Transcripts record what the API actually charged per request — including
+ * cache reads and cache writes — so cache behaviour can be reported as fact
+ * rather than estimated. This is usually the largest single lever on cost:
+ * a cached read bills at ~10% of input, while a cache write bills at ~125%,
+ * so a session that keeps invalidating its prefix pays more than one with no
+ * caching at all.
+ */
+export interface CacheUsage {
+    requests: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    uncachedTokens: number;
+    /** Share of input tokens served from cache (0-1). */
+    hitRate: number;
+    model?: string;
+    /** What the input actually cost, at list prices. */
+    paidUsd?: number;
+    /** What the same input would have cost with no caching at all. */
+    uncachedUsd?: number;
+    /** paidUsd vs uncachedUsd — positive means caching is paying off. */
+    savedUsd?: number;
+    /** USD spent on cache writes; high values mean the prefix keeps changing. */
+    writeUsd?: number;
+}
+export declare function analyzeCacheUsage(transcriptPath: string): CacheUsage | null;
+/** One-paragraph verdict for humans, or null when there is nothing to say. */
+export declare function renderCacheReport(usage: CacheUsage | null): string | null;

package/dist/cache.js

@@ -0,0 +1,97 @@
+/**
+ * Prompt-cache analysis for Claude Code sessions.
+ *
+ * Transcripts record what the API actually charged per request — including
+ * cache reads and cache writes — so cache behaviour can be reported as fact
+ * rather than estimated. This is usually the largest single lever on cost:
+ * a cached read bills at ~10% of input, while a cache write bills at ~125%,
+ * so a session that keeps invalidating its prefix pays more than one with no
+ * caching at all.
+ */
+import { readFileSync } from "node:fs";
+import { pricingFor } from "./pricing.js";
+/** Cache pricing multipliers relative to the base input rate. */
+const CACHE_WRITE_MULTIPLIER = 1.25;
+export function analyzeCacheUsage(transcriptPath) {
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let requests = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    let uncachedTokens = 0;
+    let model;
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.type !== "assistant" || !entry.message)
+            continue;
+        const usage = entry.message.usage;
+        if (!usage)
+            continue;
+        requests++;
+        cacheReadTokens += usage.cache_read_input_tokens ?? 0;
+        cacheWriteTokens += usage.cache_creation_input_tokens ?? 0;
+        uncachedTokens += usage.input_tokens ?? 0;
+        if (typeof entry.message.model === "string")
+            model = entry.message.model;
+    }
+    if (requests === 0)
+        return null;
+    const totalInput = cacheReadTokens + cacheWriteTokens + uncachedTokens;
+    const usage = {
+        requests,
+        cacheReadTokens,
+        cacheWriteTokens,
+        uncachedTokens,
+        hitRate: totalInput > 0 ? cacheReadTokens / totalInput : 0,
+        model,
+    };
+    const pricing = pricingFor(model);
+    if (pricing) {
+        const perM = (tokens, rate) => (tokens / 1_000_000) * rate;
+        const readUsd = perM(cacheReadTokens, pricing.cacheReadPerM);
+        const writeUsd = perM(cacheWriteTokens, pricing.inputPerM * CACHE_WRITE_MULTIPLIER);
+        const freshUsd = perM(uncachedTokens, pricing.inputPerM);
+        usage.paidUsd = readUsd + writeUsd + freshUsd;
+        usage.uncachedUsd = perM(totalInput, pricing.inputPerM);
+        usage.savedUsd = usage.uncachedUsd - usage.paidUsd;
+        usage.writeUsd = writeUsd;
+    }
+    return usage;
+}
+/** One-paragraph verdict for humans, or null when there is nothing to say. */
+export function renderCacheReport(usage) {
+    if (!usage)
+        return null;
+    const pct = (usage.hitRate * 100).toFixed(1);
+    const lines = [];
+    const fmt = (n) => (n >= 1 ? `$${n.toFixed(2)}` : `$${n.toFixed(3)}`);
+    const tok = (n) => n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(n);
+    lines.push(`Prompt cache: ${pct}% of input served from cache across ${usage.requests} requests`);
+    lines.push(`  read ${tok(usage.cacheReadTokens)} · written ${tok(usage.cacheWriteTokens)} · uncached ${tok(usage.uncachedTokens)}`);
+    if (usage.paidUsd !== undefined && usage.uncachedUsd !== undefined && usage.savedUsd !== undefined) {
+        lines.push(`  input cost ${fmt(usage.paidUsd)} — caching saved ${fmt(usage.savedUsd)} against ${fmt(usage.uncachedUsd)} uncached (list prices)`);
+    }
+    // A cache write costs 1.25x input while a read costs 0.1x, so writes that
+    // rival reads mean the prefix keeps changing and caching is losing money.
+    const writeShare = usage.cacheReadTokens > 0 ? usage.cacheWriteTokens / usage.cacheReadTokens : Infinity;
+    if (usage.hitRate < 0.5 && usage.requests > 5) {
+        lines.push("  ⚠ Low hit rate: something early in the prompt changes between requests. Keep the system prompt, tool list and reference docs byte-stable and put volatile content last.");
+    }
+    else if (writeShare > 0.5) {
+        lines.push("  ⚠ Cache churn: writes are large relative to reads, and a write costs 1.25x input against 0.1x for a read. The cached prefix is being rebuilt often.");
+    }
+    return lines.join("\n");
+}

package/dist/cli.js

@@ -25,6 +25,8 @@ import { runWatch } from "./watch.js";
 import { exactTokenCount } from "./exact.js";
 import { checkBudget, loadConfig } from "./config.js";
 import { startDashboard } from "./dashboard.js";
+import { listCursorChats, parseCursorChat } from "./cursor.js";
+import { analyzeCacheUsage, renderCacheReport } from "./cache.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -35,8 +37,9 @@ Usage:
   context-doctor install                        Wire the MCP server + skill into Claude Desktop,
                                                 Claude Code, and Cursor automatically
   context-doctor uninstall                      Undo install
-  context-doctor session [file]                 Profile a Claude Code session transcript
-                                                (default: the most recent session; --list to browse)
+  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
   context-doctor hook                           Claude Code UserPromptSubmit hook (installed
                                                 automatically by \`install\`; reads hook JSON on stdin)
   context-doctor report                         Impact report: exact proxy savings, hook activity,
@@ -62,6 +65,8 @@ Options:
   --exact                 (analyze) Add an exact token count: Anthropic count-tokens API for
                           Claude models (needs ANTHROPIC_API_KEY), tiktoken for GPT (if installed)
   --json                  Machine-readable output
+  --fail-over-budget      (analyze/session) Exit 1 when the .contextdoctorrc budget is
+                          exceeded — lets CI gate a pull request on context size
   --out <file>            (optimize) Write result to file instead of stdout
   --strategy <id>         (optimize) Strategy to run; repeatable.
                           Available: dedupe, trim-tool-results, strip-base64, prune-history
@@ -84,7 +89,7 @@ Examples:
           export OPENAI_BASE_URL=http://localhost:8787/v1
 `;
 function parseArgs(argv) {
-    const args = { json: false, strategies: [], list: false, exact: false };
+    const args = { json: false, strategies: [], list: false, exact: false, failOverBudget: false };
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -102,6 +107,9 @@ function parseArgs(argv) {
             case "--exact":
                 args.exact = true;
                 break;
+            case "--fail-over-budget":
+                args.failOverBudget = true;
+                break;
             case "--model":
                 args.model = argv[++i];
                 break;
@@ -146,7 +154,7 @@ function parseArgs(argv) {
 function printBudgetStatus(profile, loaded) {
     const budget = loaded.config.budget;
     if (!budget || !loaded.path)
-        return;
+        return false;
     const verdict = checkBudget(budget, profile);
     console.log("");
     if (verdict.overBudget) {
@@ -157,6 +165,14 @@ function printBudgetStatus(profile, loaded) {
     else {
         console.log(`Within budget (${loaded.path}).`);
     }
+    return verdict.overBudget;
+}
+/** Exit 1 when the caller asked CI to fail on a breach. */
+function applyBudgetGate(overBudget, failOverBudget) {
+    if (overBudget && failOverBudget) {
+        console.error("context-doctor: over budget (--fail-over-budget)");
+        process.exitCode = 1;
+    }
 }
 function readInput(file) {
     if (file === "-")
@@ -185,6 +201,45 @@ function main() {
         void buildImpactReport(args.port).then((r) => console.log(r));
         return;
     }
+    if (args.command === "cursor") {
+        let chats;
+        try {
+            chats = listCursorChats();
+        }
+        catch (e) {
+            console.error(`Could not read Cursor history: ${e.message}`);
+            process.exit(1);
+        }
+        if (chats.length === 0) {
+            console.error("No Cursor chats found (looked in Cursor's global and workspace storage).");
+            process.exit(1);
+        }
+        if (args.list) {
+            for (const c of chats) {
+                console.log(`${String(c.messageCount).padStart(5)} msgs  ${(c.title ?? "(untitled)").slice(0, 48).padEnd(50)} ${c.composerId}`);
+            }
+            return;
+        }
+        const chat = args.file ? chats.find((c) => c.composerId === args.file) ?? chats[0] : chats[0];
+        const parsed = parseCursorChat(chat);
+        const profile = profileConversation(parseConversation(parsed.conversationJson), args.model ?? parsed.model);
+        if (args.json) {
+            console.log(JSON.stringify({ chat: { id: chat.composerId, title: chat.title }, profile }, null, 2));
+        }
+        else {
+            console.log(`Cursor chat: ${chat.title ?? "(untitled)"}\nId:          ${chat.composerId}\n`);
+            console.log(renderProfile(profile));
+            if (parsed.reportedInputTokens) {
+                console.log("");
+                console.log(`Measured context (reported by the API on the last request): ${parsed.reportedInputTokens} tokens.\n` +
+                    "That figure includes the harness's system prompt, tool schemas and skills, which the\n" +
+                    "transcript does not record — so it is larger than the breakdown above, which covers\n" +
+                    "conversation messages only. Findings and savings apply to the messages.");
+            }
+            printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`)));
+        }
+        return;
+    }
     if (args.command === "session") {
         if (args.list) {
             const sessions = listSessions();
@@ -215,9 +270,25 @@ function main() {
             console.log(JSON.stringify({ session: { path: parsed.path, title: parsed.title }, profile }, null, 2));
         }
         else {
-            console.log(`Session: ${parsed.title ?? "(untitled)"}\nFile:    ${parsed.path}\n`);
+            console.log(`Session: ${parsed.title ?? "(untitled)"}\nFile:    ${parsed.path}`);
+            if (parsed.compactedAway) {
+                console.log(`Note:    ${parsed.compactedAway} earlier message(s) were compacted away and are NOT counted below — this is the live context the model still sees.`);
+            }
+            console.log("");
             console.log(renderProfile(profile));
-            printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`)));
+            if (parsed.reportedInputTokens) {
+                console.log("");
+                console.log(`Measured context (reported by the API on the last request): ${parsed.reportedInputTokens} tokens.\n` +
+                    "That figure includes the harness's system prompt, tool schemas and skills, which the\n" +
+                    "transcript does not record — so it is larger than the breakdown above, which covers\n" +
+                    "conversation messages only. Findings and savings apply to the messages.");
+            }
+            const cache = renderCacheReport(analyzeCacheUsage(path));
+            if (cache) {
+                console.log("");
+                console.log(cache);
+            }
+            applyBudgetGate(printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`))), args.failOverBudget);
         }
         return;
     }
@@ -270,7 +341,9 @@ function main() {
         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);
+            applyBudgetGate(printBudgetStatus(profile, loaded), args.failOverBudget);
+        else
+            applyBudgetGate(checkBudget(loaded.config.budget, profile).overBudget, args.failOverBudget);
         if (args.exact) {
             void exactTokenCount(input, args.model).then((exact) => {
                 if (exact.tokens !== undefined) {

package/dist/cursor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Cursor chat history: profile the conversations Cursor stores locally.
+ *
+ * Cursor keeps chats in SQLite (`state.vscdb`) rather than files:
+ *   composerData:<composerId>  → { name, conversation: [{bubbleId, type}] }
+ *   bubbleId:<composerId>:<id> → { type: 1|2, text, toolFormerData, ... }
+ * Message text lives in the per-bubble rows, so a conversation is assembled by
+ * walking the header list and looking up each bubble.
+ *
+ * Reading needs SQLite. Node 22.5+ ships `node:sqlite`; older runtimes fall
+ * back to the `sqlite3` CLI when it is installed. When neither is available we
+ * say so plainly instead of failing obscurely.
+ */
+import type { ParsedSession } from "./session.js";
+export interface CursorChat {
+    composerId: string;
+    title?: string;
+    dbPath: string;
+    messageCount: number;
+}
+/** Every Cursor state database on this machine, newest first. */
+export declare function findCursorDatabases(): string[];
+interface Row {
+    [column: string]: string | number | null;
+}
+/**
+ * Run a read-only query against a Cursor database.
+ *
+ * Two hard rules learned the expensive way:
+ *  - NEVER copy the file. A real Cursor history is gigabytes; snapshotting it
+ *    per invocation fills the disk.
+ *  - Project in SQL, not in JS. Composer rows hold megabytes of JSON each, so
+ *    listing pulls only the fields it needs via json_extract.
+ * SQLite allows concurrent readers, so opening the live database read-only is
+ * safe while Cursor is running.
+ */
+export declare function queryRows(dbPath: string, sql: string): Row[];
+/** List Cursor chats, biggest first. */
+export declare function listCursorChats(limit?: number): CursorChat[];
+/**
+ * Assemble one Cursor chat into a conversation this tool can profile.
+ * Tool calls are folded in as tool_use/tool_result blocks so the profiler's
+ * tool-result findings apply to Cursor chats exactly as they do elsewhere.
+ */
+export declare function parseCursorChat(chat: CursorChat): ParsedSession;
+export {};

package/dist/cursor.js

@@ -0,0 +1,203 @@
+/**
+ * Cursor chat history: profile the conversations Cursor stores locally.
+ *
+ * Cursor keeps chats in SQLite (`state.vscdb`) rather than files:
+ *   composerData:<composerId>  → { name, conversation: [{bubbleId, type}] }
+ *   bubbleId:<composerId>:<id> → { type: 1|2, text, toolFormerData, ... }
+ * Message text lives in the per-bubble rows, so a conversation is assembled by
+ * walking the header list and looking up each bubble.
+ *
+ * Reading needs SQLite. Node 22.5+ ships `node:sqlite`; older runtimes fall
+ * back to the `sqlite3` CLI when it is installed. When neither is available we
+ * say so plainly instead of failing obscurely.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+const require = createRequire(import.meta.url);
+/** Cursor bubble type codes. */
+const BUBBLE_USER = 1;
+/** Header list for a composer record, whichever shape it uses. */
+function headersOf(data) {
+    if (Array.isArray(data.conversation) && data.conversation.length > 0)
+        return data.conversation;
+    return data.fullConversationHeadersOnly ?? [];
+}
+/** Cursor's per-user storage root, per platform. */
+function cursorStorageDirs() {
+    const home = homedir();
+    const root = platform() === "darwin"
+        ? join(home, "Library", "Application Support", "Cursor", "User")
+        : platform() === "win32"
+            ? join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Cursor", "User")
+            : join(home, ".config", "Cursor", "User");
+    const dirs = [];
+    const global = join(root, "globalStorage");
+    if (existsSync(global))
+        dirs.push(global);
+    const ws = join(root, "workspaceStorage");
+    if (existsSync(ws)) {
+        try {
+            for (const entry of readdirSync(ws))
+                dirs.push(join(ws, entry));
+        }
+        catch {
+            /* unreadable — skip */
+        }
+    }
+    return dirs;
+}
+/** Every Cursor state database on this machine, newest first. */
+export function findCursorDatabases() {
+    const dbs = [];
+    for (const dir of cursorStorageDirs()) {
+        const db = join(dir, "state.vscdb");
+        if (!existsSync(db))
+            continue;
+        try {
+            dbs.push({ path: db, mtime: statSync(db).mtimeMs });
+        }
+        catch {
+            /* unreadable — skip */
+        }
+    }
+    return dbs.sort((a, b) => b.mtime - a.mtime).map((d) => d.path);
+}
+/**
+ * Run a read-only query against a Cursor database.
+ *
+ * Two hard rules learned the expensive way:
+ *  - NEVER copy the file. A real Cursor history is gigabytes; snapshotting it
+ *    per invocation fills the disk.
+ *  - Project in SQL, not in JS. Composer rows hold megabytes of JSON each, so
+ *    listing pulls only the fields it needs via json_extract.
+ * SQLite allows concurrent readers, so opening the live database read-only is
+ * safe while Cursor is running.
+ */
+export function queryRows(dbPath, sql) {
+    try {
+        // Preferred: Node's built-in SQLite (22.5+).
+        const { DatabaseSync } = require("node:sqlite");
+        const db = new DatabaseSync(dbPath, { readOnly: true });
+        try {
+            return db.prepare(sql).all();
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (nodeSqliteErr) {
+        // Fallback: the sqlite3 CLI, if the user has it.
+        try {
+            const out = execFileSync("sqlite3", ["-readonly", "-json", dbPath, sql], {
+                encoding: "utf8",
+                maxBuffer: 512 * 1024 * 1024,
+                stdio: ["ignore", "pipe", "ignore"], // a missing table is expected on some DBs
+            });
+            return out.trim() ? JSON.parse(out) : [];
+        }
+        catch {
+            throw new Error("reading Cursor chats needs SQLite: Node 22.5+ (built-in) or the sqlite3 command. " +
+                `Neither worked here (${nodeSqliteErr.message}).`);
+        }
+    }
+}
+/** List Cursor chats, biggest first. */
+export function listCursorChats(limit = 20) {
+    const chats = [];
+    for (const dbPath of findCursorDatabases()) {
+        let rows;
+        try {
+            // json_extract keeps megabyte-sized composer blobs in the database.
+            rows = queryRows(dbPath, "SELECT key, json_extract(value, '$.name') AS name, " +
+                "COALESCE(json_array_length(value, '$.fullConversationHeadersOnly'), " +
+                "json_array_length(value, '$.conversation'), 0) AS n " +
+                "FROM cursorDiskKV WHERE key LIKE 'composerData:%'");
+        }
+        catch {
+            continue; // no composer table (older Cursor) or no SQLite — skip
+        }
+        for (const row of rows) {
+            const count = Number(row.n ?? 0);
+            if (count === 0)
+                continue;
+            chats.push({
+                composerId: String(row.key).slice("composerData:".length),
+                title: row.name == null ? undefined : String(row.name),
+                dbPath,
+                messageCount: count,
+            });
+        }
+    }
+    return chats.sort((a, b) => b.messageCount - a.messageCount).slice(0, limit);
+}
+function safeParse(raw) {
+    if (typeof raw !== "string")
+        return raw ?? {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function stringify(value) {
+    return typeof value === "string" ? value : JSON.stringify(value ?? "");
+}
+/**
+ * Assemble one Cursor chat into a conversation this tool can profile.
+ * Tool calls are folded in as tool_use/tool_result blocks so the profiler's
+ * tool-result findings apply to Cursor chats exactly as they do elsewhere.
+ */
+export function parseCursorChat(chat) {
+    const id = chat.composerId.replace(/[^a-zA-Z0-9-]/g, "");
+    const header = queryRows(chat.dbPath, `SELECT value FROM cursorDiskKV WHERE key = 'composerData:${id}'`)[0];
+    const record = header ? JSON.parse(String(header.value)) : {};
+    const conversation = headersOf(record);
+    const bubbleRows = queryRows(chat.dbPath, `SELECT key, value FROM cursorDiskKV WHERE key LIKE 'bubbleId:${id}:%'`);
+    const byId = new Map();
+    for (const row of bubbleRows) {
+        try {
+            byId.set(String(row.key).split(":").pop() ?? "", JSON.parse(String(row.value)));
+        }
+        catch {
+            /* malformed bubble — skip */
+        }
+    }
+    const messages = [];
+    for (const entry of conversation) {
+        // Legacy entries carry their own text; modern ones point at a bubble row.
+        const bubble = (entry.bubbleId ? byId.get(entry.bubbleId) : undefined) ?? entry;
+        const role = (bubble.type ?? entry.type) === BUBBLE_USER ? "user" : "assistant";
+        const text = typeof bubble.text === "string" ? bubble.text : "";
+        const tool = bubble.toolFormerData;
+        if (tool && (tool.name || tool.rawArgs || tool.result)) {
+            if (text)
+                messages.push({ role, content: text });
+            messages.push({
+                role: "assistant",
+                content: [{ type: "tool_use", id: entry.bubbleId ?? "tool", name: String(tool.name ?? "tool"), input: safeParse(tool.rawArgs) }],
+            });
+            if (tool.result !== undefined) {
+                messages.push({
+                    role: "user",
+                    content: [{ type: "tool_result", tool_use_id: entry.bubbleId ?? "tool", content: stringify(tool.result) }],
+                });
+            }
+            continue;
+        }
+        if (!text)
+            continue;
+        messages.push({ role, content: text });
+    }
+    return {
+        conversationJson: JSON.stringify({ messages }),
+        title: chat.title,
+        // Cursor does not record the model per chat in a stable place; leaving it
+        // unset keeps window/cost math honest rather than guessed.
+        messageCount: messages.length,
+        path: `${chat.dbPath}#${chat.composerId}`,
+    };
+}

package/dist/hook.js

@@ -85,23 +85,31 @@ export async function runHook() {
         if (parsed.messageCount === 0)
             return;
         const profile = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
+        // Prefer the API's own figure when the transcript carries it: it includes
+        // the system prompt and tool schemas the transcript omits, so it is the
+        // real context size rather than a message-only estimate.
+        const liveTokens = parsed.reportedInputTokens ?? profile.totalTokens;
         // Record this parse so the next prompts take fast path 2.
-        const shouldWarn = profile.totalTokens >= threshold && profile.totalTokens >= prev.t * REGROWTH_FACTOR;
-        const nextState = { t: shouldWarn ? profile.totalTokens : prev.t, b: sizeBytes };
+        const shouldWarn = liveTokens >= threshold && liveTokens >= prev.t * REGROWTH_FACTOR;
+        const nextState = { t: shouldWarn ? liveTokens : prev.t, b: sizeBytes };
         const entries = Object.entries({ ...state, [sessionId]: nextState });
         writeFileSync(statePath(), JSON.stringify(Object.fromEntries(entries.slice(-100))));
-        recordLedger({ ev: "check", sid: sessionId.slice(0, 12), tok: profile.totalTokens, warn: shouldWarn });
+        recordLedger({ ev: "check", sid: sessionId.slice(0, 12), tok: liveTokens, warn: shouldWarn });
         if (!shouldWarn)
             return;
+        const windowPct = profile.contextWindow ? (liveTokens / profile.contextWindow) * 100 : undefined;
+        const costPerCall = profile.cost && profile.totalTokens > 0
+            ? (profile.cost.perCallUsd * liveTokens) / profile.totalTokens
+            : undefined;
         const lines = [
-            `This session's context is at ~${formatTokens(profile.totalTokens)} tokens` +
-                (profile.usagePct ? ` (${profile.usagePct.toFixed(0)}% of the window)` : "") +
-                (profile.cost ? `, costing ~${formatUsd(profile.cost.perCallUsd)} of input per message` : "") +
+            `This session's context is at ~${formatTokens(liveTokens)} tokens` +
+                (windowPct !== undefined ? ` (${windowPct.toFixed(0)}% of the window)` : "") +
+                (costPerCall !== undefined ? `, costing ~${formatUsd(costPerCall)} of input per message` : "") +
                 ".",
             "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);
+        const verdict = checkBudget(config.budget, { ...profile, totalTokens: liveTokens, usagePct: windowPct });
         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.`);
         }
@@ -109,7 +117,7 @@ export async function runHook() {
         if (topFinding) {
             lines.push(`Largest recoverable waste: ${topFinding.message} (${topFinding.suggestion})`);
         }
-        if (profile.totalTokens > threshold * 2) {
+        if (liveTokens > threshold * 2) {
             lines.push("If it fits the flow, offer the user a compaction of the older history.");
         }
         console.log(JSON.stringify({