@unpolarize/code-sessions 0.2.0 → 0.4.0

package/dist/{chunk-HV6FQJPS.js → chunk-3VPXOUIE.js}

@@ -135,11 +135,13 @@ Commands:
   install-hooks   Install Claude Code hooks that feed the daemon
   install-skills  Install the cs-label-session skill into agents [--agent claude|codex|grok|all]
   hook            (internal) forward a hook payload from stdin to the daemon
-  backfill        Import existing transcripts into the store [--agent claude|grok|codex|all]
+  backfill        Import existing transcripts into the store [--agent claude|grok|codex|codebuild|all]
   reindex         (Re)derive insights for stored sessions  [--since YYYY-MM]
   export          Export stored sessions as OTLP to a collector  [--since YYYY-MM]
   index           (Re)build the internal SQLite index from the git store
   query           List recent sessions from the index  [--limit N] [--agent X]
+  usage           Aggregated token/cost usage (totals/by-agent/by-day)  [--json]
+  graph           Sessions \xD7 topics graph (nodes + edges)  [--json]
   search          Full-text search session turns  <text> [--limit N]
   fork            Fork a session at a turn ("git for sessions")  <session-id> --at N [--id X]
   analytics       Compute MVP-2 rollups + digest into analytics/
@@ -1761,8 +1763,144 @@ function parseCodexSession(info, host) {
   return { host, sessionId, agent: "codex", turns, meta };
 }
 
+// src/adapters/codebuild.ts
+import { existsSync as existsSync12, readdirSync as readdirSync4, readFileSync as readFileSync10, statSync as statSync2 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join8 } from "path";
+import {
+  SCHEMA_VERSIONS as SCHEMA_VERSIONS5
+} from "@unpolarize/code-sessions-schema";
+function codebuildSessionsRoot() {
+  return join8(homedir4(), ".codebuild", "sessions");
+}
+function discoverCodebuildSessions(root = codebuildSessionsRoot()) {
+  if (!existsSync12(root)) return [];
+  let files;
+  try {
+    files = readdirSync4(root).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return [];
+  }
+  return files.map((f) => ({ sessionId: f.replace(/\.jsonl$/, ""), path: join8(root, f) }));
+}
+function backendToAgent(backend) {
+  if (backend === "claude") return "claude-code";
+  if (backend === "grok") return "grok";
+  if (backend === "codex") return "codex";
+  return "unknown";
+}
+function parseCodebuildSession(info, host) {
+  let raw = "";
+  try {
+    raw = readFileSync10(info.path, "utf8");
+  } catch {
+    return null;
+  }
+  const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+  const baseMs = statMtime2(info.path);
+  let agent = "unknown";
+  let sessionId = info.sessionId;
+  let title;
+  let cwd;
+  const turns = [];
+  let pending = null;
+  let idx = 0;
+  const flush = () => {
+    if (!pending) return;
+    const p = pending;
+    pending = null;
+    const turn = mkTurn2(sessionId, host, agent, idx++, baseMs, "assistant", p.text, p.tools);
+    turn.usage = {
+      input_tokens: p.input_tokens,
+      output_tokens: p.output_tokens,
+      cache_read_tokens: p.cache_read_tokens,
+      cache_write_tokens: 0
+    };
+    if (p.cost_usd > 0) turn.telemetry = { cost_usd: p.cost_usd };
+    turns.push(turn);
+  };
+  const ensurePending = () => {
+    if (!pending) pending = { text: "", tools: [], input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cost_usd: 0 };
+    return pending;
+  };
+  for (const line of lines) {
+    let ev;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (ev.type === "meta" && ev.meta) {
+      agent = backendToAgent(ev.meta.backend);
+      if (typeof ev.meta.id === "string") sessionId = ev.meta.id;
+      if (typeof ev.meta.title === "string") title = ev.meta.title;
+      if (typeof ev.meta.cwd === "string") cwd = ev.meta.cwd;
+      continue;
+    }
+    if (ev.type === "user" && typeof ev.text === "string") {
+      flush();
+      turns.push(mkTurn2(sessionId, host, agent, idx++, baseMs, "user", ev.text, []));
+      continue;
+    }
+    if (ev.type === "update" && ev.update) {
+      const u = ev.update;
+      if (u.kind === "agent_message_chunk") {
+        const t = u.content?.text;
+        if (typeof t === "string") ensurePending().text += t;
+      } else if (u.kind === "tool_call" && u.toolCall) {
+        const p = ensurePending();
+        p.tools.push({ name: String(u.toolCall.title ?? u.toolCall.kind ?? "tool"), input: u.toolCall.rawInput });
+      } else if (u.kind === "usage" && u.usage) {
+        const p = ensurePending();
+        p.input_tokens += Number(u.usage.inputTokens) || 0;
+        p.output_tokens += Number(u.usage.outputTokens) || 0;
+        p.cache_read_tokens += Number(u.usage.cacheReadTokens) || 0;
+      } else if (u.kind === "result" && u.usage) {
+        const p = ensurePending();
+        p.input_tokens += Number(u.usage.inputTokens) || 0;
+        p.output_tokens += Number(u.usage.outputTokens) || 0;
+        p.cost_usd += Number(u.usage.costUsd) || 0;
+        flush();
+      }
+    }
+  }
+  flush();
+  if (turns.length === 0) return null;
+  const meta = {
+    session_id: sessionId,
+    started_at: turns[0].ts,
+    ended_at: turns[turns.length - 1].ts
+  };
+  if (cwd) meta.project_path = cwd;
+  if (title) meta.title = title;
+  return { host, sessionId, agent, turns, meta };
+}
+function statMtime2(p) {
+  try {
+    return statSync2(p).mtimeMs;
+  } catch {
+    return Date.parse("2020-01-01T00:00:00Z");
+  }
+}
+function mkTurn2(sessionId, host, agent, index, baseMs, role, text, tool_calls) {
+  return {
+    schema: SCHEMA_VERSIONS5.turn,
+    session_id: sessionId,
+    host,
+    agent,
+    turn_index: index,
+    ts: new Date(baseMs + index * 1e3).toISOString(),
+    role,
+    text,
+    tool_calls,
+    usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 },
+    scrubbed: false,
+    raw_ref: null
+  };
+}
+
 // src/adapters/import.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync6, readFileSync as readFileSync10, renameSync as renameSync4, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync11, renameSync as renameSync4, writeFileSync as writeFileSync6 } from "fs";
 import { dirname as dirname5 } from "path";
 var NATIVE_FORMAT = {
   "claude-code": "claude-jsonl",
@@ -1793,9 +1931,9 @@ function writeImportedSession(cfg, s) {
   });
   env.native_ref.format = NATIVE_FORMAT[s.agent] ?? "unknown";
   const envPath = envelopeFile(dir);
-  if (existsSync12(envPath)) {
+  if (existsSync13(envPath)) {
     try {
-      const prev = JSON.parse(readFileSync10(envPath, "utf8"));
+      const prev = JSON.parse(readFileSync11(envPath, "utf8"));
       if (prev.labels?.length) env.labels = prev.labels;
     } catch {
     }
@@ -1816,6 +1954,9 @@ function toMs(iso) {
   const v = Date.parse(iso);
   return Number.isNaN(v) ? null : v;
 }
+function round6(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
 var SessionIndex = class {
   db;
   constructor(path) {
@@ -2017,6 +2158,83 @@ var SessionIndex = class {
     ).all(like, like, limit);
     return rows.map((r) => this.rowToIndex(r));
   }
+  /** Graph of sessions clustered by topic (+ fork lineage where known). */
+  graphData() {
+    const rows = this.db.prepare("SELECT session_id, agent, topic, intent, cost_usd, title FROM session ORDER BY started_at DESC").all();
+    const nodes = [];
+    const edges = [];
+    const topicNodes = /* @__PURE__ */ new Map();
+    const topicId = (t) => {
+      let id = topicNodes.get(t);
+      if (!id) {
+        id = `topic:${topicNodes.size}`;
+        topicNodes.set(t, id);
+        nodes.push({ id, kind: "topic", label: t, sessions: 0, cost_usd: 0 });
+      }
+      return id;
+    };
+    for (const r of rows) {
+      const sid = `s:${r.session_id}`;
+      nodes.push({
+        id: sid,
+        kind: "session",
+        label: (r.topic || r.title || r.session_id).slice(0, 48),
+        agent: r.agent,
+        intent: r.intent ?? null,
+        cost_usd: r.cost_usd,
+        sessions: 1
+      });
+      const topic = (r.topic || r.intent || "misc").toString();
+      const tid = topicId(topic);
+      edges.push({ from: sid, to: tid, kind: "has-topic" });
+      const tn = nodes.find((n) => n.id === tid);
+      tn.sessions += 1;
+      tn.cost_usd += r.cost_usd;
+    }
+    return { nodes, edges };
+  }
+  /** Aggregated usage for a Usage panel: totals, by agent, by day, by project, top cost. */
+  usageSummary(opts = {}) {
+    const rows = this.db.prepare(
+      "SELECT session_id, agent, started_at, input_tokens, output_tokens, cost_usd, projects_json, topic, title FROM session"
+    ).all();
+    const totals = { sessions: rows.length, input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+    const byAgent = {};
+    const byDay = {};
+    const byProject = {};
+    const add = (m, key, r) => {
+      const b = m[key] ??= { sessions: 0, input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+      b.sessions++;
+      b.input_tokens += r.input_tokens;
+      b.output_tokens += r.output_tokens;
+      b.cost_usd += r.cost_usd;
+    };
+    for (const r of rows) {
+      totals.input_tokens += r.input_tokens;
+      totals.output_tokens += r.output_tokens;
+      totals.cost_usd += r.cost_usd;
+      add(byAgent, r.agent || "unknown", r);
+      if (r.started_at) add(byDay, new Date(r.started_at).toISOString().slice(0, 10), r);
+      for (const p of safeJson(r.projects_json)) add(byProject, p, r);
+    }
+    totals.cost_usd = round6(totals.cost_usd);
+    for (const m of [byAgent, byDay, byProject]) for (const b of Object.values(m)) b.cost_usd = round6(b.cost_usd);
+    const days = opts.days ?? 30;
+    const recentDays = Object.entries(byDay).sort((a, b) => a[0] < b[0] ? 1 : -1).slice(0, days).map(([day, b]) => ({ day, ...b }));
+    const topByCost = rows.map((r) => ({
+      session_id: r.session_id,
+      agent: r.agent,
+      cost_usd: round6(r.cost_usd),
+      label: r.topic || r.title || r.session_id
+    })).sort((a, b) => b.cost_usd - a.cost_usd).slice(0, opts.topN ?? 10);
+    return {
+      totals,
+      byAgent,
+      byDay: recentDays,
+      byProject,
+      topByCost
+    };
+  }
   stats() {
     const s = this.db.prepare("SELECT COUNT(*) c, COALESCE(SUM(cost_usd),0) cost FROM session").get();
     const t = this.db.prepare("SELECT COUNT(*) c FROM turn").get();
@@ -2040,7 +2258,7 @@ function safeJson(s) {
 }
 
 // src/index_store/sync.ts
-import { existsSync as existsSync13, readFileSync as readFileSync11, statSync as statSync2 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync12, statSync as statSync3 } from "fs";
 import { safeParseInsights, safeParseSession as safeParseSession2 } from "@unpolarize/code-sessions-schema";
 function syncIndex(cfg, opts = {}) {
   const index = opts.index ?? new SessionIndex(cfg.indexPath);
@@ -2054,8 +2272,8 @@ function syncIndex(cfg, opts = {}) {
     let unchanged = 0;
     for (const ref of refs) {
       const envPath = envelopeFile(ref.dir);
-      if (!existsSync13(envPath)) continue;
-      const st = statSync2(envPath);
+      if (!existsSync14(envPath)) continue;
+      const st = statSync3(envPath);
       const mtime_ms = Math.floor(st.mtimeMs);
       const size_bytes = st.size;
       seen.add(ref.sessionId);
@@ -2064,7 +2282,7 @@ function syncIndex(cfg, opts = {}) {
         unchanged++;
         continue;
       }
-      const parsed = safeParseSession2(JSON.parse(readFileSync11(envPath, "utf8")));
+      const parsed = safeParseSession2(JSON.parse(readFileSync12(envPath, "utf8")));
       if (!parsed.success) continue;
       const env = parsed.data;
       let topic;
@@ -2072,8 +2290,8 @@ function syncIndex(cfg, opts = {}) {
       let projects = [];
       const insPath = insightsFile(ref.dir);
       let insights = void 0;
-      if (existsSync13(insPath)) {
-        const pi = safeParseInsights(JSON.parse(readFileSync11(insPath, "utf8")));
+      if (existsSync14(insPath)) {
+        const pi = safeParseInsights(JSON.parse(readFileSync12(insPath, "utf8")));
         if (pi.success) {
           insights = pi.data;
           topic = pi.data.topic;
@@ -2146,36 +2364,36 @@ ${buildLabelSkillBody()}
 
 // src/skills/install.ts
 import { mkdirSync as mkdirSync8, writeFileSync as writeFileSync7 } from "fs";
-import { homedir as homedir4 } from "os";
-import { dirname as dirname7, join as join8 } from "path";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname7, join as join9 } from "path";
 function targetsFor(agent, home) {
   const out = [];
   const want = (a) => agent === "all" || agent === a;
   if (want("claude")) {
     out.push({
       agent: "claude",
-      path: join8(home, ".claude", "skills", "cs-label-session", "SKILL.md"),
+      path: join9(home, ".claude", "skills", "cs-label-session", "SKILL.md"),
       content: buildClaudeSkill()
     });
   }
   if (want("codex")) {
     out.push({
       agent: "codex",
-      path: join8(home, ".codex", "prompts", "cs-label-session.md"),
+      path: join9(home, ".codex", "prompts", "cs-label-session.md"),
       content: buildPromptFile()
     });
   }
   if (want("grok")) {
     out.push({
       agent: "grok",
-      path: join8(home, ".grok", "prompts", "cs-label-session.md"),
+      path: join9(home, ".grok", "prompts", "cs-label-session.md"),
       content: buildPromptFile()
     });
   }
   return out;
 }
 function installSkills(opts = {}) {
-  const home = opts.home ?? homedir4();
+  const home = opts.home ?? homedir5();
   const installed = [];
   for (const t of targetsFor(opts.agent ?? "all", home)) {
     mkdirSync8(dirname7(t.path), { recursive: true });
@@ -2186,7 +2404,7 @@ function installSkills(opts = {}) {
 }
 
 // src/fork.ts
-import { existsSync as existsSync14, readFileSync as readFileSync12 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync13 } from "fs";
 import { randomUUID } from "crypto";
 import { mkdirSync as mkdirSync9, renameSync as renameSync5, writeFileSync as writeFileSync8 } from "fs";
 import { dirname as dirname8 } from "path";
@@ -2199,8 +2417,8 @@ function locateSession(storeDir, sessionId) {
 }
 function loadEnvelope2(dir) {
   const p = envelopeFile(dir);
-  if (!existsSync14(p)) return void 0;
-  const parsed = safeParseSession3(JSON.parse(readFileSync12(p, "utf8")));
+  if (!existsSync15(p)) return void 0;
+  const parsed = safeParseSession3(JSON.parse(readFileSync13(p, "utf8")));
   return parsed.success ? parsed.data : void 0;
 }
 function writeJsonAtomic4(path, value) {
@@ -2249,8 +2467,8 @@ function forkSession(cfg, opts) {
 }
 
 // src/commands.ts
-import { existsSync as existsSync15, writeFileSync as writeFileSync9 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync16, writeFileSync as writeFileSync9 } from "fs";
+import { join as join10 } from "path";
 function gitStoreFor(cfg) {
   return new GitStore(cfg.storeDir, {
     ...cfg.git.remote ? { remote: cfg.git.remote } : {},
@@ -2260,13 +2478,13 @@ function gitStoreFor(cfg) {
 function listClaudeTranscripts(projectsDir, maxDepth = 3) {
   const out = [];
   const walk = (dir, depth) => {
-    if (depth > maxDepth || !existsSync15(dir)) return;
+    if (depth > maxDepth || !existsSync16(dir)) return;
     for (const e of readEntries(dir)) {
       const name = String(e.name);
       if (e.isFile() && name.endsWith(".jsonl")) {
-        out.push({ sessionId: name.replace(/\.jsonl$/, ""), path: join9(dir, name) });
+        out.push({ sessionId: name.replace(/\.jsonl$/, ""), path: join10(dir, name) });
       } else if (e.isDirectory()) {
-        walk(join9(dir, name), depth + 1);
+        walk(join10(dir, name), depth + 1);
       }
     }
   };
@@ -2276,8 +2494,8 @@ function listClaudeTranscripts(projectsDir, maxDepth = 3) {
 function cmdInit(cfg) {
   const git = gitStoreFor(cfg);
   git.init();
-  const configPath = join9(cfg.storeDir, "config.json");
-  if (!existsSync15(configPath)) {
+  const configPath = join10(cfg.storeDir, "config.json");
+  if (!existsSync16(configPath)) {
     writeFileSync9(
       configPath,
       `${JSON.stringify({ insights: cfg.insights, batch: cfg.batch, hygiene: cfg.hygiene }, null, 2)}
@@ -2291,7 +2509,7 @@ function cmdStatus(cfg) {
   const state = new StateStore(cfg.statePath);
   const sessions = Object.keys(state.all());
   const stored = listSessionDirs(cfg.storeDir);
-  const socketUp = existsSync15(cfg.socketPath);
+  const socketUp = existsSync16(cfg.socketPath);
   const lines = [
     `store:      ${cfg.storeDir}`,
     `host:       ${cfg.host}`,
@@ -2346,6 +2564,20 @@ async function cmdBackfill(cfg, opts = {}) {
     turns += t;
     parts.push(`codex: ${n} sessions / ${t} turns`);
   }
+  if (agent === "codebuild" || agent === "all") {
+    const found = discoverCodebuildSessions();
+    let n = 0;
+    let t = 0;
+    for (const info of found) {
+      const imported = parseCodebuildSession(info, cfg.host);
+      if (!imported) continue;
+      t += writeImportedSession(cfg, imported).turns;
+      n++;
+    }
+    sessions += n;
+    turns += t;
+    parts.push(`codebuild: ${n} sessions / ${t} turns`);
+  }
   const git = gitStoreFor(cfg);
   git.init();
   git.commit(`backfill (${agent}): ${sessions} sessions`);
@@ -2360,7 +2592,7 @@ async function cmdReindex(cfg, opts = {}) {
 }
 function cmdInstallHooks(cfg, opts = {}) {
   const home = cfg.claudeProjectsDir.replace(/\/projects\/?$/, "");
-  const settingsPath = opts.settingsPath ?? join9(home, "settings.json");
+  const settingsPath = opts.settingsPath ?? join10(home, "settings.json");
   const command = opts.command ?? "code-sessions hook";
   const res = installHooks(settingsPath, command);
   return {
@@ -2370,10 +2602,10 @@ function cmdInstallHooks(cfg, opts = {}) {
 }
 function cmdDoctor(cfg) {
   const checks = [
-    ["store dir exists", existsSync15(cfg.storeDir)],
-    ["store is git repo", existsSync15(join9(cfg.storeDir, ".git"))],
-    ["daemon socket present", existsSync15(cfg.socketPath)],
-    ["claude projects dir", existsSync15(cfg.claudeProjectsDir)]
+    ["store dir exists", existsSync16(cfg.storeDir)],
+    ["store is git repo", existsSync16(join10(cfg.storeDir, ".git"))],
+    ["daemon socket present", existsSync16(cfg.socketPath)],
+    ["claude projects dir", existsSync16(cfg.claudeProjectsDir)]
   ];
   const lines = checks.map(([name, ok]) => `${ok ? "\u2713" : "\u2717"} ${name}`);
   const code = checks.every(([, ok]) => ok) ? 0 : 1;
@@ -2409,6 +2641,37 @@ function cmdFork(cfg, opts) {
     return { code: 1, output: `fork failed: ${e instanceof Error ? e.message : String(e)}` };
   }
 }
+function cmdGraph(cfg, opts = {}) {
+  syncIndex(cfg);
+  const index = new SessionIndex(cfg.indexPath);
+  try {
+    const g = index.graphData();
+    if (opts.json) return { code: 0, output: JSON.stringify(g) };
+    const topics = g.nodes.filter((n) => n.kind === "topic").length;
+    const sessions = g.nodes.filter((n) => n.kind === "session").length;
+    return { code: 0, output: `graph: ${sessions} sessions across ${topics} topics, ${g.edges.length} edges` };
+  } finally {
+    index.close();
+  }
+}
+function cmdUsage(cfg, opts = {}) {
+  syncIndex(cfg);
+  const index = new SessionIndex(cfg.indexPath);
+  try {
+    const u = index.usageSummary();
+    if (opts.json) return { code: 0, output: JSON.stringify(u) };
+    const lines = [
+      `# usage \u2014 ${u.totals.sessions} sessions \xB7 ${u.totals.input_tokens.toLocaleString()} in / ${u.totals.output_tokens.toLocaleString()} out \xB7 $${u.totals.cost_usd.toFixed(2)}`,
+      "by agent:",
+      ...Object.entries(u.byAgent).map(([a, b]) => `  ${a.padEnd(12)} ${b.sessions} sess  $${b.cost_usd.toFixed(2)}`),
+      "top sessions by cost:",
+      ...u.topByCost.slice(0, 5).map((t) => `  $${t.cost_usd.toFixed(2).padStart(8)}  ${t.agent.padEnd(12)} ${t.label.slice(0, 50)}`)
+    ];
+    return { code: 0, output: lines.join("\n") };
+  } finally {
+    index.close();
+  }
+}
 function cmdInstallSkills(opts = {}) {
   const res = installSkills(opts.agent ? { agent: opts.agent } : {});
   return { code: 0, output: `Installed cs-label-session skill:
@@ -2474,9 +2737,9 @@ async function startDaemon(cfg) {
 }
 
 // src/hooks/shim.ts
-import { existsSync as existsSync16 } from "fs";
+import { existsSync as existsSync17 } from "fs";
 async function handleHookInput(socketPath, rawInput) {
-  if (!existsSync16(socketPath)) return { ok: false, error: "daemon not running" };
+  if (!existsSync17(socketPath)) return { ok: false, error: "daemon not running" };
   let parsed;
   try {
     parsed = JSON.parse(rawInput);
@@ -2560,6 +2823,9 @@ export {
   codexSessionsRoot,
   discoverCodexSessions,
   parseCodexSession,
+  codebuildSessionsRoot,
+  discoverCodebuildSessions,
+  parseCodebuildSession,
   writeImportedSession,
   SessionIndex,
   syncIndex,
@@ -2577,6 +2843,8 @@ export {
   cmdDoctor,
   cmdExport,
   cmdFork,
+  cmdGraph,
+  cmdUsage,
   cmdInstallSkills,
   cmdIndex,
   cmdQuery,

package/dist/cli.js

@@ -5,6 +5,7 @@ import {
   cmdDoctor,
   cmdExport,
   cmdFork,
+  cmdGraph,
   cmdIndex,
   cmdInit,
   cmdInstallHooks,
@@ -13,6 +14,7 @@ import {
   cmdReindex,
   cmdSearch,
   cmdStatus,
+  cmdUsage,
   envelopeFile,
   handleHookInput,
   insightsFile,
@@ -22,7 +24,7 @@ import {
   parseFlags,
   readStdin,
   startDaemon
-} from "./chunk-HV6FQJPS.js";
+} from "./chunk-3VPXOUIE.js";
 
 // src/analytics/command.ts
 import { mkdirSync, writeFileSync } from "fs";
@@ -256,6 +258,12 @@ async function main(argv) {
     case "index":
       emit(cmdIndex(cfg));
       break;
+    case "usage":
+      emit(cmdUsage(cfg, { json: flags.json === true }));
+      break;
+    case "graph":
+      emit(cmdGraph(cfg, { json: flags.json === true }));
+      break;
     case "query":
       emit(
         cmdQuery(cfg, {

package/dist/index.js

@@ -20,6 +20,7 @@ import {
   cmdDoctor,
   cmdExport,
   cmdFork,
+  cmdGraph,
   cmdIndex,
   cmdInit,
   cmdInstallHooks,
@@ -28,6 +29,8 @@ import {
   cmdReindex,
   cmdSearch,
   cmdStatus,
+  cmdUsage,
+  codebuildSessionsRoot,
   codexSessionsRoot,
   computeEnvelope,
   defaultConfig,
@@ -35,6 +38,7 @@ import {
   deriveProjects,
   deriveSignals,
   deriveTags,
+  discoverCodebuildSessions,
   discoverCodexSessions,
   discoverGrokSessions,
   envelopeFile,
@@ -61,6 +65,7 @@ import {
   monthOf,
   ollamaRunner,
   overridesFromFlags,
+  parseCodebuildSession,
   parseCodexSession,
   parseFlags,
   parseGrokSession,
@@ -88,7 +93,7 @@ import {
   writeBlobFile,
   writeImportedSession,
   writeTurnFile
-} from "./chunk-HV6FQJPS.js";
+} from "./chunk-3VPXOUIE.js";
 export {
   CaptureEngine,
   DEFAULT_HOOK_EVENTS,
@@ -111,6 +116,7 @@ export {
   cmdDoctor,
   cmdExport,
   cmdFork,
+  cmdGraph,
   cmdIndex,
   cmdInit,
   cmdInstallHooks,
@@ -119,6 +125,8 @@ export {
   cmdReindex,
   cmdSearch,
   cmdStatus,
+  cmdUsage,
+  codebuildSessionsRoot,
   codexSessionsRoot,
   computeEnvelope,
   defaultConfig,
@@ -126,6 +134,7 @@ export {
   deriveProjects,
   deriveSignals,
   deriveTags,
+  discoverCodebuildSessions,
   discoverCodexSessions,
   discoverGrokSessions,
   envelopeFile,
@@ -152,6 +161,7 @@ export {
   monthOf,
   ollamaRunner,
   overridesFromFlags,
+  parseCodebuildSession,
   parseCodexSession,
   parseFlags,
   parseGrokSession,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unpolarize/code-sessions",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Headless, event-driven cross-agent session capture agent (daemon + CLI)",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,7 @@
     "build": "tsup src/index.ts src/cli.ts --format esm --clean --out-dir dist"
   },
   "dependencies": {
-    "@unpolarize/code-sessions-schema": "^0.2.0",
+    "@unpolarize/code-sessions-schema": "^0.4.0",
     "zod": "^3.23.8"
   }
 }

package/src/adapters/adapters.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from 'vitest';
 import { sessionDir, turnFile, envelopeFile } from '../store/paths';
 import { makeConfig, withTempDir } from '../test/tmp';
 import { discoverCodexSessions, parseCodexSession } from './codex';
+import { discoverCodebuildSessions, parseCodebuildSession } from './codebuild';
 import { discoverGrokSessions, parseGrokSession } from './grok';
 import { writeImportedSession } from './import';
 
@@ -98,6 +99,41 @@ describe('codex adapter', () => {
   });
 });
 
+function seedCodebuild(root: string): void {
+  mkdirSync(root, { recursive: true });
+  writeFileSync(
+    join(root, 'cb-1.jsonl'),
+    [
+      '{"type":"meta","meta":{"id":"cb-1","backend":"claude","title":"Plan MVP","cwd":"/Users/x/projects/foo"}}',
+      '{"type":"update","update":{"kind":"system_init","backendSessionId":"native-1"}}',
+      '{"type":"user","text":"add a feature"}',
+      '{"type":"update","update":{"kind":"agent_message_chunk","content":{"type":"text","text":"sure, "}}}',
+      '{"type":"update","update":{"kind":"agent_message_chunk","content":{"type":"text","text":"editing"}}}',
+      '{"type":"update","update":{"kind":"tool_call","toolCall":{"toolCallId":"t1","title":"Edit","rawInput":{"file_path":"a.ts"}}}}',
+      '{"type":"update","update":{"kind":"result","stopReason":"success","usage":{"inputTokens":1000,"outputTokens":40,"costUsd":0.25}}}',
+    ].join('\n'),
+  );
+}
+
+describe('codebuild adapter', () => {
+  it('folds CB stream into user/assistant turns with usage', () => {
+    withTempDir((root) => {
+      seedCodebuild(root);
+      const found = discoverCodebuildSessions(root);
+      expect(found).toHaveLength(1);
+      const imported = parseCodebuildSession(found[0]!, 'test-host')!;
+      expect(imported.agent).toBe('claude-code'); // backend=claude -> claude-code
+      expect(imported.sessionId).toBe('cb-1');
+      expect(imported.meta.title).toBe('Plan MVP');
+      expect(imported.turns.map((t) => t.role)).toEqual(['user', 'assistant']);
+      expect(imported.turns[1]!.text).toBe('sure, editing'); // chunks concatenated
+      expect(imported.turns[1]!.tool_calls[0]).toMatchObject({ name: 'Edit' });
+      expect(imported.turns[1]!.usage.input_tokens).toBe(1000);
+      expect(imported.turns[1]!.telemetry?.cost_usd).toBe(0.25);
+    });
+  });
+});
+
 describe('writeImportedSession', () => {
   it('writes per-turn files + envelope for an imported session', () => {
     withTempDir((store) => {

package/src/adapters/codebuild.ts

@@ -0,0 +1,188 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  SCHEMA_VERSIONS,
+  type AgentKind,
+  type ClaudeSessionMeta,
+  type ToolCall,
+  type Turn,
+} from '@unpolarize/code-sessions-schema';
+import type { ImportedSession } from './import';
+
+/**
+ * Code Build VSCode (CB) adapter. CB stores each chat at
+ * ~/.codebuild/sessions/<uuid>.jsonl as a stream of:
+ *   {type:"meta", meta:{id, backend, title, cwd}}
+ *   {type:"user", text}
+ *   {type:"update", update:{kind:"agent_message_chunk", content:{type:"text",text}}}
+ *   {type:"update", update:{kind:"tool_call", toolCall:{title, rawInput}}}
+ *   {type:"update", update:{kind:"usage"|"result", usage:{...}}}
+ * Events carry no per-line timestamp; synthesized from file mtime + ordinal.
+ *
+ * Importing CB sessions into the CS store is how "CB context management uses CS":
+ * every CB turn becomes discoverable in the shared sessions store + index, and a
+ * CB switch/fork can be expressed as a CS forkSession on the persisted session.
+ */
+
+export function codebuildSessionsRoot(): string {
+  return join(homedir(), '.codebuild', 'sessions');
+}
+
+export interface CodebuildSessionInfo {
+  sessionId: string;
+  path: string;
+}
+
+export function discoverCodebuildSessions(root = codebuildSessionsRoot()): CodebuildSessionInfo[] {
+  if (!existsSync(root)) return [];
+  let files: string[];
+  try {
+    files = readdirSync(root).filter((f) => f.endsWith('.jsonl'));
+  } catch {
+    return [];
+  }
+  return files.map((f) => ({ sessionId: f.replace(/\.jsonl$/, ''), path: join(root, f) }));
+}
+
+function backendToAgent(backend: unknown): AgentKind {
+  if (backend === 'claude') return 'claude-code';
+  if (backend === 'grok') return 'grok';
+  if (backend === 'codex') return 'codex';
+  return 'unknown';
+}
+
+interface Pending {
+  text: string;
+  tools: ToolCall[];
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cost_usd: number;
+}
+
+export function parseCodebuildSession(info: CodebuildSessionInfo, host: string): ImportedSession | null {
+  let raw = '';
+  try {
+    raw = readFileSync(info.path, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  const baseMs = statMtime(info.path);
+
+  let agent: AgentKind = 'unknown';
+  let sessionId = info.sessionId;
+  let title: string | undefined;
+  let cwd: string | undefined;
+
+  const turns: Turn[] = [];
+  let pending: Pending | null = null;
+  let idx = 0;
+
+  const flush = (): void => {
+    if (!pending) return;
+    const p = pending;
+    pending = null;
+    const turn = mkTurn(sessionId, host, agent, idx++, baseMs, 'assistant', p.text, p.tools);
+    turn.usage = {
+      input_tokens: p.input_tokens,
+      output_tokens: p.output_tokens,
+      cache_read_tokens: p.cache_read_tokens,
+      cache_write_tokens: 0,
+    };
+    if (p.cost_usd > 0) turn.telemetry = { cost_usd: p.cost_usd };
+    turns.push(turn);
+  };
+  const ensurePending = (): Pending => {
+    if (!pending) pending = { text: '', tools: [], input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cost_usd: 0 };
+    return pending;
+  };
+
+  for (const line of lines) {
+    let ev: any;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (ev.type === 'meta' && ev.meta) {
+      agent = backendToAgent(ev.meta.backend);
+      if (typeof ev.meta.id === 'string') sessionId = ev.meta.id;
+      if (typeof ev.meta.title === 'string') title = ev.meta.title;
+      if (typeof ev.meta.cwd === 'string') cwd = ev.meta.cwd;
+      continue;
+    }
+    if (ev.type === 'user' && typeof ev.text === 'string') {
+      flush();
+      turns.push(mkTurn(sessionId, host, agent, idx++, baseMs, 'user', ev.text, []));
+      continue;
+    }
+    if (ev.type === 'update' && ev.update) {
+      const u = ev.update;
+      if (u.kind === 'agent_message_chunk') {
+        const t = u.content?.text;
+        if (typeof t === 'string') ensurePending().text += t;
+      } else if (u.kind === 'tool_call' && u.toolCall) {
+        const p = ensurePending();
+        p.tools.push({ name: String(u.toolCall.title ?? u.toolCall.kind ?? 'tool'), input: u.toolCall.rawInput });
+      } else if (u.kind === 'usage' && u.usage) {
+        const p = ensurePending();
+        p.input_tokens += Number(u.usage.inputTokens) || 0;
+        p.output_tokens += Number(u.usage.outputTokens) || 0;
+        p.cache_read_tokens += Number(u.usage.cacheReadTokens) || 0;
+      } else if (u.kind === 'result' && u.usage) {
+        const p = ensurePending();
+        p.input_tokens += Number(u.usage.inputTokens) || 0;
+        p.output_tokens += Number(u.usage.outputTokens) || 0;
+        p.cost_usd += Number(u.usage.costUsd) || 0;
+        flush();
+      }
+    }
+  }
+  flush();
+
+  if (turns.length === 0) return null;
+  const meta: ClaudeSessionMeta = {
+    session_id: sessionId,
+    started_at: turns[0]!.ts,
+    ended_at: turns[turns.length - 1]!.ts,
+  };
+  if (cwd) meta.project_path = cwd;
+  if (title) meta.title = title;
+  return { host, sessionId, agent, turns, meta };
+}
+
+function statMtime(p: string): number {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return Date.parse('2020-01-01T00:00:00Z');
+  }
+}
+
+function mkTurn(
+  sessionId: string,
+  host: string,
+  agent: AgentKind,
+  index: number,
+  baseMs: number,
+  role: Turn['role'],
+  text: string,
+  tool_calls: ToolCall[],
+): Turn {
+  return {
+    schema: SCHEMA_VERSIONS.turn,
+    session_id: sessionId,
+    host,
+    agent,
+    turn_index: index,
+    ts: new Date(baseMs + index * 1000).toISOString(),
+    role,
+    text,
+    tool_calls,
+    usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 },
+    scrubbed: false,
+    raw_ref: null,
+  };
+}

package/src/adapters/index.ts

@@ -1,3 +1,4 @@
 export * from './import';
 export * from './grok';
 export * from './codex';
+export * from './codebuild';

package/src/cli.ts

@@ -5,6 +5,7 @@ import {
   cmdDoctor,
   cmdExport,
   cmdFork,
+  cmdGraph,
   cmdIndex,
   cmdInit,
   cmdInstallHooks,
@@ -13,6 +14,7 @@ import {
   cmdReindex,
   cmdSearch,
   cmdStatus,
+  cmdUsage,
   startDaemon,
   type CommandResult,
 } from './commands';
@@ -54,7 +56,7 @@ export async function main(argv: string[]): Promise<void> {
       emit(
         await cmdBackfill(cfg, {
           ...(typeof flags.projects === 'string' ? { projectsDir: flags.projects } : {}),
-          ...(typeof flags.agent === 'string' ? { agent: flags.agent as 'claude' | 'grok' | 'codex' | 'all' } : {}),
+          ...(typeof flags.agent === 'string' ? { agent: flags.agent as 'claude' | 'grok' | 'codex' | 'codebuild' | 'all' } : {}),
         }),
       );
       break;
@@ -70,6 +72,12 @@ export async function main(argv: string[]): Promise<void> {
     case 'index':
       emit(cmdIndex(cfg));
       break;
+    case 'usage':
+      emit(cmdUsage(cfg, { json: flags.json === true }));
+      break;
+    case 'graph':
+      emit(cmdGraph(cfg, { json: flags.json === true }));
+      break;
     case 'query':
       emit(
         cmdQuery(cfg, {

package/src/cliargs.ts

@@ -53,11 +53,13 @@ Commands:
   install-hooks   Install Claude Code hooks that feed the daemon
   install-skills  Install the cs-label-session skill into agents [--agent claude|codex|grok|all]
   hook            (internal) forward a hook payload from stdin to the daemon
-  backfill        Import existing transcripts into the store [--agent claude|grok|codex|all]
+  backfill        Import existing transcripts into the store [--agent claude|grok|codex|codebuild|all]
   reindex         (Re)derive insights for stored sessions  [--since YYYY-MM]
   export          Export stored sessions as OTLP to a collector  [--since YYYY-MM]
   index           (Re)build the internal SQLite index from the git store
   query           List recent sessions from the index  [--limit N] [--agent X]
+  usage           Aggregated token/cost usage (totals/by-agent/by-day)  [--json]
+  graph           Sessions × topics graph (nodes + edges)  [--json]
   search          Full-text search session turns  <text> [--limit N]
   fork            Fork a session at a turn ("git for sessions")  <session-id> --at N [--id X]
   analytics       Compute MVP-2 rollups + digest into analytics/

package/src/commands.ts

@@ -12,6 +12,7 @@ import { installHooks } from './hooks/install';
 import { exportSession, exportStore } from './telemetry/exporter';
 import { discoverGrokSessions, parseGrokSession } from './adapters/grok';
 import { discoverCodexSessions, parseCodexSession } from './adapters/codex';
+import { discoverCodebuildSessions, parseCodebuildSession } from './adapters/codebuild';
 import { writeImportedSession } from './adapters/import';
 import { SessionIndex, type SessionIndexRow } from './index_store/db';
 import { syncIndex } from './index_store/sync';
@@ -82,7 +83,7 @@ export function cmdStatus(cfg: CodeSessionsConfig): CommandResult {
   return { code: 0, output: lines.join('\n') };
 }
 
-export type BackfillAgent = 'claude' | 'grok' | 'codex' | 'all';
+export type BackfillAgent = 'claude' | 'grok' | 'codex' | 'codebuild' | 'all';
 
 export async function cmdBackfill(
   cfg: CodeSessionsConfig,
@@ -134,6 +135,21 @@ export async function cmdBackfill(
     parts.push(`codex: ${n} sessions / ${t} turns`);
   }
 
+  if (agent === 'codebuild' || agent === 'all') {
+    const found = discoverCodebuildSessions();
+    let n = 0;
+    let t = 0;
+    for (const info of found) {
+      const imported = parseCodebuildSession(info, cfg.host);
+      if (!imported) continue;
+      t += writeImportedSession(cfg, imported).turns;
+      n++;
+    }
+    sessions += n;
+    turns += t;
+    parts.push(`codebuild: ${n} sessions / ${t} turns`);
+  }
+
   const git = gitStoreFor(cfg);
   git.init();
   git.commit(`backfill (${agent}): ${sessions} sessions`);
@@ -218,6 +234,41 @@ export function cmdFork(
   }
 }
 
+/** Sessions × topics graph (nodes + edges) from the CS index. JSON for the graph view. */
+export function cmdGraph(cfg: CodeSessionsConfig, opts: { json?: boolean } = {}): CommandResult {
+  syncIndex(cfg);
+  const index = new SessionIndex(cfg.indexPath);
+  try {
+    const g = index.graphData();
+    if (opts.json) return { code: 0, output: JSON.stringify(g) };
+    const topics = g.nodes.filter((n) => n.kind === 'topic').length;
+    const sessions = g.nodes.filter((n) => n.kind === 'session').length;
+    return { code: 0, output: `graph: ${sessions} sessions across ${topics} topics, ${g.edges.length} edges` };
+  } finally {
+    index.close();
+  }
+}
+
+/** Aggregated usage from the CS index (totals/byAgent/byDay/byProject/topByCost). */
+export function cmdUsage(cfg: CodeSessionsConfig, opts: { json?: boolean } = {}): CommandResult {
+  syncIndex(cfg); // ensure the index reflects the current store
+  const index = new SessionIndex(cfg.indexPath);
+  try {
+    const u = index.usageSummary();
+    if (opts.json) return { code: 0, output: JSON.stringify(u) };
+    const lines = [
+      `# usage — ${u.totals.sessions} sessions · ${u.totals.input_tokens.toLocaleString()} in / ${u.totals.output_tokens.toLocaleString()} out · $${u.totals.cost_usd.toFixed(2)}`,
+      'by agent:',
+      ...Object.entries(u.byAgent).map(([a, b]) => `  ${a.padEnd(12)} ${b.sessions} sess  $${b.cost_usd.toFixed(2)}`),
+      'top sessions by cost:',
+      ...u.topByCost.slice(0, 5).map((t) => `  $${t.cost_usd.toFixed(2).padStart(8)}  ${t.agent.padEnd(12)} ${t.label.slice(0, 50)}`),
+    ];
+    return { code: 0, output: lines.join('\n') };
+  } finally {
+    index.close();
+  }
+}
+
 export function cmdInstallSkills(opts: { agent?: SkillAgent } = {}): CommandResult {
   const res = installSkills(opts.agent ? { agent: opts.agent } : {});
   return { code: 0, output: `Installed cs-label-session skill:\n  ${res.installed.join('\n  ')}` };

package/src/index_store/db.test.ts

@@ -91,6 +91,50 @@ describe('SessionIndex', () => {
     }
   });
 
+  it('aggregates usage by agent, day, project, and top-cost', () => {
+    const idx = new SessionIndex(':memory:');
+    try {
+      idx.upsertSession(env('c1', 'claude-code', { totals: { input_tokens: 100, output_tokens: 20, cost_usd: 2 } }), {
+        ...src,
+        projects: ['foo'],
+      });
+      idx.upsertSession(env('g1', 'grok', { totals: { input_tokens: 50, output_tokens: 5, cost_usd: 0.5 } }), {
+        ...src,
+        source_path: '/s/g.json',
+        projects: ['foo', 'bar'],
+      });
+      const u = idx.usageSummary();
+      expect(u.totals.sessions).toBe(2);
+      expect(u.totals.cost_usd).toBe(2.5);
+      expect(u.byAgent['claude-code']!.cost_usd).toBe(2);
+      expect(u.byProject['foo']!.sessions).toBe(2);
+      expect(u.byProject['bar']!.sessions).toBe(1);
+      expect(u.byDay[0]!.day).toBe('2026-06-20');
+      expect(u.topByCost[0]!.session_id).toBe('c1'); // highest cost first
+    } finally {
+      idx.close();
+    }
+  });
+
+  it('builds a sessions×topics graph', () => {
+    const idx = new SessionIndex(':memory:');
+    try {
+      idx.upsertSession(env('a', 'claude-code'), { ...src, topic: 'fix parser' });
+      idx.upsertSession(env('b', 'grok'), { ...src, source_path: '/s/b.json', topic: 'fix parser' });
+      idx.upsertSession(env('c', 'codex'), { ...src, source_path: '/s/c.json', topic: 'add feature' });
+      const g = idx.graphData();
+      const topics = g.nodes.filter((n) => n.kind === 'topic');
+      const sessions = g.nodes.filter((n) => n.kind === 'session');
+      expect(sessions).toHaveLength(3);
+      expect(topics).toHaveLength(2); // "fix parser" + "add feature"
+      expect(g.edges).toHaveLength(3); // each session -> its topic
+      const fixParser = topics.find((t) => t.label === 'fix parser')!;
+      expect(fixParser.sessions).toBe(2);
+    } finally {
+      idx.close();
+    }
+  });
+
   it('filters by agent and deletes sessions (cascade turns)', () => {
     const idx = new SessionIndex(':memory:');
     try {

package/src/index_store/db.ts

@@ -44,12 +44,50 @@ export interface SessionIndexRow {
   source_path: string;
 }
 
+export interface UsageBucket {
+  sessions: number;
+  input_tokens: number;
+  output_tokens: number;
+  cost_usd: number;
+}
+
+export interface GraphNode {
+  id: string;
+  kind: 'session' | 'topic';
+  label: string;
+  agent?: string;
+  intent?: string | null;
+  cost_usd: number;
+  sessions: number;
+}
+export interface GraphEdge {
+  from: string;
+  to: string;
+  kind: 'has-topic' | 'forked-from';
+}
+export interface GraphData {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+export interface UsageSummary {
+  totals: { sessions: number; input_tokens: number; output_tokens: number; cost_usd: number };
+  byAgent: Record<string, UsageBucket>;
+  byDay: Array<{ day: string } & UsageBucket>;
+  byProject: Record<string, UsageBucket>;
+  topByCost: Array<{ session_id: string; agent: string; cost_usd: number; label: string }>;
+}
+
 function toMs(iso: string | undefined): number | null {
   if (!iso) return null;
   const v = Date.parse(iso);
   return Number.isNaN(v) ? null : v;
 }
 
+function round6(n: number): number {
+  return Math.round(n * 1e6) / 1e6;
+}
+
 export class SessionIndex {
   readonly db: DatabaseSyncT;
 
@@ -289,6 +327,97 @@ export class SessionIndex {
     return (rows as any[]).map((r) => this.rowToIndex(r));
   }
 
+  /** Graph of sessions clustered by topic (+ fork lineage where known). */
+  graphData(): GraphData {
+    const rows = this.db
+      .prepare('SELECT session_id, agent, topic, intent, cost_usd, title FROM session ORDER BY started_at DESC')
+      .all() as any[];
+    const nodes: GraphNode[] = [];
+    const edges: GraphEdge[] = [];
+    const topicNodes = new Map<string, string>(); // topic -> node id
+    const topicId = (t: string) => {
+      let id = topicNodes.get(t);
+      if (!id) {
+        id = `topic:${topicNodes.size}`;
+        topicNodes.set(t, id);
+        nodes.push({ id, kind: 'topic', label: t, sessions: 0, cost_usd: 0 });
+      }
+      return id;
+    };
+    for (const r of rows) {
+      const sid = `s:${r.session_id}`;
+      nodes.push({
+        id: sid,
+        kind: 'session',
+        label: (r.topic || r.title || r.session_id).slice(0, 48),
+        agent: r.agent,
+        intent: r.intent ?? null,
+        cost_usd: r.cost_usd,
+        sessions: 1,
+      });
+      const topic = (r.topic || r.intent || 'misc').toString();
+      const tid = topicId(topic);
+      edges.push({ from: sid, to: tid, kind: 'has-topic' });
+      const tn = nodes.find((n) => n.id === tid)!;
+      tn.sessions += 1;
+      tn.cost_usd += r.cost_usd;
+    }
+    return { nodes, edges };
+  }
+
+  /** Aggregated usage for a Usage panel: totals, by agent, by day, by project, top cost. */
+  usageSummary(opts: { days?: number; topN?: number } = {}): UsageSummary {
+    const rows = this.db
+      .prepare(
+        'SELECT session_id, agent, started_at, input_tokens, output_tokens, cost_usd, projects_json, topic, title FROM session',
+      )
+      .all() as any[];
+    const totals = { sessions: rows.length, input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+    const byAgent: Record<string, UsageBucket> = {};
+    const byDay: Record<string, UsageBucket> = {};
+    const byProject: Record<string, UsageBucket> = {};
+    const add = (m: Record<string, UsageBucket>, key: string, r: any) => {
+      const b = (m[key] ??= { sessions: 0, input_tokens: 0, output_tokens: 0, cost_usd: 0 });
+      b.sessions++;
+      b.input_tokens += r.input_tokens;
+      b.output_tokens += r.output_tokens;
+      b.cost_usd += r.cost_usd;
+    };
+    for (const r of rows) {
+      totals.input_tokens += r.input_tokens;
+      totals.output_tokens += r.output_tokens;
+      totals.cost_usd += r.cost_usd;
+      add(byAgent, r.agent || 'unknown', r);
+      if (r.started_at) add(byDay, new Date(r.started_at).toISOString().slice(0, 10), r);
+      for (const p of safeJson(r.projects_json)) add(byProject, p, r);
+    }
+    totals.cost_usd = round6(totals.cost_usd);
+    for (const m of [byAgent, byDay, byProject]) for (const b of Object.values(m)) b.cost_usd = round6(b.cost_usd);
+
+    const days = opts.days ?? 30;
+    const recentDays = Object.entries(byDay)
+      .sort((a, b) => (a[0] < b[0] ? 1 : -1))
+      .slice(0, days)
+      .map(([day, b]) => ({ day, ...b }));
+    const topByCost = rows
+      .map((r) => ({
+        session_id: r.session_id,
+        agent: r.agent,
+        cost_usd: round6(r.cost_usd),
+        label: r.topic || r.title || r.session_id,
+      }))
+      .sort((a, b) => b.cost_usd - a.cost_usd)
+      .slice(0, opts.topN ?? 10);
+
+    return {
+      totals,
+      byAgent,
+      byDay: recentDays,
+      byProject,
+      topByCost,
+    };
+  }
+
   stats(): { sessions: number; turns: number; cost_usd: number; byAgent: Record<string, number> } {
     const s = this.db.prepare('SELECT COUNT(*) c, COALESCE(SUM(cost_usd),0) cost FROM session').get() as {
       c: number;