ai-usage-analyzer 0.1.0 → 0.2.1

package/README.md

@@ -17,166 +17,62 @@ TUI analyzer for local AI coding agent token consumption. Auto-detects
 
 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
+# Try it (no install)
 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
+# Or install globally
 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
+ai-usage                  # default TUI
+ai-usage --top 10         # show top 10 heaviest sessions
+ai-usage --json           # machine-readable JSON
+ai-usage --md > report.md # save as markdown
 ```
 
-### Environment overrides
+## Supported tools
 
-If a tool's data lives outside the default location, override its base path:
+| Tool | Default path | Tokens |
+|---|---|---|
+| Claude Code    | `~/.claude/projects`                | presence only |
+| Codex          | `~/.codex/sessions/YYYY/MM/DD/`    | yes |
+| 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 |
 
-```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
-```
+## Path overrides
 
-Or pass all at once via JSON:
+Override any tool's base path with an env var (`CLAUDE_HOME`, `CODEX_HOME`,
+`OPENCODE_HOME`, `MIMOCODE_HOME`, `COPILOT_HOME`, `ANTIGRAVITY_HOME`,
+`GEMINI_HOME`), 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.
+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.
 
-## Architecture
+## How it works
 
 ```
 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)
+├── 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  •  markdown.js  →  Markdown report
 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
-# }
+└── ai-usage.js    entry point
 ```
 
 ## License

package/bin/ai-usage.js

@@ -10,14 +10,18 @@ import {
   renderPerProject, renderPerMonth, renderPerWeek,
   renderTopSessions, renderNotes,
 } from '../src/render.js';
+import { renderMarkdown } from '../src/markdown.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 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 topN = (() => {
   const i = args.indexOf('--top');
-  return i >= 0 ? parseInt(args[i + 1], 10) || 5 : 5;
+  if (i < 0) return 5;
+  const v = parseInt(args[i + 1], 10);
+  return Number.isFinite(v) && v > 0 ? v : 5;
 })();
 
 if (showHelp) {
@@ -28,9 +32,16 @@ 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
+  --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)
+
+Examples:
+  ai-usage                       # default TUI
+  ai-usage --json | jq .summary  # pipe to jq
+  ai-usage --md > report.md      # save as markdown
+  ai-usage --top 20              # show top 20 sessions
 
 Environment overrides (per-tool data path):
   CLAUDE_HOME, CODEX_HOME, OPENCODE_HOME, MIMOCODE_HOME,
@@ -38,7 +49,7 @@ Environment overrides (per-tool data path):
   AI_USAGE_PATHS_JSON='{"codex":"/custom/path",...}'
 
 Supported tools:
-  • Claude Code    — ~/.claude/transcripts  (presence only)
+  • Claude Code    — ~/.claude/projects  (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)
@@ -49,6 +60,11 @@ Supported tools:
   process.exit(0);
 }
 
+if (jsonOut && mdOut) {
+  console.error('Error: --json and --markdown are mutually exclusive.');
+  process.exit(2);
+}
+
 async function main() {
   const t0 = Date.now();
   const detections = detectAll();
@@ -70,6 +86,15 @@ async function main() {
     return;
   }
 
+  if (mdOut) {
+    const out = renderMarkdown({
+      records, detections, errors,
+      dateRange: range, topN, generatedAt: new Date().toISOString(),
+    });
+    process.stdout.write(out);
+    return;
+  }
+
   // TUI render
   const sections = [
     renderHeader({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-usage-analyzer",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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/detectors.js

@@ -56,25 +56,28 @@ const DETECTORS = [
     name: 'Claude Code',
     kind: 'jsonl',
     envVar: 'CLAUDE_HOME',
-    candidatePaths: () => {
-      const base = env.CLAUDE_HOME || join(HOME, '.claude');
-      return [
-        join(base, 'transcripts'),
-        join(base, 'projects'),
-      ];
-    },
+    candidatePaths: () => [
+      env.CLAUDE_HOME
+        ? join(env.CLAUDE_HOME, 'projects')
+        : join(HOME, '.claude', 'projects'),
+    ],
     count: (p) => {
       if (!p) return 0;
       let n = 0;
-      try {
-        for (const f of readdirSync(p)) {
-          if (f.startsWith('ses_') && f.endsWith('.jsonl')) n++;
-        }
-      } catch {}
+      function walk(dir) {
+        try {
+          for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) walk(full);
+            else if (e.isFile() && e.name.endsWith('.jsonl')) n++;
+          }
+        } catch {}
+      }
+      walk(p);
       return n;
     },
     hasTokens: false,  // transcripts only contain text, no token counts
-    description: '~/.claude/transcripts/*.jsonl  (no token data stored locally)',
+    description: '~/.claude/projects/*/<UUID>.jsonl  (no token data stored locally)',
   },
 
   // -----------------------------------------------------------------------

package/src/markdown.js

@@ -0,0 +1,257 @@
+// Markdown report renderer for AI token usage analysis.
+// Produces a self-contained GitHub-flavored markdown document that
+// copies cleanly into issues, PRs, Notion, etc.
+
+import {
+  perProject, perMonth, perWeek, perTool, overall, topSessions, tokenBreakdown,
+  MONTH_NAMES,
+} from './aggregate.js';
+
+// ---------------------------------------------------------------------------
+// Number formatting helpers (re-implemented locally to avoid TUI deps)
+// ---------------------------------------------------------------------------
+
+export function fmtInt(n) {
+  return Number(n || 0).toLocaleString('en-US');
+}
+
+export function fmtCompact(n) {
+  const a = Math.abs(n);
+  if (a >= 1e9) return (n / 1e9).toFixed(2) + 'B';
+  if (a >= 1e6) return (n / 1e6).toFixed(2) + 'M';
+  if (a >= 1e3) return (n / 1e3).toFixed(1) + 'K';
+  return String(n || 0);
+}
+
+function fmtCost(n) {
+  if (!n) return '—';
+  return '$' + Number(n).toFixed(2);
+}
+
+function compactHome(p) {
+  if (!p) return '—';
+  const home = process.env.HOME || '';
+  return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+
+function bar(value, max, width) {
+  if (!max || max <= 0) return '░'.repeat(width);
+  const pct = Math.max(0, Math.min(1, value / max));
+  const filled = Math.round(pct * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function pct(x) { return (x * 100).toFixed(1) + '%'; }
+
+function mdEscape(s) {
+  if (s == null) return '';
+  return String(s).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+function shortModel(m) {
+  if (!m) return '—';
+  if (typeof m === 'string' && m.trim().startsWith('{')) {
+    try {
+      const d = JSON.parse(m);
+      const id = d.id || d.model || m;
+      const prov = d.providerId || d.provider;
+      return id + (prov ? ` (${prov})` : '');
+    } catch { return m.slice(0, 30); }
+  }
+  return m;
+}
+
+function today() {
+  return new Date().toISOString().split('T')[0];
+}
+
+// ---------------------------------------------------------------------------
+// Public: renderMarkdown
+// ---------------------------------------------------------------------------
+
+export function renderMarkdown({
+  records = [], detections = [], errors = [],
+  dateRange = [null, null], topN = 5, generatedAt = null,
+}) {
+  const out = [];
+  const tot = overall(records);
+  const breakdown = tokenBreakdown(tot);
+  const tools = perTool(records);
+  const hasData = records.length > 0;
+
+  // Header --------------------------------------------------------------
+  out.push(`# AI Token Usage Report`);
+  out.push(``);
+  out.push(`> Generated by [\`ai-usage-analyzer\`](https://github.com/adetxt/ai-usage-analyzer) on ${generatedAt ? generatedAt.split('T')[0] : today()}`);
+  out.push(``);
+
+  if (hasData) {
+    out.push(`**Range**: ${dateRange[0] ?? '—'} → ${dateRange[1] ?? '—'}  `);
+    out.push(`**Sessions**: ${fmtInt(records.length)}  `);
+    out.push(`**Total tokens**: ${fmtCompact(tot.tokensTotal)}  `);
+    if (tot.cost > 0) {
+      out.push(`**Cost**: ${fmtCost(tot.cost)} (opencode only)  `);
+    }
+  } else {
+    out.push(`**No session data available** — only detection status below.`);
+  }
+  out.push(``);
+
+  // Detected tools ------------------------------------------------------
+  out.push(`## Detected AI Tools`);
+  out.push(``);
+  out.push(`| Tool | Status | Path | Count | Tokens |`);
+  out.push(`|---|---|---|---:|---|`);
+  for (const d of detections) {
+    const status = d.status === 'present' ? '✅ present' : '❌ absent';
+    const path = d.path ? '`' + mdEscape(compactHome(d.path)) + '`' : '—';
+    const count = d.count ? fmtInt(d.count) : '—';
+    const tok = d.hasTokens
+      ? (d.count ? '✅' : '—')
+      : 'n/a';
+    out.push(`| ${mdEscape(d.name)} | ${status} | ${path} | ${count} | ${tok} |`);
+  }
+  out.push(``);
+
+  if (!hasData) {
+    if (errors && errors.length > 0) {
+      out.push(`## Errors`);
+      out.push(``);
+      for (const e of errors) out.push(`- ${mdEscape(e)}`);
+      out.push(``);
+    }
+    return out.join('\n');
+  }
+
+  // Overview ------------------------------------------------------------
+  out.push(`## Overview`);
+  out.push(``);
+  out.push(`### Per-tool Summary`);
+  out.push(``);
+  out.push(`| Tool | Sessions | Total | Avg/sess | Cost |`);
+  out.push(`|---|---:|---:|---:|---:|`);
+  for (const t of tools) {
+    out.push(`| ${mdEscape(t.tool)} | ${fmtInt(t.n)} | ${fmtCompact(t.tokensTotal)} | ${fmtCompact(t.avg)} | ${fmtCost(t.cost)} |`);
+  }
+  out.push(`| **TOTAL** | **${fmtInt(records.length)}** | **${fmtCompact(tot.tokensTotal)}** | **${fmtCompact(tot.avg)}** | **${fmtCost(tot.cost)}** |`);
+  out.push(``);
+
+  out.push(`### Token Breakdown`);
+  out.push(``);
+  out.push(`| Type | Tokens | Share |`);
+  out.push(`|---|---:|---:|`);
+  out.push(`| Input | ${fmtCompact(breakdown.input)} | ${pct(breakdown.ratios.input)} |`);
+  out.push(`| Output | ${fmtCompact(breakdown.output)} | ${pct(breakdown.ratios.output)} |`);
+  out.push(`| Cache Read | ${fmtCompact(breakdown.cacheRead)} | ${pct(breakdown.ratios.cacheRead)} |`);
+  out.push(`| Cache Write | ${fmtCompact(breakdown.cacheWrite)} | ${pct(breakdown.ratios.cacheWrite)} |`);
+  out.push(`| Reasoning | ${fmtCompact(breakdown.reasoning)} | ${pct(breakdown.ratios.reasoning)} |`);
+  out.push(`| **Total** | **${fmtCompact(breakdown.total)}** | **100.0%** |`);
+  out.push(``);
+
+  // Per Project ---------------------------------------------------------
+  const projects = perProject(records);
+  if (projects.length > 0) {
+    const max = projects[0].tokensTotal;
+    out.push(`## Per Project`);
+    out.push(``);
+    out.push(`| Tool | Project | Sessions | Input | Output | Cache | Total | Dist |`);
+    out.push(`|---|---|---:|---:|---:|---:|---:|---|`);
+    for (const p of projects) {
+      const cache = p.tokensCacheRead + p.tokensCacheWrite;
+      const proj = compactHome(p.project);
+      out.push(`| ${mdEscape(p.tool)} | \`${mdEscape(proj)}\` | ${fmtInt(p.n)} | ${fmtCompact(p.tokensInput)} | ${fmtCompact(p.tokensOutput)} | ${fmtCompact(cache)} | ${fmtCompact(p.tokensTotal)} | ${bar(p.tokensTotal, max, 20)} |`);
+    }
+    out.push(``);
+  }
+
+  // Per Month -----------------------------------------------------------
+  const months = perMonth(records);
+  if (months.length > 0) {
+    const max = Math.max(...months.map(m => m.tokensTotal));
+    out.push(`## Per Month`);
+    out.push(``);
+    out.push(`| Month | Sessions | Input | Output | Total | OC | CX | MM | Dist |`);
+    out.push(`|---|---:|---:|---:|---:|---:|---:|---:|---|`);
+    for (const m of months) {
+      const yyyy = m.month.slice(0, 4);
+      const mm = m.month.slice(5, 7);
+      const label = `${MONTH_NAMES[mm] || mm} ${yyyy}`;
+      out.push(`| ${label} | ${fmtInt(m.n)} | ${fmtCompact(m.tokensInput)} | ${fmtCompact(m.tokensOutput)} | ${fmtCompact(m.tokensTotal)} | ${m.byTool.opencode ? fmtCompact(m.byTool.opencode) : '—'} | ${m.byTool.codex ? fmtCompact(m.byTool.codex) : '—'} | ${m.byTool.mimocode ? fmtCompact(m.byTool.mimocode) : '—'} | ${bar(m.tokensTotal, max, 20)} |`);
+    }
+    out.push(``);
+  }
+
+  // Per Week ------------------------------------------------------------
+  const weeks = perWeek(records);
+  if (weeks.length > 0) {
+    const max = Math.max(...weeks.map(w => w.tokensTotal));
+    out.push(`## Per Week`);
+    out.push(``);
+    out.push(`| Week | Sessions | Input | Output | Total | OC | CX | MM | Dist |`);
+    out.push(`|---|---:|---:|---:|---:|---:|---:|---:|---|`);
+    for (const w of weeks) {
+      out.push(`| ${w.week} | ${fmtInt(w.n)} | ${fmtCompact(w.tokensInput)} | ${fmtCompact(w.tokensOutput)} | ${fmtCompact(w.tokensTotal)} | ${w.byTool.opencode ? fmtCompact(w.byTool.opencode) : '—'} | ${w.byTool.codex ? fmtCompact(w.byTool.codex) : '—'} | ${w.byTool.mimocode ? fmtCompact(w.byTool.mimocode) : '—'} | ${bar(w.tokensTotal, max, 18)} |`);
+    }
+    out.push(``);
+  }
+
+  // Top N ---------------------------------------------------------------
+  const top = topSessions(records, topN);
+  if (top.length > 0) {
+    out.push(`## Top ${top.length} Heaviest Sessions`);
+    out.push(``);
+    out.push(`| # | Total | Input | Output | Cost | Model | Project | Title |`);
+    out.push(`|---:|---:|---:|---:|---:|---|---|---|`);
+    top.forEach((r, i) => {
+      const proj = compactHome(r.project);
+      out.push(`| ${i + 1} | ${fmtCompact(r.tokensTotal)} | ${fmtCompact(r.tokensInput)} | ${fmtCompact(r.tokensOutput)} | ${r.cost ? '$' + r.cost.toFixed(4) : '—'} | ${mdEscape(shortModel(r.model))} | \`${mdEscape(proj)}\` | ${mdEscape(r.title || '—')} |`);
+    });
+    out.push(``);
+  }
+
+  // Notes ---------------------------------------------------------------
+  out.push(`## Notes`);
+  out.push(``);
+  out.push(`### Token Definitions`);
+  out.push(``);
+  out.push(`- **Input** — prompt tokens sent to the model`);
+  out.push(`- **Output** — completion tokens generated by the model`);
+  out.push(`- **Cache Read** — prompt tokens served from the provider's cache (cheap)`);
+  out.push(`- **Cache Write** — prompt tokens cached for future use (OpenCode only)`);
+  out.push(`- **Reasoning** — extended thinking / chain-of-thought tokens`);
+  out.push(``);
+
+  const withTokens = detections.filter(d => d.hasTokens && d.status === 'present');
+  if (withTokens.length > 0) {
+    out.push(`### Detected Tools With Token Data`);
+    out.push(``);
+    for (const d of withTokens) {
+      out.push(`- **${mdEscape(d.name)}** — \`${mdEscape(d.description)}\``);
+    }
+    out.push(``);
+  }
+
+  const noTokens = detections.filter(d => !d.hasTokens && d.status === 'present');
+  if (noTokens.length > 0) {
+    out.push(`### Detected Tools Without Token Data`);
+    out.push(``);
+    for (const d of noTokens) {
+      out.push(`- **${mdEscape(d.name)}** — \`${mdEscape(d.description)}\``);
+    }
+    out.push(``);
+  }
+
+  if (errors && errors.length > 0) {
+    out.push(`### Errors`);
+    out.push(``);
+    for (const e of errors.slice(0, 10)) {
+      out.push(`- ${mdEscape(e)}`);
+    }
+    if (errors.length > 10) {
+      out.push(`- … and ${errors.length - 10} more`);
+    }
+    out.push(``);
+  }
+
+  return out.join('\n');
+}