ai-usage-analyzer 0.1.0 → 0.2.0

package/README.md

@@ -76,10 +76,12 @@ 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 output
+ai-usage --markdown       # GitHub-flavored Markdown report
+ai-usage --md > report.md # same, save to file
+ai-usage -h               # help (also --help)
 ```
 
 ### Environment overrides
@@ -179,6 +181,38 @@ ai-usage --json | jq '.summary'
 # }
 ```
 
+### Markdown (`--markdown` / `--md`)
+
+GitHub-flavored markdown report with the same sections as the TUI (header,
+detected tools, overview, token breakdown, per-project, per-month, per-week,
+top sessions, notes). Designed to be pasted into GitHub issues, PRs, or
+Notion pages.
+
+```bash
+ai-usage --md > report.md
+cat report.md   # or just paste the output into a GitHub comment
+```
+
+Distribution bars use Unicode block characters (`█░`) so they render in
+plain markdown without colors. Sample output:
+
+```markdown
+# AI Token Usage Report
+
+**Range**: 2026-04-01 → 2026-06-27  
+**Sessions**: 411  
+**Total tokens**: 1.58B  
+**Cost**: $29.40 (opencode only)  
+
+## Detected AI Tools
+
+| Tool | Status | Path | Count | Tokens |
+|---|---|---|---:|---|
+| Codex | ✅ present | `~/.codex/sessions` | 94 | ✅ |
+| OpenCode | ✅ present | `~/.local/share/opencode/opencode.db` | 328 | ✅ |
+| ...
+```
+
 ## License
 
 MIT

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,
@@ -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.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/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');
+}