g3usage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 g3usage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# g3usage
+
+**ccusage for Grok Build** — analyze local Grok Build token usage and estimate costs.
+
+## Quick start
+
+```bash
+npx g3usage@latest
+```
+
+Or install globally:
+
+```bash
+npm install -g g3usage
+g3usage
+g3usage monthly
+g3usage session --json
+```
+
+From this repo (dev):
+
+```bash
+node bin/g3usage.js daily
+```
+
+## What it does
+
+Reads **local** session logs from:
+
+```
+$GROK_HOME/sessions/*/*/   # default: ~/.grok/sessions/
+```
+
+For each session it uses:
+
+| File | Role |
+|------|------|
+| `updates.jsonl` | `_meta.totalTokens` (cumulative context size per event) |
+| `summary.json` | session id, cwd, title, model, timestamps |
+| `signals.json` | models used, context peak fallback |
+
+Nothing is uploaded. Same idea as [ccusage](https://github.com/ccusage/ccusage), scoped to Grok Build only.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `daily` (default) | Group by date |
+| `weekly` | Group by ISO week |
+| `monthly` | Group by month |
+| `session` | One row per session |
+
+### Options
+
+```
+-j, --json              JSON output
+-s, --since <date>      From date (YYYY-MM-DD or YYYYMMDD)
+-u, --until <date>      Until date (inclusive)
+-z, --timezone <tz>     IANA timezone for grouping
+    --no-cost           Hide cost column
+    --path <dir>        Grok home override (default ~/.grok)
+-h, --help
+-v, --version
+```
+
+## Token estimates
+
+Grok Build currently logs **cumulative context size** (`totalTokens`), not billed input/output/cache splits.
+
+g3usage estimates per user turn (`promptId`):
+
+- **Input** ≈ first `totalTokens` seen in the turn (context at start)
+- **Output** ≈ growth during the turn (`peak − first`)
+
+Growth includes tool results, so output is an **upper-bound** estimate. Treat numbers as directional, not invoices.
+
+## Cost estimates
+
+Costs use public xAI API rates (see `src/pricing.js`). If you use **SuperGrok / X Premium+** subscription auth, you may not be billed per token — figures are **API-equivalent**.
+
+## Install
+
+```bash
+npm install -g .
+# then:
+g3usage
+g3usage session -s 2026-07-01
+```
+
+## License
+
+MIT

package/bin/g3usage.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err?.stack || err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "g3usage",
+  "version": "0.1.0",
+  "description": "Analyze Grok Build token usage and estimated costs from local session data (ccusage for Grok)",
+  "type": "module",
+  "bin": {
+    "g3usage": "bin/g3usage.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/g3usage.js",
+    "prepublishOnly": "node bin/g3usage.js --version"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "grok",
+    "xai",
+    "grok-build",
+    "usage",
+    "tokens",
+    "cli",
+    "ccusage",
+    "cost"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YOUR_USER/g3usage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YOUR_USER/g3usage/issues"
+  },
+  "homepage": "https://github.com/YOUR_USER/g3usage#readme"
+}

package/src/aggregate.js

@@ -0,0 +1,205 @@
+/**
+ * Date helpers + report aggregation (daily / weekly / monthly / session).
+ */
+
+function parseISO(s) {
+  if (!s) return null;
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** Format a Date in a timezone as YYYY-MM-DD */
+export function dateKey(date, timeZone) {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(date);
+}
+
+/** Monday-start ISO week key: YYYY-Www */
+export function weekKey(date, timeZone) {
+  // Use local calendar date in TZ, then compute ISO week on that Y-M-D as UTC noon
+  const ymd = dateKey(date, timeZone);
+  const [y, m, d] = ymd.split("-").map(Number);
+  const utc = new Date(Date.UTC(y, m - 1, d, 12));
+  // ISO week: Thursday determines the year
+  const day = utc.getUTCDay() || 7; // Mon=1..Sun=7
+  utc.setUTCDate(utc.getUTCDate() + 4 - day);
+  const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1));
+  const weekNo = Math.ceil(((utc - yearStart) / 86400000 + 1) / 7);
+  const weekYear = utc.getUTCFullYear();
+  return `${weekYear}-W${String(weekNo).padStart(2, "0")}`;
+}
+
+export function monthKey(date, timeZone) {
+  return dateKey(date, timeZone).slice(0, 7); // YYYY-MM
+}
+
+export function resolveTimezone(tz) {
+  if (tz) return tz;
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+/**
+ * Filter records by inclusive date range (YYYY-MM-DD or YYYYMMDD).
+ * Uses updatedAt (fallback createdAt).
+ */
+export function filterByDate(records, { since, until, timeZone } = {}) {
+  const tz = resolveTimezone(timeZone);
+  const norm = (s) => {
+    if (!s) return null;
+    const digits = String(s).replace(/-/g, "");
+    if (!/^\d{8}$/.test(digits)) return null;
+    return `${digits.slice(0, 4)}-${digits.slice(4, 6)}-${digits.slice(6, 8)}`;
+  };
+  const sinceK = norm(since);
+  const untilK = norm(until);
+
+  return records.filter((r) => {
+    const d = parseISO(r.updatedAt || r.createdAt);
+    if (!d) return !sinceK && !untilK;
+    const k = dateKey(d, tz);
+    if (sinceK && k < sinceK) return false;
+    if (untilK && k > untilK) return false;
+    return true;
+  });
+}
+
+function emptyBucket() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheCreateTokens: 0,
+    cacheReadTokens: 0,
+    totalTokens: 0,
+    peakTokens: 0,
+    cost: 0,
+    models: new Set(),
+    sessions: 0,
+  };
+}
+
+function addToBucket(b, r) {
+  b.inputTokens += r.inputTokens;
+  b.outputTokens += r.outputTokens;
+  b.cacheCreateTokens += r.cacheCreateTokens;
+  b.cacheReadTokens += r.cacheReadTokens;
+  b.totalTokens += r.totalTokens;
+  b.peakTokens += r.peakTokens;
+  b.cost += r.cost;
+  b.models.add(r.model);
+  for (const m of r.models || []) b.models.add(m);
+  b.sessions += 1;
+}
+
+function finalize(map) {
+  return [...map.entries()]
+    .map(([key, b]) => ({
+      key,
+      inputTokens: b.inputTokens,
+      outputTokens: b.outputTokens,
+      cacheCreateTokens: b.cacheCreateTokens,
+      cacheReadTokens: b.cacheReadTokens,
+      totalTokens: b.totalTokens,
+      peakTokens: b.peakTokens,
+      cost: b.cost,
+      models: [...b.models].sort(),
+      sessions: b.sessions,
+    }))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+export function aggregateBy(records, keyFn) {
+  const map = new Map();
+  for (const r of records) {
+    const d = parseISO(r.updatedAt || r.createdAt);
+    if (!d) continue;
+    const key = keyFn(d, r);
+    let b = map.get(key);
+    if (!b) {
+      b = emptyBucket();
+      map.set(key, b);
+    }
+    addToBucket(b, r);
+  }
+  return finalize(map);
+}
+
+export function dailyReport(records, timeZone) {
+  const tz = resolveTimezone(timeZone);
+  return aggregateBy(records, (d) => dateKey(d, tz));
+}
+
+export function weeklyReport(records, timeZone) {
+  const tz = resolveTimezone(timeZone);
+  return aggregateBy(records, (d) => weekKey(d, tz));
+}
+
+export function monthlyReport(records, timeZone) {
+  const tz = resolveTimezone(timeZone);
+  return aggregateBy(records, (d) => monthKey(d, tz));
+}
+
+export function sessionReport(records, timeZone) {
+  const tz = resolveTimezone(timeZone);
+  return records
+    .map((r) => {
+      const d = parseISO(r.updatedAt || r.createdAt);
+      return {
+        key: r.sessionId,
+        date: d ? dateKey(d, tz) : null,
+        title: r.title,
+        cwd: r.cwd,
+        model: r.model,
+        models: r.models,
+        inputTokens: r.inputTokens,
+        outputTokens: r.outputTokens,
+        cacheCreateTokens: r.cacheCreateTokens,
+        cacheReadTokens: r.cacheReadTokens,
+        totalTokens: r.totalTokens,
+        peakTokens: r.peakTokens,
+        cost: r.cost,
+        sessions: 1,
+        prompts: r.prompts,
+      };
+    })
+    .sort((a, b) => {
+      const ad = a.date || "";
+      const bd = b.date || "";
+      if (ad !== bd) return ad < bd ? -1 : 1;
+      return a.key < b.key ? -1 : 1;
+    });
+}
+
+export function totals(rows) {
+  const t = emptyBucket();
+  for (const r of rows) {
+    t.inputTokens += r.inputTokens || 0;
+    t.outputTokens += r.outputTokens || 0;
+    t.cacheCreateTokens += r.cacheCreateTokens || 0;
+    t.cacheReadTokens += r.cacheReadTokens || 0;
+    t.totalTokens += r.totalTokens || 0;
+    t.peakTokens += r.peakTokens || 0;
+    t.cost += r.cost || 0;
+    t.sessions += r.sessions || 0;
+    for (const m of r.models || []) t.models.add(m);
+    if (r.model) t.models.add(r.model);
+  }
+  return {
+    inputTokens: t.inputTokens,
+    outputTokens: t.outputTokens,
+    cacheCreateTokens: t.cacheCreateTokens,
+    cacheReadTokens: t.cacheReadTokens,
+    totalTokens: t.totalTokens,
+    peakTokens: t.peakTokens,
+    cost: t.cost,
+    models: [...t.models].sort(),
+    sessions: t.sessions,
+  };
+}

package/src/cli.js

@@ -0,0 +1,316 @@
+import { loadSessions, grokHome, sessionsRoot } from "./load.js";
+import {
+  filterByDate,
+  dailyReport,
+  weeklyReport,
+  monthlyReport,
+  sessionReport,
+  totals,
+  resolveTimezone,
+} from "./aggregate.js";
+import {
+  printTable,
+  formatNum,
+  formatCost,
+  c,
+} from "./table.js";
+
+const VERSION = "0.1.0";
+
+const HELP = `
+${c.bold("g3usage")} — Grok Build usage analysis (ccusage for Grok)
+
+${c.bold("USAGE")}
+  g3usage [daily] [options]
+  g3usage <command> [options]
+
+${c.bold("COMMANDS")}
+  daily      Show usage grouped by date (default)
+  weekly     Show usage grouped by week
+  monthly    Show usage grouped by month
+  session    Show usage grouped by session
+
+${c.bold("OPTIONS")}
+  -j, --json              Output JSON
+  -s, --since <date>      Filter from date (YYYY-MM-DD or YYYYMMDD)
+  -u, --until <date>      Filter until date (inclusive)
+  -z, --timezone <tz>     IANA timezone for date grouping
+      --no-cost           Hide cost column
+      --path <dir>        Override Grok home (default: $GROK_HOME or ~/.grok)
+  -h, --help              Show help
+  -v, --version           Show version
+
+${c.bold("NOTES")}
+  Reads local session logs from ~/.grok/sessions (never uploads data).
+  Token input/output is estimated from cumulative context sizes in
+  updates.jsonl — Grok does not currently log billed I/O splits.
+  Cost is API-equivalent; SuperGrok subscription usage may not bill per token.
+`.trim();
+
+function parseArgs(argv) {
+  const opts = {
+    command: "daily",
+    json: false,
+    since: null,
+    until: null,
+    timezone: null,
+    noCost: false,
+    path: null,
+    help: false,
+    version: false,
+  };
+
+  const commands = new Set(["daily", "weekly", "monthly", "session"]);
+  const args = [...argv];
+
+  if (args[0] && !args[0].startsWith("-") && commands.has(args[0])) {
+    opts.command = args.shift();
+  }
+
+  while (args.length) {
+    const a = args.shift();
+    switch (a) {
+      case "-h":
+      case "--help":
+        opts.help = true;
+        break;
+      case "-v":
+      case "--version":
+        opts.version = true;
+        break;
+      case "-j":
+      case "--json":
+        opts.json = true;
+        break;
+      case "--no-cost":
+        opts.noCost = true;
+        break;
+      case "-s":
+      case "--since":
+        opts.since = args.shift();
+        break;
+      case "-u":
+      case "--until":
+        opts.until = args.shift();
+        break;
+      case "-z":
+      case "--timezone":
+        opts.timezone = args.shift();
+        break;
+      case "--path":
+        opts.path = args.shift();
+        break;
+      default:
+        if (a.startsWith("-")) {
+          throw new Error(`Unknown option: ${a}\n\n${HELP}`);
+        }
+        if (commands.has(a)) {
+          opts.command = a;
+        } else {
+          throw new Error(`Unknown command: ${a}\n\n${HELP}`);
+        }
+    }
+  }
+
+  return opts;
+}
+
+function shortPath(p, max = 36) {
+  if (!p) return "";
+  const home = process.env.HOME || "";
+  let s = home && p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+  if (s.length <= max) return s;
+  return "…" + s.slice(-(max - 1));
+}
+
+function rowCells(row, { noCost, mode }) {
+  const models =
+    (row.models && row.models.length
+      ? row.models
+      : row.model
+        ? [row.model]
+        : []
+    )
+      .map((m) => m)
+      .join(", ");
+
+  if (mode === "session") {
+    const label = row.title
+      ? `${row.key.slice(0, 8)}… ${row.title.slice(0, 28)}`
+      : row.key.slice(0, 13);
+    const cells = [
+      row.date || "?",
+      label,
+      models || "—",
+      formatNum(row.inputTokens),
+      formatNum(row.outputTokens),
+      formatNum(row.totalTokens),
+    ];
+    if (!noCost) cells.push(formatCost(row.cost));
+    return cells;
+  }
+
+  const cells = [
+    row.key,
+    models || "—",
+    formatNum(row.inputTokens),
+    formatNum(row.outputTokens),
+    formatNum(row.totalTokens),
+    String(row.sessions ?? ""),
+  ];
+  if (!noCost) cells.push(formatCost(row.cost));
+  return cells;
+}
+
+function headersFor(mode, noCost) {
+  if (mode === "session") {
+    const h = ["Date", "Session", "Models", "Input", "Output", "Total"];
+    if (!noCost) h.push("Cost (USD)");
+    return h;
+  }
+  const label =
+    mode === "monthly" ? "Month" : mode === "weekly" ? "Week" : "Date";
+  const h = [label, "Models", "Input", "Output", "Total", "Sessions"];
+  if (!noCost) h.push("Cost (USD)");
+  return h;
+}
+
+function alignFor(mode, noCost) {
+  if (mode === "session") {
+    return ["left", "left", "left", "right", "right", "right", "right"].slice(
+      0,
+      noCost ? 6 : 7,
+    );
+  }
+  return ["left", "left", "right", "right", "right", "right", "right"].slice(
+    0,
+    noCost ? 6 : 7,
+  );
+}
+
+function printReport(mode, rows, opts) {
+  const t = totals(rows);
+  const titleMap = {
+    daily: "Grok Build Usage Report - Daily",
+    weekly: "Grok Build Usage Report - Weekly",
+    monthly: "Grok Build Usage Report - Monthly",
+    session: "Grok Build Usage Report - Session",
+  };
+
+  const headers = headersFor(mode, opts.noCost);
+  const tableRows = rows.map((r) => rowCells(r, { noCost: opts.noCost, mode }));
+
+  let footer;
+  if (mode === "session") {
+    footer = [
+      "Total",
+      `${t.sessions} sessions`,
+      t.models.join(", "),
+      formatNum(t.inputTokens),
+      formatNum(t.outputTokens),
+      formatNum(t.totalTokens),
+    ];
+    if (!opts.noCost) footer.push(formatCost(t.cost));
+  } else {
+    footer = [
+      "Total",
+      t.models.join(", "),
+      formatNum(t.inputTokens),
+      formatNum(t.outputTokens),
+      formatNum(t.totalTokens),
+      String(t.sessions),
+    ];
+    if (!opts.noCost) footer.push(formatCost(t.cost));
+  }
+
+  printTable({
+    title: titleMap[mode],
+    headers,
+    rows: tableRows,
+    align: alignFor(mode, opts.noCost),
+    footer,
+  });
+
+  if (!opts.noCost) {
+    console.log(
+      c.dim(
+        "  Costs are API-equivalent estimates. SuperGrok / subscription usage may not bill per token.",
+      ),
+    );
+  }
+  console.log(
+    c.dim(
+      "  Input/Output estimated from cumulative context sizes in local session logs.",
+    ),
+  );
+  console.log();
+}
+
+export async function main(argv) {
+  const opts = parseArgs(argv);
+
+  if (opts.help) {
+    console.log(HELP);
+    return;
+  }
+  if (opts.version) {
+    console.log(`g3usage ${VERSION}`);
+    return;
+  }
+
+  const home = opts.path || grokHome();
+  const root = sessionsRoot(home);
+
+  if (!opts.json) {
+    // quiet load message only when empty later
+  }
+
+  let records = loadSessions({ home });
+  const tz = resolveTimezone(opts.timezone);
+  records = filterByDate(records, {
+    since: opts.since,
+    until: opts.until,
+    timeZone: tz,
+  });
+
+  let rows;
+  switch (opts.command) {
+    case "weekly":
+      rows = weeklyReport(records, tz);
+      break;
+    case "monthly":
+      rows = monthlyReport(records, tz);
+      break;
+    case "session":
+      rows = sessionReport(records, tz);
+      break;
+    case "daily":
+    default:
+      rows = dailyReport(records, tz);
+  }
+
+  if (opts.json) {
+    const payload = {
+      command: opts.command,
+      timezone: tz,
+      grokHome: home,
+      sessionsPath: root,
+      totals: totals(rows),
+      rows,
+    };
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (rows.length === 0) {
+    console.log(
+      c.yellow(
+        `\nNo Grok Build usage found under ${root}\n` +
+          `Run some sessions with Grok Build first, or pass --path.\n`,
+      ),
+    );
+    return;
+  }
+
+  printReport(opts.command, rows, opts);
+}

package/src/load.js

@@ -0,0 +1,200 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { estimateCost } from "./pricing.js";
+
+export function grokHome() {
+  return process.env.GROK_HOME || path.join(os.homedir(), ".grok");
+}
+
+export function sessionsRoot(home = grokHome()) {
+  return path.join(home, "sessions");
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse updates.jsonl for per-prompt token estimates.
+ *
+ * Grok exposes cumulative context size as `_meta.totalTokens`, not billed
+ * input/output. We approximate:
+ *   - input  ≈ first totalTokens observed in a prompt (context at turn start)
+ *   - output ≈ max(0, peak - first) within that prompt (growth during the turn)
+ *
+ * Growth includes tool results, so "output" is an upper-bound estimate.
+ */
+function parseUpdates(updatesPath) {
+  if (!fs.existsSync(updatesPath)) {
+    return { inputTokens: 0, outputTokens: 0, peakTokens: 0, prompts: 0 };
+  }
+
+  /** @type {Map<string, { first: number, peak: number }>} */
+  const byPrompt = new Map();
+  let peakTokens = 0;
+  let lineNo = 0;
+
+  const text = fs.readFileSync(updatesPath, "utf8");
+  for (const line of text.split("\n")) {
+    lineNo++;
+    if (!line.trim()) continue;
+    let o;
+    try {
+      o = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const meta = o?.params?._meta;
+    if (!meta || typeof meta.totalTokens !== "number") continue;
+
+    const tt = meta.totalTokens;
+    if (tt > peakTokens) peakTokens = tt;
+
+    const pid = meta.promptId || `_line_${lineNo}`;
+    let entry = byPrompt.get(pid);
+    if (!entry) {
+      // first observation for this turn (chronological — file is append-only)
+      entry = { first: tt, peak: tt };
+      byPrompt.set(pid, entry);
+    } else if (tt > entry.peak) {
+      entry.peak = tt;
+    }
+  }
+
+  let inputTokens = 0;
+  let outputTokens = 0;
+  for (const { first, peak } of byPrompt.values()) {
+    inputTokens += first;
+    outputTokens += Math.max(0, peak - first);
+  }
+
+  return {
+    inputTokens,
+    outputTokens,
+    peakTokens,
+    prompts: byPrompt.size,
+  };
+}
+
+function listSessionDirs(root) {
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const project of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!project.isDirectory()) continue;
+    const projectPath = path.join(root, project.name);
+    for (const sid of fs.readdirSync(projectPath, { withFileTypes: true })) {
+      if (!sid.isDirectory()) continue;
+      out.push(path.join(projectPath, sid.name));
+    }
+  }
+  return out;
+}
+
+/**
+ * @typedef {object} UsageRecord
+ * @property {string} sessionId
+ * @property {string|null} cwd
+ * @property {string|null} title
+ * @property {string} model
+ * @property {string[]} models
+ * @property {string|null} createdAt ISO
+ * @property {string|null} updatedAt ISO
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {number} cacheReadTokens always 0 for now (not in local logs)
+ * @property {number} cacheCreateTokens always 0
+ * @property {number} totalTokens input+output estimate
+ * @property {number} peakTokens max context size in session
+ * @property {number} cost USD estimate
+ * @property {string|null} agentName
+ * @property {number} prompts
+ */
+
+/** @returns {UsageRecord[]} */
+export function loadSessions({ home = grokHome() } = {}) {
+  const root = sessionsRoot(home);
+  const dirs = listSessionDirs(root);
+  /** @type {UsageRecord[]} */
+  const records = [];
+
+  for (const dir of dirs) {
+    const summary = readJson(path.join(dir, "summary.json")) || {};
+    const signals = readJson(path.join(dir, "signals.json")) || {};
+    const usage = parseUpdates(path.join(dir, "updates.jsonl"));
+
+    // Prefer signals peak when updates empty/missing
+    const peakTokens = Math.max(
+      usage.peakTokens,
+      signals.contextTokensUsed || 0,
+    );
+
+    const models = new Set();
+    if (Array.isArray(signals.modelsUsed)) {
+      for (const m of signals.modelsUsed) if (m) models.add(m);
+    }
+    if (signals.primaryModelId) models.add(signals.primaryModelId);
+    if (summary.current_model_id) models.add(summary.current_model_id);
+
+    const model =
+      signals.primaryModelId ||
+      summary.current_model_id ||
+      [...models][0] ||
+      "unknown";
+
+    // If no prompt breakdown, fall back to peak as "total" with no split
+    let { inputTokens, outputTokens, prompts } = usage;
+    if (prompts === 0 && peakTokens > 0) {
+      // unknown split — attribute all to input (context snapshot)
+      inputTokens = peakTokens;
+      outputTokens = 0;
+    }
+
+    const totalTokens = inputTokens + outputTokens;
+    const cost = estimateCost(model, {
+      input: inputTokens,
+      output: outputTokens,
+    });
+
+    const sessionId =
+      summary?.info?.id || path.basename(dir);
+
+    const createdAt =
+      summary.created_at || summary.updated_at || null;
+    const updatedAt =
+      summary.last_active_at || summary.updated_at || createdAt;
+
+    // Skip empty ghost sessions
+    if (totalTokens === 0 && peakTokens === 0 && !summary.num_messages) {
+      continue;
+    }
+
+    records.push({
+      sessionId,
+      cwd: summary?.info?.cwd || null,
+      title:
+        summary.generated_title ||
+        summary.session_summary ||
+        null,
+      model,
+      models: [...models],
+      createdAt,
+      updatedAt,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens: 0,
+      cacheCreateTokens: 0,
+      totalTokens,
+      peakTokens,
+      cost,
+      agentName: summary.agent_name || null,
+      prompts,
+    });
+  }
+
+  return records;
+}

package/src/pricing.js

@@ -0,0 +1,72 @@
+/**
+ * Token pricing ($ / 1M tokens) for API-equivalent cost estimates.
+ *
+ * Sources:
+ * - xAI API: https://docs.x.ai/developers/pricing
+ * - Cursor Composer 2.5: https://cursor.com/blog/composer-2-5
+ *   and https://cursor.com/docs/models/cursor-composer-2-5
+ * - Cursor model table: https://cursor.com/docs/models-and-pricing
+ *
+ * SuperGrok / subscription sessions may not bill per token —
+ * reported costs are API-equivalent estimates only.
+ */
+export const PRICING = {
+  // xAI Chat API — https://docs.x.ai/developers/pricing
+  "grok-4.5": { input: 2.0, cachedInput: 0.5, output: 6.0 },
+  "grok-4.3": { input: 1.25, cachedInput: 0.2, output: 2.5 },
+  "grok-4.20-multi-agent-0309": { input: 1.25, cachedInput: 0.2, output: 2.5 },
+  "grok-4.20-0309-reasoning": { input: 1.25, cachedInput: 0.2, output: 2.5 },
+  "grok-4.20-0309-non-reasoning": { input: 1.25, cachedInput: 0.2, output: 2.5 },
+  "grok-4": { input: 3.0, cachedInput: 0.75, output: 15.0 },
+  "grok-4-0709": { input: 3.0, cachedInput: 0.75, output: 15.0 },
+  "grok-4-fast": { input: 0.2, cachedInput: 0.05, output: 0.5 },
+  "grok-4-1-fast": { input: 0.2, cachedInput: 0.05, output: 0.5 },
+  "grok-code-fast-1": { input: 0.2, cachedInput: 0.05, output: 1.5 },
+  "grok-3": { input: 3.0, cachedInput: 0.75, output: 15.0 },
+  "grok-3-mini": { input: 0.3, cachedInput: 0.075, output: 0.5 },
+
+  // xAI Code API
+  "grok-build-0.1": { input: 1.0, cachedInput: 0.2, output: 2.0 },
+  // Build UI alias often maps to 4.5 / grok-build-latest
+  "grok-build": { input: 2.0, cachedInput: 0.5, output: 6.0 },
+  "grok-build-latest": { input: 2.0, cachedInput: 0.5, output: 6.0 },
+
+  // Cursor Composer 2.5 (also used inside Grok Build as grok-composer-*)
+  // Standard: $0.50 in / $2.50 out; Fast (default): $3 in / $15 out
+  "composer-2.5": { input: 0.5, cachedInput: 0.2, output: 2.5 },
+  "composer-2.5-fast": { input: 3.0, cachedInput: 0.5, output: 15.0 },
+  "grok-composer-2.5": { input: 0.5, cachedInput: 0.2, output: 2.5 },
+  "grok-composer-2.5-fast": { input: 3.0, cachedInput: 0.5, output: 15.0 },
+};
+
+const DEFAULT = { input: 2.0, cachedInput: 0.5, output: 6.0 };
+
+export function priceFor(model) {
+  if (!model) return DEFAULT;
+  if (PRICING[model]) return PRICING[model];
+
+  const lower = String(model).toLowerCase();
+
+  // Prefer exact-ish substring matches for composer variants before generic prefixes
+  if (lower.includes("composer-2.5-fast") || lower.includes("composer-2.5_fast")) {
+    return PRICING["composer-2.5-fast"];
+  }
+  if (lower.includes("composer-2.5") || lower.includes("composer_2.5")) {
+    return PRICING["composer-2.5"];
+  }
+
+  // fuzzy: match prefix keys longest-first
+  const keys = Object.keys(PRICING).sort((a, b) => b.length - a.length);
+  for (const k of keys) {
+    if (model === k || model.startsWith(k) || k.startsWith(model)) {
+      return PRICING[k];
+    }
+  }
+  return DEFAULT;
+}
+
+/** Estimate USD cost from token counts. */
+export function estimateCost(model, { input = 0, output = 0, cacheRead = 0 } = {}) {
+  const p = priceFor(model);
+  return (input * p.input + output * p.output + cacheRead * p.cachedInput) / 1_000_000;
+}

package/src/table.js

@@ -0,0 +1,103 @@
+/** Minimal table renderer (no deps). */
+
+const useColor =
+  process.stdout.isTTY &&
+  !process.env.NO_COLOR &&
+  process.env.FORCE_COLOR !== "0";
+
+const c = {
+  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  cyan: (s) => (useColor ? `\x1b[36m${s}\x1b[0m` : s),
+  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+};
+
+export function formatNum(n) {
+  if (n == null || Number.isNaN(n)) return "0";
+  return Math.round(n).toLocaleString("en-US");
+}
+
+export function formatCost(n) {
+  if (n == null || Number.isNaN(n)) return "$0.00";
+  if (n > 0 && n < 0.01) return `$${n.toFixed(4)}`;
+  return `$${n.toFixed(2)}`;
+}
+
+function pad(str, width, align = "left") {
+  const s = String(str);
+  const visible = s.replace(/\x1b\[[0-9;]*m/g, "");
+  const padLen = Math.max(0, width - visible.length);
+  if (align === "right") return " ".repeat(padLen) + s;
+  return s + " ".repeat(padLen);
+}
+
+function visibleLen(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.title
+ * @param {string[]} opts.headers
+ * @param {string[][]} opts.rows
+ * @param {('left'|'right')[]} [opts.align]
+ * @param {string[]} [opts.footer]
+ */
+export function printTable({ title, headers, rows, align = [], footer }) {
+  const cols = headers.length;
+  const widths = headers.map((h, i) => {
+    let w = visibleLen(h);
+    for (const row of rows) w = Math.max(w, visibleLen(row[i] ?? ""));
+    if (footer) w = Math.max(w, visibleLen(footer[i] ?? ""));
+    return Math.min(w, 48);
+  });
+
+  const rule = (left, mid, right, fill = "─") =>
+    left + widths.map((w) => fill.repeat(w + 2)).join(mid) + right;
+
+  const line = (cells, bold = false) => {
+    const parts = cells.map((cell, i) => {
+      let text = String(cell ?? "");
+      // truncate long cells
+      const vis = visibleLen(text);
+      if (vis > widths[i]) {
+        const plain = text.replace(/\x1b\[[0-9;]*m/g, "");
+        text = plain.slice(0, Math.max(0, widths[i] - 1)) + "…";
+      }
+      const a = align[i] || (i === 0 ? "left" : "right");
+      return pad(text, widths[i], a);
+    });
+    const body = "│ " + parts.join(" │ ") + " │";
+    return bold ? c.bold(body) : body;
+  };
+
+  const boxTitle = title;
+  const inner = Math.max(
+    boxTitle.length + 2,
+    widths.reduce((a, w) => a + w + 3, 1),
+  );
+  console.log();
+  console.log(c.cyan("╭" + "─".repeat(inner) + "╮"));
+  console.log(c.cyan("│") + c.bold(pad(` ${boxTitle}`, inner)) + c.cyan("│"));
+  console.log(c.cyan("╰" + "─".repeat(inner) + "╯"));
+  console.log();
+
+  console.log(rule("┌", "┬", "┐"));
+  console.log(line(headers, true));
+  console.log(rule("├", "┼", "┤"));
+  for (const row of rows) console.log(line(row));
+  if (footer) {
+    console.log(rule("├", "┼", "┤"));
+    console.log(line(footer, true));
+  }
+  console.log(rule("└", "┴", "┘"));
+  console.log();
+}
+
+export function modelsCell(models) {
+  if (!models?.length) return "";
+  return models.map((m) => `- ${m}`).join("\n");
+}
+
+export { c };