ai-usage-analyzer 0.3.2 → 0.5.0

package/README.md

@@ -1,17 +1,11 @@
 # ai-usage-analyzer
 
-TUI analyzer for local AI coding agent token consumption. Auto-detects
+A local web dashboard for AI coding agent token consumption. Auto-detects
 **Claude Code**, **Codex**, **OpenCode**, **MimoCode**, **GitHub Copilot**,
-**Antigravity**, and **Gemini CLI** data directories — no hardcoded paths.
+**Antigravity**, and **Gemini CLI** data directories.
 
-```
-╭──────────────────────────────────────────────────────╮
-│               ◆  AI TOKEN ANALYZER  ◆                │
-│                                                      │
-│  411 sessions  •  1.56B total tokens  •  $29.40 USD  │
-│            range: 2026-04-01  →  2026-06-27          │
-╰──────────────────────────────────────────────────────╯
-```
+The default command starts a local server and opens the dashboard in your browser.
+Usage data stays on your device. Press Ctrl+C in the terminal to stop the server.
 
 ## Install
 
@@ -31,18 +25,19 @@ The short alias `ai-usage` is also installed and works identically.
 ## Usage
 
 ```bash
-ai-usage-analyzer                  # default TUI
-ai-usage-analyzer --top 10         # show top 10 heaviest sessions
+ai-usage-analyzer                  # open the dashboard
+ai-usage-analyzer --static --top 10 # terminal report with top 10 sessions
 ai-usage-analyzer --json           # machine-readable JSON
 ai-usage-analyzer --md > report.md # save as markdown
+ai-usage-analyzer --json --quota    # include a live quota snapshot
 ```
 
 ## Supported tools
 
 | Tool | Default path | Tokens |
 |---|---|---|
-| Claude Code    | `~/.claude/projects`                | presence only |
-| Codex          | `~/.codex/sessions/YYYY/MM/DD/`    | yes |
+| Claude Code    | `~/.claude/projects`                | yes (estimated cost) |
+| Codex          | `~/.codex/sessions/` and `archived_sessions/` | yes (estimated cost) |
 | OpenCode       | `~/.local/share/opencode/opencode.db` | yes (+cost) |
 | MimoCode       | `~/.local/share/mimocode/mimocode.db` | yes (+cost) |
 | GitHub Copilot | `~/.copilot/session-state/`        | presence only |
@@ -65,14 +60,34 @@ For tools that record token data, the analyzer shows input, output, cache
 read, cache write, and reasoning tokens. Cache hits are cheap; reasoning is
 the extended-thinking/chain-of-thought cost.
 
+## Quotas
+
+Reports stay offline unless `--quota` is supplied. This requests Claude and Codex
+usage limits using your existing logins. Vendor endpoints are internal and can
+change. Codex credentials may be refreshed and written back to `auth.json`.
+
+## Costs
+
+Claude and Codex costs use bundled API rates per model and are estimates,
+not subscription charges or invoices. `~` marks an estimate, `*` marks a
+partial total, and `n/a` means unavailable. Unknown models are listed rather
+than assigned a fallback price. OpenCode and MimoCode costs are read from
+their local databases. Pricing uses standard public API rates and the
+five-minute Claude cache-write rate; regional, batch, and other modifiers may
+differ. Rates are versioned with the app and can become outdated.
+
 ## How it works
 
 ```
 src/
 ├── detectors.js   auto-path discovery (env → well-known locations)
 ├── loaders.js     SQLite + JSONL parsers → unified session record
+├── quota.js       Claude and Codex quota snapshots
+├── pricing.js     bundled model pricing and estimates
+├── live.js        incremental live usage monitor
 ├── aggregate.js   per-project / per-week / per-month grouping
-├── render.js      TUI  •  markdown.js  →  Markdown report
+├── server.js      local dashboard server
+├── render.js      static terminal report  •  markdown.js  →  Markdown report
 bin/
 └── ai-usage.js    entry point
 ```

package/bin/ai-usage.js

@@ -2,30 +2,41 @@
 // AI Usage Analyzer - TUI for local AI coding agent token consumption
 // Auto-detects: Claude Code, Codex, OpenCode, MimoCode, Copilot, Antigravity, Gemini
 
-import { detectAll } from '../src/detectors.js';
-import { loadAll, dateRange } from '../src/loaders.js';
-import { overall } from '../src/aggregate.js';
+import { overall } from "../src/aggregate.js";
+import { detectAll } from "../src/detectors.js";
+import { dateRange, loadAll } from "../src/loaders.js";
+import { renderMarkdown } from "../src/markdown.js";
 import {
-  renderHeader, renderDetections, renderOverview,
-  renderPerProject, renderPerTool, renderPerToolPerMonth,
-  renderPerMonth, renderPerWeek,
-  renderTopSessions, renderNotes,
-} from '../src/render.js';
-import { renderMarkdown } from '../src/markdown.js';
+    renderDetections,
+    renderHeader,
+    renderNotes,
+    renderOverview,
+    renderPerMonth,
+    renderPerProject,
+    renderPerTool,
+    renderPerToolPerMonth,
+    renderPerWeek,
+    renderTopSessions,
+} from "../src/render.js";
+import { startDashboard } from "../src/server.js";
+import { collectQuotas, renderQuota } from "../src/quota.js";
 
 const args = process.argv.slice(2);
-const hasFlag = (name) => args.includes(`--${name}`) || args.includes(`-${name}`);
-const showHelp = hasFlag('help') || hasFlag('h');
-const jsonOut = hasFlag('json');
-const mdOut = hasFlag('markdown') || hasFlag('md');
+const hasFlag = (name) =>
+  args.includes(`--${name}`) || args.includes(`-${name}`);
+const showHelp = hasFlag("help") || hasFlag("h");
+const jsonOut = hasFlag("json");
+const mdOut = hasFlag("markdown") || hasFlag("md");
+const quotaOut = hasFlag("quota");
+const staticOut = hasFlag("static") || hasFlag("no-interactive");
 const topN = (() => {
-  const i = args.indexOf('--top');
+  const i = args.indexOf("--top");
   if (i < 0) return 5;
   const v = parseInt(args[i + 1], 10);
   return Number.isFinite(v) && v > 0 ? v : 5;
 })();
 const yearFilter = (() => {
-  const i = args.indexOf('--year');
+  const i = args.indexOf("--year");
   if (i < 0) return null;
   const v = parseInt(args[i + 1], 10);
   return Number.isFinite(v) && v > 1970 && v < 3000 ? v : null;
@@ -33,24 +44,26 @@ const yearFilter = (() => {
 
 if (showHelp) {
   console.log(`
-ai-usage-analyzer — local AI coding agent token consumption TUI
+ai-usage-analyzer — local AI coding agent usage dashboard
 
 Usage:
   ai-usage [options]
 
 Options:
-  -h, --help         Show this help
-  --json             Output machine-readable JSON instead of TUI
-  --markdown, --md   Output as a Markdown report (GitHub-flavored tables)
-  --top N            Show top N heaviest sessions (default: 5)
-  --year YYYY        Filter records to a single year (e.g. --year 2026)
+  -h, --help               Show this help
+  --json                   Output machine-readable JSON instead of TUI
+  --markdown, --md         Output as a Markdown report (GitHub-flavored tables)
+  --static, --no-interactive  Disable interactive mode; dump all sections at once
+  --quota                  Include live quota in JSON, Markdown, or static reports
+  --top N                  Show top N sessions in reports (default: 5)
+  --year YYYY              Filter reports to a single year (e.g. --year 2026)
 
 Examples:
-  ai-usage                       # default TUI
-  ai-usage --year 2026           # TUI, only 2026 sessions
+  ai-usage                       # open dashboard
+  ai-usage --static --year 2026  # report, only 2026 sessions
   ai-usage --json | jq .summary  # pipe to jq
   ai-usage --md > report.md      # save as markdown
-  ai-usage --top 20              # show top 20 sessions
+  ai-usage --static --top 20     # show top 20 sessions
 
 Environment overrides (per-tool data path):
   CLAUDE_HOME, CODEX_HOME, OPENCODE_HOME, MIMOCODE_HOME,
@@ -70,27 +83,38 @@ Supported tools:
 }
 
 if (jsonOut && mdOut) {
-  console.error('Error: --json and --markdown are mutually exclusive.');
+  console.error("Error: --json and --markdown are mutually exclusive.");
   process.exit(2);
 }
 
 async function main() {
+  if (!jsonOut && !mdOut && !staticOut) {
+    await startDashboard();
+    return;
+  }
   const t0 = Date.now();
   const detections = detectAll();
   const { records: allRecords, errors } = await loadAll(detections);
 
   // Apply --year filter before any aggregation so dateRange and totals
   // reflect the filtered set.
-  const records = yearFilter !== null
-    ? allRecords.filter(r => r.month && r.month.startsWith(`${yearFilter}-`))
-    : allRecords;
+  const records =
+    yearFilter !== null
+      ? allRecords.filter(
+          (r) => r.month && r.month.startsWith(`${yearFilter}-`),
+        )
+      : allRecords;
 
   const range = dateRange(records);
   const tot = overall(records);
 
+  const quotaPromise = quotaOut ? collectQuotas() : null;
+
   if (jsonOut) {
+    const quotas = quotaPromise ? await quotaPromise : null;
     const out = {
       detections,
+      ...(quotas ? { quotas } : {}),
       summary: tot,
       dateRange: range,
       sessions: records,
@@ -105,19 +129,25 @@ async function main() {
 
   if (mdOut) {
     const out = renderMarkdown({
-      records, detections, errors,
-      dateRange: range, topN, generatedAt: new Date().toISOString(),
+      records,
+      detections,
+      errors,
+      dateRange: range,
+      topN,
+      generatedAt: new Date().toISOString(),
     });
-    process.stdout.write(out);
+    const quota = quotaPromise ? await quotaPromise : null;
+    process.stdout.write(out + (quota ? `\n## Quotas\n\n\`\`\`\n${renderQuota(quota)}\n\`\`\`\n` : ""));
     return;
   }
 
-  // TUI render
+  // Static fallback (--static, --no-interactive, or piped output)
   const sections = [
     renderHeader({
       totalSessions: records.length,
       totalTokens: tot.tokensTotal,
       totalCost: tot.cost,
+      costStatus: tot.costStatus,
       dateRange: range,
     }),
     renderDetections(detections),
@@ -134,11 +164,12 @@ async function main() {
     );
   }
   sections.push(renderNotes(detections, errors));
+  if (quotaPromise) sections.push(renderQuota(await quotaPromise));
 
-  console.log(sections.join('\n\n'));
+  console.log(sections.join("\n\n"));
 }
 
-main().catch(err => {
-  console.error('Fatal error:', err);
+main().catch((err) => {
+  console.error("Fatal error:", err);
   process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-usage-analyzer",
-  "version": "0.3.2",
-  "description": "TUI analyzer for local AI coding agent token usage. Auto-detects Claude Code, Codex, OpenCode, MimoCode, Copilot, Antigravity, and Gemini.",
+  "version": "0.5.0",
+  "description": "Local web dashboard for AI coding agent token usage.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
   "bin": {
@@ -11,7 +11,8 @@
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "web"
   ],
   "scripts": {
     "start": "node bin/ai-usage.js",
@@ -31,8 +32,8 @@
     "copilot",
     "antigravity",
     "gemini",
-    "tui",
-    "cli"
+    "cli",
+    "dashboard"
   ],
   "author": "ade",
   "license": "MIT",
@@ -48,6 +49,7 @@
     "boxen": "^7.1.1",
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.5",
-    "gradient-string": "^2.0.2"
+    "gradient-string": "^2.0.2",
+    "gsap": "^3.15.0"
   }
 }

package/src/aggregate.js

@@ -1,9 +1,18 @@
 // Group session records by various dimensions and compute stats.
 
 const MONTH_NAMES = {
-  '01': 'Jan', '02': 'Feb', '03': 'Mar', '04': 'Apr',
-  '05': 'May', '06': 'Jun', '07': 'Jul', '08': 'Aug',
-  '09': 'Sep', '10': 'Oct', '11': 'Nov', '12': 'Dec',
+  "01": "Jan",
+  "02": "Feb",
+  "03": "Mar",
+  "04": "Apr",
+  "05": "May",
+  "06": "Jun",
+  "07": "Jul",
+  "08": "Aug",
+  "09": "Sep",
+  10: "Oct",
+  11: "Nov",
+  12: "Dec",
 };
 
 function sum(arr, key) {
@@ -25,16 +34,23 @@ export function groupBy(records, keyFn) {
 }
 
 function summarize(records) {
+  const statuses = records.map(r => r.costStatus || 'recorded');
+  const incomplete = statuses.some(status => status === 'partial' || status === 'unavailable');
+  const known = statuses.some(status => status !== 'unavailable');
+  const costStatus = !statuses.length ? 'unavailable' : incomplete ? (known ? 'partial' : 'unavailable') : statuses.includes('estimated') ? 'estimated' : 'recorded';
+  const unknownModels = [...new Set(records.flatMap(r => r.unknownModels || []))];
   return {
     n: records.length,
-    tokensTotal: sum(records, 'tokensTotal'),
-    tokensInput: sum(records, 'tokensInput'),
-    tokensOutput: sum(records, 'tokensOutput'),
-    tokensCacheRead: sum(records, 'tokensCacheRead'),
-    tokensCacheWrite: sum(records, 'tokensCacheWrite'),
-    tokensReasoning: sum(records, 'tokensReasoning'),
-    cost: sum(records, 'cost'),
-    avg: avg(records, 'tokensTotal'),
+    tokensTotal: sum(records, "tokensTotal"),
+    tokensInput: sum(records, "tokensInput"),
+    tokensOutput: sum(records, "tokensOutput"),
+    tokensCacheRead: sum(records, "tokensCacheRead"),
+    tokensCacheWrite: sum(records, "tokensCacheWrite"),
+    tokensReasoning: sum(records, "tokensReasoning"),
+    cost: sum(records, "cost"),
+    costStatus,
+    unknownModels,
+    avg: avg(records, "tokensTotal"),
   };
 }
 
@@ -46,21 +62,34 @@ function toolBreakdown(records) {
   return byTool;
 }
 
+function toolSessionCount(records) {
+  const nByTool = {};
+  for (const r of records) {
+    nByTool[r.tool] = (nByTool[r.tool] || 0) + 1;
+  }
+  return nByTool;
+}
+
 export function perProject(records) {
   // One row per project — tool mix is shown via the stacked bar / byTool,
   // not as a separate column. Detailed per-tool-per-project breakdown
   // is no longer surfaced here; the "Per Tool per Month" section is the
   // place to see per-tool data over time.
-  const m = groupBy(records, r => r.project);
+  const m = groupBy(records, (r) => r.project);
   const out = [];
   for (const [project, arr] of m) {
-    out.push({ project, ...summarize(arr), byTool: toolBreakdown(arr) });
+    out.push({
+      project,
+      ...summarize(arr),
+      byTool: toolBreakdown(arr),
+      nByTool: toolSessionCount(arr),
+    });
   }
   return out.sort((a, b) => b.tokensTotal - a.tokensTotal);
 }
 
 export function perMonth(records) {
-  const m = groupBy(records, r => r.month);
+  const m = groupBy(records, (r) => r.month);
   const out = [];
   for (const [month, arr] of m) {
     out.push({ month, ...summarize(arr), byTool: toolBreakdown(arr) });
@@ -69,7 +98,7 @@ export function perMonth(records) {
 }
 
 export function perWeek(records) {
-  const m = groupBy(records, r => r.week);
+  const m = groupBy(records, (r) => r.week);
   const out = [];
   for (const [week, arr] of m) {
     out.push({ week, ...summarize(arr), byTool: toolBreakdown(arr) });
@@ -78,7 +107,7 @@ export function perWeek(records) {
 }
 
 export function perTool(records) {
-  const m = groupBy(records, r => r.tool);
+  const m = groupBy(records, (r) => r.tool);
   const out = [];
   for (const [tool, arr] of m) {
     out.push({ tool, ...summarize(arr) });
@@ -90,10 +119,10 @@ export function perToolPerMonth(records) {
   // Cross-tab: one row per (tool, month). Lets you see how a single tool's
   // usage is distributed across months — and avoids the hardcoded OC/CX/MM
   // column problem in the per-month table.
-  const m = groupBy(records, r => `${r.tool}\u0001${r.month}`);
+  const m = groupBy(records, (r) => `${r.tool}\u0001${r.month}`);
   const out = [];
   for (const [k, arr] of m) {
-    const [tool, month] = k.split('\u0001');
+    const [tool, month] = k.split("\u0001");
     out.push({ tool, month, ...summarize(arr) });
   }
   return out.sort((a, b) => b.tokensTotal - a.tokensTotal);
@@ -104,9 +133,7 @@ export function overall(records) {
 }
 
 export function topSessions(records, n = 5) {
-  return [...records]
-    .sort((a, b) => b.tokensTotal - a.tokensTotal)
-    .slice(0, n);
+  return [...records].sort((a, b) => b.tokensTotal - a.tokensTotal).slice(0, n);
 }
 
 export function tokenBreakdown(s) {

package/src/live.js

@@ -0,0 +1,132 @@
+import { openSync, closeSync, fstatSync, readSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const FIELDS = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'];
+const count = value => Number.isFinite(Number(value)) ? Math.max(0, Number(value)) : 0;
+
+export class LiveUsageTailer {
+  constructor(detections) {
+    this.roots = [];
+    for (const d of detections) {
+      if (!d.path || !['claude', 'codex'].includes(d.key) || d.status === 'absent') continue;
+      if (d.key === 'codex' && basename(d.path) === 'archived_sessions') continue;
+      this.roots.push({ path: d.path, tool: d.key });
+    }
+    this.directories = new Map();
+    this.files = new Map();
+    this.events = [];
+    this.started = false;
+    this.lastFull = 0;
+  }
+
+  tick(now = Date.now()) {
+    const full = !this.started || now - this.lastFull >= 60000;
+    if (full) this.lastFull = now;
+    const discovered = new Set();
+    const walk = (dir, tool) => {
+      let st;
+      try { st = statSync(dir); } catch { return; }
+      if (!st.isDirectory()) return;
+      const key = `${tool}:${dir}`;
+      let cached = this.directories.get(key);
+      if (!cached || cached.mtime !== st.mtimeMs || full) {
+        let entries;
+        try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+        cached = { mtime: st.mtimeMs, dirs: [], files: [] };
+        for (const entry of entries) {
+          if (entry.isDirectory() && !(tool === 'claude' && entry.name === 'subagents') && !(tool === 'codex' && entry.name === 'archived_sessions')) cached.dirs.push(join(dir, entry.name));
+          else if (entry.isFile() && entry.name.endsWith('.jsonl') && (tool !== 'codex' || entry.name.startsWith('rollout-'))) cached.files.push(join(dir, entry.name));
+        }
+        this.directories.set(key, cached);
+      }
+      for (const child of cached.dirs) walk(child, tool);
+      for (const file of cached.files) {
+        const id = `${tool}:${file}`;
+        discovered.add(id);
+        if (!this.files.has(id)) this.files.set(id, { path: file, tool, offset: null, partial: Buffer.alloc(0), seen: new Map(), total: null, mtime: 0 });
+      }
+    };
+    for (const root of this.roots) walk(root.path, root.tool);
+    for (const [key, file] of this.files) {
+      if (!discovered.has(key)) { this.files.delete(key); continue; }
+      if (file.offset !== null && !full && now - file.mtime > 600000) continue;
+      this.readFile(file, now);
+    }
+    this.started = true;
+    this.events = this.events.filter(e => e.ts > now - 3600000);
+    return this.rate(now, 600);
+  }
+
+  readFile(file, now) {
+    let fd;
+    try {
+      fd = openSync(file.path, 'r');
+      const st = fstatSync(fd);
+      const identity = `${st.dev}:${st.ino}`;
+      let changedBoundary = false;
+      if (file.offset !== null && file.offset > 0 && file.boundary && st.size >= file.offset) {
+        const sample = Buffer.alloc(file.boundary.length);
+        const size = readSync(fd, sample, 0, sample.length, file.offset - sample.length);
+        changedBoundary = size !== sample.length || !sample.equals(file.boundary);
+      }
+      if (file.offset === null) {
+        file.offset = this.started ? 0 : st.size;
+        file.identity = identity;
+      } else if (file.identity !== identity || st.size < file.offset || changedBoundary) {
+        file.offset = 0;
+        file.identity = identity;
+        file.partial = Buffer.alloc(0);
+        file.seen.clear();
+        file.total = null;
+      }
+      file.mtime = st.mtimeMs;
+      while (file.offset < st.size) {
+        const buffer = Buffer.allocUnsafe(Math.min(65536, st.size - file.offset));
+        const size = readSync(fd, buffer, 0, buffer.length, file.offset);
+        if (!size) break;
+        file.offset += size;
+        const data = Buffer.concat([file.partial, buffer.subarray(0, size)]);
+        let from = 0, end;
+        while ((end = data.indexOf(10, from)) !== -1) {
+          this.consume(file, data.subarray(from, end).toString('utf8'), now);
+          from = end + 1;
+        }
+        file.partial = data.subarray(from);
+      }
+      const sample = Buffer.alloc(Math.min(64, file.offset));
+      if (sample.length) {
+        const size = readSync(fd, sample, 0, sample.length, file.offset - sample.length);
+        file.boundary = sample.subarray(0, size);
+      } else file.boundary = sample;
+    } catch {} finally { if (fd !== undefined) closeSync(fd); }
+  }
+
+  consume(file, line, now) {
+    let event;
+    try { event = JSON.parse(line); } catch { return; }
+    let tokens = 0;
+    if (file.tool === 'claude' && event.type === 'assistant' && event.message?.usage) {
+      const usage = event.message.usage;
+      const id = event.message.id ? JSON.stringify([event.message.id, event.requestId || null]) : null;
+      const previous = id ? file.seen.get(id) || {} : {};
+      const next = {};
+      for (const field of FIELDS) {
+        next[field] = Math.max(count(previous[field]), count(usage[field]));
+        tokens += next[field] - count(previous[field]);
+      }
+      if (id) file.seen.set(id, next);
+    } else if (file.tool === 'codex' && event.type === 'event_msg' && event.payload?.type === 'token_count') {
+      const info = event.payload.info || {};
+      const total = info.total_token_usage;
+      const key = total ? JSON.stringify(total) : null;
+      if (key && key === file.total) return;
+      if (key) file.total = key;
+      if (info.last_token_usage) tokens = count(info.last_token_usage.input_tokens) + count(info.last_token_usage.output_tokens);
+    }
+    if (tokens > 0) this.events.push({ ts: now, tokens });
+  }
+
+  rate(now = Date.now(), seconds = 600) {
+    return this.events.filter(e => e.ts > now - seconds * 1000 && e.ts <= now).reduce((sum, e) => sum + e.tokens, 0) * 60 / seconds;
+  }
+}