context-doctor 0.7.0 → 0.9.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 |
 
@@ -283,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:
@@ -297,9 +310,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.
+
+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.
 
-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.
+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.
 
 
 

package/dist/cli.js

@@ -23,6 +23,9 @@ 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";
+import { listCursorChats, parseCursorChat } from "./cursor.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -33,18 +36,26 @@ 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,
                                                 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.
 
@@ -133,6 +144,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");
@@ -144,6 +171,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
@@ -156,6 +187,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();
@@ -186,8 +256,20 @@ 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));
+            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;
     }
@@ -200,7 +282,8 @@ function main() {
         return;
     }
     if (args.command === "proxy") {
-        let routes;
+        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;
@@ -216,9 +299,9 @@ function main() {
             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
     }
@@ -235,8 +318,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) {
@@ -253,10 +339,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/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}`,
+    };
+}