ai-usage-analyzer 0.3.2 → 0.4.0

package/bin/ai-usage.js

@@ -2,30 +2,39 @@
 // 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 { runInteractive } from "../src/tui.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 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;
@@ -39,11 +48,12 @@ 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
+  --top N                  Show top N heaviest sessions (default: 5)
+  --year YYYY              Filter records to a single year (e.g. --year 2026)
 
 Examples:
   ai-usage                       # default TUI
@@ -70,7 +80,7 @@ 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);
 }
 
@@ -81,9 +91,12 @@ async function main() {
 
   // 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);
@@ -105,14 +118,24 @@ 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);
     return;
   }
 
-  // TUI render
+  // 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,
@@ -135,10 +158,10 @@ async function main() {
   }
   sections.push(renderNotes(detections, errors));
 
-  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,6 +1,6 @@
 {
   "name": "ai-usage-analyzer",
-  "version": "0.3.2",
+  "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.",
   "type": "module",
   "packageManager": "pnpm@10.33.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) {
@@ -27,14 +36,14 @@ export function groupBy(records, keyFn) {
 function summarize(records) {
   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"),
+    avg: avg(records, "tokensTotal"),
   };
 }
 
@@ -46,21 +55,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 +91,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 +100,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 +112,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 +126,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) {