ai-usage-analyzer 0.4.0 → 0.5.1

package/README.md

@@ -1,17 +1,11 @@
 # ai-usage-analyzer
 
-TUI analyzer for local AI coding agent token consumption. Auto-detects
-**Claude Code**, **Codex**, **OpenCode**, **MimoCode**, **GitHub Copilot**,
-**Antigravity**, and **Gemini CLI** data directories — no hardcoded paths.
+A local web dashboard for AI coding agent token consumption. Auto-detects
+**Claude Code**, **Codex**, **OpenCode**,
+**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,28 +25,27 @@ 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 |
 | Antigravity    | `~/Library/Application Support/Antigravity` | presence only |
 | Gemini CLI     | `~/.gemini/antigravity/conversations` | presence only |
 
 ## Path overrides
 
 Override any tool's base path with an env var (`CLAUDE_HOME`, `CODEX_HOME`,
-`OPENCODE_HOME`, `MIMOCODE_HOME`, `COPILOT_HOME`, `ANTIGRAVITY_HOME`,
+`OPENCODE_HOME`, `ANTIGRAVITY_HOME`,
 `GEMINI_HOME`), or pass all at once via JSON:
 
 ```bash
@@ -65,14 +58,40 @@ 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.
 
+Average daily tokens divides total tokens by calendar days, including days
+without usage. The dashboard uses the selected date range in your local time.
+All time uses the first through last recorded day. Terminal, Markdown, and JSON
+reports use the first through last recorded day in UTC; JSON exposes the value
+as `summary.avgDailyTokens`.
+
+## 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 costs are read from
+its local database. 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

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 // AI Usage Analyzer - TUI for local AI coding agent token consumption
-// Auto-detects: Claude Code, Codex, OpenCode, MimoCode, Copilot, Antigravity, Gemini
 
 import { overall } from "../src/aggregate.js";
 import { detectAll } from "../src/detectors.js";
@@ -18,7 +17,8 @@ import {
     renderPerWeek,
     renderTopSessions,
 } from "../src/render.js";
-import { runInteractive } from "../src/tui.js";
+import { startDashboard } from "../src/server.js";
+import { collectQuotas, renderQuota } from "../src/quota.js";
 
 const args = process.argv.slice(2);
 const hasFlag = (name) =>
@@ -26,6 +26,7 @@ const hasFlag = (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");
@@ -42,7 +43,7 @@ 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]
@@ -52,27 +53,26 @@ Options:
   --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
-  --top N                  Show top N heaviest sessions (default: 5)
-  --year YYYY              Filter records to a single year (e.g. --year 2026)
+  --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,
-  COPILOT_HOME, ANTIGRAVITY_HOME, GEMINI_HOME,
+  CLAUDE_HOME, CODEX_HOME, OPENCODE_HOME,
+  ANTIGRAVITY_HOME, GEMINI_HOME,
   AI_USAGE_PATHS_JSON='{"codex":"/custom/path",...}'
 
 Supported tools:
   • Claude Code    — ~/.claude/projects  (tokens from per-message usage)
   • Codex          — ~/.codex/sessions      (tokens from token_count events)
   • OpenCode       — ~/.local/share/opencode/opencode.db  (tokens + cost)
-  • MimoCode       — ~/.local/share/mimocode/mimocode.db  (tokens + cost)
-  • GitHub Copilot — ~/.copilot/session-state  (presence only)
   • Antigravity    — ~/Library/Application Support/Antigravity  (presence only)
   • Gemini CLI     — ~/.gemini/antigravity/conversations  (presence only)
 `);
@@ -85,6 +85,10 @@ if (jsonOut && mdOut) {
 }
 
 async function main() {
+  if (!jsonOut && !mdOut && !staticOut) {
+    await startDashboard();
+    return;
+  }
   const t0 = Date.now();
   const detections = detectAll();
   const { records: allRecords, errors } = await loadAll(detections);
@@ -101,9 +105,13 @@ async function main() {
   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,
@@ -125,22 +133,18 @@ async function main() {
       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;
   }
 
-  // Interactive TUI (default when stdout is a TTY and --static not given)
-  if (!staticOut) {
-    const handled = await runInteractive({ records, detections, errors, topN });
-    if (handled) return;
-  }
-
   // 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),
@@ -157,6 +161,7 @@ async function main() {
     );
   }
   sections.push(renderNotes(detections, errors));
+  if (quotaPromise) sections.push(renderQuota(await quotaPromise));
 
   console.log(sections.join("\n\n"));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-usage-analyzer",
-  "version": "0.4.0",
-  "description": "TUI analyzer for local AI coding agent token usage. Auto-detects Claude Code, Codex, OpenCode, MimoCode, Copilot, Antigravity, and Gemini.",
+  "version": "0.5.1",
+  "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",
@@ -27,12 +28,10 @@
     "claude-code",
     "codex",
     "opencode",
-    "mimocode",
-    "copilot",
     "antigravity",
     "gemini",
-    "tui",
-    "cli"
+    "cli",
+    "dashboard"
   ],
   "author": "ade",
   "license": "MIT",
@@ -48,6 +47,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

@@ -34,6 +34,11 @@ 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"),
@@ -43,6 +48,8 @@ function summarize(records) {
     tokensCacheWrite: sum(records, "tokensCacheWrite"),
     tokensReasoning: sum(records, "tokensReasoning"),
     cost: sum(records, "cost"),
+    costStatus,
+    unknownModels,
     avg: avg(records, "tokensTotal"),
   };
 }
@@ -121,8 +128,23 @@ export function perToolPerMonth(records) {
   return out.sort((a, b) => b.tokensTotal - a.tokensTotal);
 }
 
-export function overall(records) {
-  return summarize(records);
+export function overall(records, dayCount) {
+  const totals = summarize(records);
+  if (dayCount === undefined) {
+    let first = Infinity;
+    let last = -Infinity;
+    for (const record of records) {
+      if (!Number.isFinite(record.ts) || !Number.isFinite(new Date(record.ts).getTime())) continue;
+      const day = Math.floor(record.ts / 86400000);
+      first = Math.min(first, day);
+      last = Math.max(last, day);
+    }
+    dayCount = last - first + 1;
+  }
+  return {
+    ...totals,
+    avgDailyTokens: Number.isFinite(dayCount) && dayCount > 0 ? totals.tokensTotal / dayCount : 0,
+  };
 }
 
 export function topSessions(records, n = 5) {

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;
+  }
+}