ai-usage-analyzer 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# 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.
+
+```
+╭──────────────────────────────────────────────────────╮
+│               ◆  AI TOKEN ANALYZER  ◆                │
+│                                                      │
+│  411 sessions  •  1.56B total tokens  •  $29.40 USD  │
+│            range: 2026-04-01  →  2026-06-27          │
+╰──────────────────────────────────────────────────────╯
+```
+
+## Install
+
+Requires **Node.js ≥ 22.5** (for built-in `node:sqlite`).
+
+Pick whichever fits your workflow:
+
+### Option 1: `npx` from GitHub (zero install, fastest to try)
+
+```bash
+npx -y github:adetxt/ai-usage-analyzer
+# or with a specific ref
+npx -y github:adetxt/ai-usage-analyzer#v0.1.0
+```
+
+No clone, no `node_modules`, no global install. npx downloads the repo
+on first run and caches it. Subsequent runs are instant.
+
+### Option 2: Clone + install (best for development / contribution)
+
+```bash
+git clone https://github.com/adetxt/ai-usage-analyzer.git
+cd ai-usage-analyzer
+pnpm install
+pnpm link --global   # exposes the `ai-usage` command globally
+```
+
+> Uses `pnpm` (declared in the `packageManager` field). `pnpm-lock.yaml`
+> is committed as the source of truth for reproducible installs.
+
+### Option 3: Install globally from GitHub (no clone)
+
+```bash
+pnpm add -g git+https://github.com/adetxt/ai-usage-analyzer.git
+# or with npm
+npm install -g git+https://github.com/adetxt/ai-usage-analyzer.git
+# then
+ai-usage
+```
+
+### Option 4: From npm registry (when published)
+
+```bash
+npx -y ai-usage-analyzer
+# or
+pnpm add -g ai-usage-analyzer
+```
+
+To publish your own copy: `npm login && npm publish --access public`
+(requires the `ai-usage-analyzer` name to be available on npmjs.com,
+or use a scoped name like `@yourname/ai-usage-analyzer` and update
+the `name` field in `package.json` first).
+
+### Verify install
+
+```bash
+ai-usage --help
+# or via npx
+npx -y github:adetxt/ai-usage-analyzer --help
+```
+
+## Usage
+
+```bash
+ai-usage                # default TUI
+ai-usage --top 10       # show top 10 heaviest sessions
+ai-usage --json         # machine-readable JSON output
+ai-usage --help
+```
+
+### Environment overrides
+
+If a tool's data lives outside the default location, override its base path:
+
+```bash
+export CLAUDE_HOME=/custom/path/to/.claude
+export CODEX_HOME=/custom/path/to/.codex
+export OPENCODE_HOME=/custom/path/to/.local/share/opencode
+export MIMOCODE_HOME=/custom/path/to/.local/share/mimocode
+export COPILOT_HOME=/custom/path/to/.copilot
+export ANTIGRAVITY_HOME=/custom/path/to/Antigravity
+export GEMINI_HOME=/custom/path/to/.gemini
+```
+
+Or pass all at once via JSON:
+
+```bash
+export AI_USAGE_PATHS_JSON='{"codex":"/data/codex","opencode":"/data/oc.db"}'
+```
+
+## Supported tools
+
+| Tool | Path | Token data | Source format |
+|---|---|---|---|
+| Claude Code    | `~/.claude/transcripts`             | presence only | `ses_*.jsonl` |
+| Codex          | `~/.codex/sessions/YYYY/MM/DD/`    | **yes** | `rollout-*.jsonl` `token_count` events |
+| OpenCode       | `~/.local/share/opencode/opencode.db` | **yes** (+cost) | SQLite |
+| MimoCode       | `~/.local/share/mimocode/mimocode.db` | **yes** (+cost, when present) | SQLite |
+| GitHub Copilot | `~/.copilot/session-state/`        | presence only | `events.jsonl` |
+| Antigravity    | `~/Library/Application Support/Antigravity` | presence only | dir scan |
+| Gemini CLI     | `~/.gemini/antigravity/conversations` | presence only | `*.pb` protobuf |
+
+## Token breakdown
+
+For tools that record token data, the analyzer shows the full breakdown:
+
+- **Input** — prompt tokens sent to the model
+- **Output** — completion tokens generated by the model
+- **Cache Read** — prompt tokens served from the provider's cache (cheap)
+- **Cache Write** — prompt tokens cached for future use (OpenCode only)
+- **Reasoning** — extended thinking / chain-of-thought tokens
+
+The TUI is adaptive: at terminal widths below 110 columns it drops
+non-essential columns; at 110+ it shows the full breakdown with project
+paths, per-tool token columns, and longer distribution bars.
+
+## Architecture
+
+```
+src/
+├── detectors.js    auto-path discovery (env → well-known locations)
+├── loaders.js      SQLite + JSONL parsers → unified session record
+├── aggregate.js    per-project / per-week / per-month grouping
+├── render.js       TUI (chalk + cli-table3 + boxen + gradient-string)
+bin/
+└── ai-usage.js     entry point
+```
+
+The loader produces a unified record shape:
+
+```ts
+{
+  tool, sessionId, project, title, week, month, ts,
+  tokensInput, tokensOutput, tokensCacheRead, tokensCacheWrite,
+  tokensReasoning, tokensTotal, cost, model
+}
+```
+
+The aggregator then groups by project / week / month, and the renderer
+turns each grouping into a colored table with a distribution bar.
+
+## Output modes
+
+### TUI (default)
+
+Color-coded, boxed tables with bar charts. Adapts to terminal width.
+
+### JSON (`--json`)
+
+Single JSON object with detection results, summary, raw sessions, and errors.
+Suitable for piping into `jq` or feeding a dashboard.
+
+```bash
+ai-usage --json | jq '.summary'
+# {
+#   "n": 411,
+#   "tokensTotal": 1558000000,
+#   "tokensInput": 420900000,
+#   "tokensOutput": 4450000,
+#   "tokensCacheRead": 1130000000,
+#   "tokensCacheWrite": 49000,
+#   "tokensReasoning": 2210000,
+#   "cost": 29.4,
+#   "avg": 3790000
+# }
+```
+
+## License
+
+MIT

package/bin/ai-usage.js

@@ -0,0 +1,100 @@
+#!/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 { detectAll } from '../src/detectors.js';
+import { loadAll, dateRange } from '../src/loaders.js';
+import { overall } from '../src/aggregate.js';
+import {
+  renderHeader, renderDetections, renderOverview,
+  renderPerProject, renderPerMonth, renderPerWeek,
+  renderTopSessions, renderNotes,
+} from '../src/render.js';
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter(a => a.startsWith('--')));
+const showHelp = flags.has('--help') || flags.has('-h');
+const jsonOut = flags.has('--json');
+const topN = (() => {
+  const i = args.indexOf('--top');
+  return i >= 0 ? parseInt(args[i + 1], 10) || 5 : 5;
+})();
+
+if (showHelp) {
+  console.log(`
+ai-usage-analyzer — local AI coding agent token consumption TUI
+
+Usage:
+  ai-usage [options]
+
+Options:
+  --top N            Show top N heaviest sessions (default: 5)
+  --json             Output machine-readable JSON instead of TUI
+  -h, --help         Show this help
+
+Environment overrides (per-tool data path):
+  CLAUDE_HOME, CODEX_HOME, OPENCODE_HOME, MIMOCODE_HOME,
+  COPILOT_HOME, ANTIGRAVITY_HOME, GEMINI_HOME,
+  AI_USAGE_PATHS_JSON='{"codex":"/custom/path",...}'
+
+Supported tools:
+  • Claude Code    — ~/.claude/transcripts  (presence only)
+  • 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)
+`);
+  process.exit(0);
+}
+
+async function main() {
+  const t0 = Date.now();
+  const detections = detectAll();
+  const { records, errors } = await loadAll(detections);
+  const range = dateRange(records);
+  const tot = overall(records);
+
+  if (jsonOut) {
+    const out = {
+      detections,
+      summary: tot,
+      dateRange: range,
+      sessions: records,
+      errors,
+      generatedAt: new Date().toISOString(),
+      durationMs: Date.now() - t0,
+    };
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  // TUI render
+  const sections = [
+    renderHeader({
+      totalSessions: records.length,
+      totalTokens: tot.tokensTotal,
+      totalCost: tot.cost,
+      dateRange: range,
+    }),
+    renderDetections(detections),
+  ];
+  if (records.length > 0) {
+    sections.push(
+      renderOverview(records, detections),
+      renderPerProject(records),
+      renderPerMonth(records),
+      renderPerWeek(records),
+      renderTopSessions(records, topN),
+    );
+  }
+  sections.push(renderNotes(detections, errors));
+
+  console.log(sections.join('\n\n'));
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ai-usage-analyzer",
+  "version": "0.1.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",
+  "bin": {
+    "ai-usage": "bin/ai-usage.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/ai-usage.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=22.5.0",
+    "pnpm": ">=10.0.0"
+  },
+  "keywords": [
+    "ai",
+    "tokens",
+    "claude-code",
+    "codex",
+    "opencode",
+    "mimocode",
+    "copilot",
+    "antigravity",
+    "gemini",
+    "tui",
+    "cli"
+  ],
+  "author": "ade",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adetxt/ai-usage-analyzer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adetxt/ai-usage-analyzer/issues"
+  },
+  "homepage": "https://github.com/adetxt/ai-usage-analyzer#readme",
+  "dependencies": {
+    "boxen": "^7.1.1",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "gradient-string": "^2.0.2"
+  }
+}

package/src/aggregate.js

@@ -0,0 +1,117 @@
+// Group session records by various dimensions and compute stats.
+
+const MONTH_NAMES = {
+  '01': 'Jan', '02': 'Feb', '03': 'Mar', '04': 'Apr',
+  '05': 'Mei', '06': 'Jun', '07': 'Jul', '08': 'Agu',
+  '09': 'Sep', '10': 'Okt', '11': 'Nov', '12': 'Des',
+};
+
+function sum(arr, key) {
+  return arr.reduce((a, b) => a + (b[key] || 0), 0);
+}
+
+function avg(arr, key) {
+  return arr.length ? sum(arr, key) / arr.length : 0;
+}
+
+export function groupBy(records, keyFn) {
+  const out = new Map();
+  for (const r of records) {
+    const k = keyFn(r);
+    if (!out.has(k)) out.set(k, []);
+    out.get(k).push(r);
+  }
+  return out;
+}
+
+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'),
+  };
+}
+
+export function perProject(records) {
+  const m = groupBy(records, r => `${r.tool}\u0001${r.project}`);
+  const out = [];
+  for (const [k, arr] of m) {
+    const [tool, project] = k.split('\u0001');
+    const s = summarize(arr);
+    out.push({ tool, project, ...s });
+  }
+  return out.sort((a, b) => b.tokensTotal - a.tokensTotal);
+}
+
+export function perMonth(records) {
+  const m = groupBy(records, r => r.month);
+  const out = [];
+  for (const [month, arr] of m) {
+    const byTool = {};
+    for (const r of arr) {
+      byTool[r.tool] = (byTool[r.tool] || 0) + r.tokensTotal;
+    }
+    out.push({ month, ...summarize(arr), byTool });
+  }
+  return out.sort((a, b) => a.month.localeCompare(b.month));
+}
+
+export function perWeek(records) {
+  const m = groupBy(records, r => r.week);
+  const out = [];
+  for (const [week, arr] of m) {
+    const byTool = {};
+    for (const r of arr) {
+      byTool[r.tool] = (byTool[r.tool] || 0) + r.tokensTotal;
+    }
+    out.push({ week, ...summarize(arr), byTool });
+  }
+  return out.sort((a, b) => a.week.localeCompare(b.week));
+}
+
+export function perTool(records) {
+  const m = groupBy(records, r => r.tool);
+  const out = [];
+  for (const [tool, arr] of m) {
+    out.push({ tool, ...summarize(arr) });
+  }
+  return out.sort((a, b) => b.tokensTotal - a.tokensTotal);
+}
+
+export function overall(records) {
+  return summarize(records);
+}
+
+export function topSessions(records, n = 5) {
+  return [...records]
+    .sort((a, b) => b.tokensTotal - a.tokensTotal)
+    .slice(0, n);
+}
+
+export function tokenBreakdown(s) {
+  // Returns { input, output, cacheRead, cacheWrite, reasoning, total, ratios }
+  const total = s.tokensTotal || 1;
+  return {
+    input: s.tokensInput,
+    output: s.tokensOutput,
+    cacheRead: s.tokensCacheRead,
+    cacheWrite: s.tokensCacheWrite,
+    reasoning: s.tokensReasoning,
+    total: s.tokensTotal,
+    ratios: {
+      input: s.tokensInput / total,
+      output: s.tokensOutput / total,
+      cacheRead: s.tokensCacheRead / total,
+      cacheWrite: s.tokensCacheWrite / total,
+      reasoning: s.tokensReasoning / total,
+    },
+  };
+}
+
+export { MONTH_NAMES };