usagelens 0.2.0 → 0.3.0

package/README.md

@@ -12,20 +12,44 @@ That's it — it scans your local data, starts a server on <http://localhost:431
 
 - **Tokens, est. cost, sessions, cache hit-rate, streak** — with deltas vs the prior period
 - **Daily activity** bar chart and a **when-you-work** hour × weekday heatmap (hover for details)
-- **Tool breakdown** (Claude / Codex / Cursor) and **model mix** with per-model estimated cost
-- **Top projects** — which repos consume the most AI
-- **Session shape** (quick / standard / deep / marathon) with averages
-- **Cache effectiveness** trend and estimated savings
-- **Code authorship** (from Cursor) — AI-authored vs human lines over time
+- **Tool breakdown** (Claude / Codex / Cursor / Antigravity) and **model mix** with per-model estimated cost
+- **Cost per shipped code** — AI spend mapped to real git commits & lines (`$/commit`, `$/1K lines`, per project)
+- **Cost efficiency & model routing** — premium (Opus) share, output/input leverage, and estimated savings if routine turns were routed to a cheaper tier
+- **Tool usage** — how often Bash / Edit / Read / etc. are called
+- **Top projects**, **session shape**, **cache effectiveness**, and **code authorship** (Cursor)
+- **Budgets** — month-to-date spend vs a configured monthly budget, with straight-line projection
+- **Live refresh** — re-scan your data without restarting; **multi-account** aware
 
 ## Options
 
 ```bash
-usagelens                # start on :4319 and open the browser
-usagelens --port 8080    # custom port
-usagelens --no-open      # don't auto-open the browser
+usagelens                       # start on :4319 (loopback only) and open the browser
+usagelens --port 8080           # custom port
+usagelens --no-open             # don't auto-open the browser
+usagelens report                # print a markdown usage report to stdout
+usagelens report --json         # machine-readable report (pipe to jq, CI, Slack)
+usagelens report --range 7d     # 7d | 30d | 90d
 ```
 
+## Config (optional) — `~/.usagelens.json`
+
+```json
+{
+  "sources": [
+    { "tool": "claude", "dir": "~/.claude",          "label": "work@company.com" },
+    { "tool": "claude", "dir": "~/.claude-personal", "label": "me@personal.com" }
+  ],
+  "pricing": { "opus": { "input": 12, "output": 60 } },
+  "budget":  { "monthlyUsd": 500, "monthlyTokens": 2000000000 },
+  "git": true
+}
+```
+
+- **sources** — point at multiple config dirs to track multiple accounts (each labeled).
+- **pricing** — override the estimated per-model $/Mtoken rates.
+- **budget** — enables the budget panel + projection.
+- **git** — set `false` to skip the git correlation (cost-per-shipped-code).
+
 ## Data sources
 
 Read-only, from your machine:
@@ -39,7 +63,7 @@ Tools detected without usable local usage data (Gemini, GitHub Copilot, Ollama)
 ## Notes
 
 - **Cost is estimated** — list price × tokens ("API-equivalent value"), not a bill. If you're on a subscription, treat it as a proxy for usage.
-- Nothing is written to your tool directories, and nothing leaves your machine.
+- Nothing is written to your tool directories, and nothing leaves your machine. The server binds to **loopback (127.0.0.1) only**.
 - Requires **Node ≥ 22.5** (uses the built-in `node:sqlite`).
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagelens",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local dashboard for your AI coding usage across Claude Code, Codex CLI, and Cursor. Reads your machine's local data and serves an interactive dashboard on localhost. Read-only, offline, zero runtime dependencies.",
   "type": "module",
   "bin": {

package/src/lib/adapters.mjs

@@ -2,8 +2,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
-import { costOf } from './pricing.mjs';
+import { costOf, setPricingOverrides } from './pricing.mjs';
 import { antigravityAccount, claudeAccount, codexAccount, fallbackAccount } from './accounts.mjs';
+import { loadConfig } from './config.mjs';
 
 const HOME = homedir();
 const require = createRequire(import.meta.url);
@@ -25,7 +26,7 @@ function walk(dir, ext) {
 export function loadClaude(dir, account) {
   const root = dir ?? join(HOME, '.claude', 'projects');
   if (!existsSync(root)) return { events: [], commits: [], activity: [], status: { tool: 'claude', account, available: false, note: 'no projects dir' } };
-  const events = [];
+  const events = [], toolcalls = [];
   for (const f of walk(root, '.jsonl')) {
     let text; try { text = readFileSync(f, 'utf8'); } catch { continue; }
     for (const line of text.split('\n')) {
@@ -35,6 +36,12 @@ export function loadClaude(dir, account) {
       const m = row.message, u = m?.usage;
       if (!u || !m?.model) continue;
       const cwd = row.cwd ?? 'unknown';
+      // tool_use blocks in the assistant message content
+      if (Array.isArray(m.content)) {
+        for (const b of m.content) {
+          if (b?.type === 'tool_use' && b.name) toolcalls.push({ tool: 'claude', account, timestamp: row.timestamp, name: b.name });
+        }
+      }
       const t = {
         inputTokens: u.input_tokens ?? 0, outputTokens: u.output_tokens ?? 0,
         cacheReadTokens: u.cache_read_input_tokens ?? 0, cacheCreateTokens: u.cache_creation_input_tokens ?? 0,
@@ -46,7 +53,7 @@ export function loadClaude(dir, account) {
       });
     }
   }
-  return { events, commits: [], activity: [], status: statusOf('claude', account, events) };
+  return { events, commits: [], activity: [], toolcalls, status: statusOf('claude', account, events) };
 }
 
 // ---------- Codex ----------
@@ -157,22 +164,17 @@ function defaultSources() {
   ];
 }
 
-function configuredSources() {
-  const cfg = join(HOME, '.usagelens.json');
-  if (!existsSync(cfg)) return null;
-  try {
-    const j = JSON.parse(readFileSync(cfg, 'utf8'));
-    if (!Array.isArray(j.sources) || j.sources.length === 0) return null;
-    return j.sources.map((s) => ({ tool: s.tool, dir: expand(s.dir ?? ''), account: s.label ?? s.account ?? null }));
-  } catch { return null; }
-}
-
 const LOADERS = { claude: loadClaude, codex: loadCodex, cursor: loadCursor, antigravity: loadAntigravity };
 
 export function loadAll() {
-  const sources = configuredSources() ?? defaultSources();
-  const events = [], commits = [], activity = [], statuses = [];
+  const cfg = loadConfig();
+  setPricingOverrides(cfg.pricing);
+  const sources = (cfg.sources
+    ? cfg.sources.map((s) => ({ tool: s.tool, dir: expand(s.dir ?? ''), account: s.label ?? s.account ?? null }))
+    : null) ?? defaultSources();
+  const events = [], commits = [], activity = [], toolcalls = [], statuses = [];
   const accounts = new Set();
+  const projectPaths = new Map(); // project name -> real filesystem path (for git correlation)
   for (const s of sources) {
     const loader = LOADERS[s.tool];
     if (!loader) { statuses.push({ tool: s.tool, available: false, note: 'unknown tool' }); continue; }
@@ -180,6 +182,8 @@ export function loadAll() {
     try {
       const r = loader(s.dir, account);
       events.push(...r.events); commits.push(...r.commits); activity.push(...(r.activity ?? []));
+      if (r.toolcalls) toolcalls.push(...r.toolcalls);
+      for (const e of r.events) if (e.projectPath && e.projectPath !== 'unknown') projectPaths.set(e.project, e.projectPath);
       statuses.push(r.status);
       if (r.status.available) accounts.add(account);
     } catch (e) { statuses.push({ tool: s.tool, account, available: false, note: e.message }); }
@@ -191,5 +195,5 @@ export function loadAll() {
   ]) {
     if (existsSync(join(HOME, rel))) statuses.push({ tool, available: false, note });
   }
-  return { events, commits, activity, statuses, accounts: [...accounts].sort() };
+  return { events, commits, activity, toolcalls, statuses, accounts: [...accounts].sort(), projectPaths, config: cfg };
 }

package/src/lib/aggregate.mjs

@@ -1,4 +1,6 @@
 import { savingsOf } from './pricing.mjs';
+import { budgetStatus, efficiency, modelRouting, toolUsage } from './analytics.mjs';
+import { gitCorrelation } from './git.mjs';
 
 const MS_DAY = 86_400_000;
 const DAYS = { '7d': 7, '30d': 30, '90d': 90 };
@@ -156,6 +158,15 @@ function activitySummary(activity) {
   };
 }
 
+// Computed on demand (shells out to git across repos) — see /api/git.
+export async function gitReport(ds, range, now, account) {
+  const win = rangeWindow(range, now);
+  const evAll = account && account !== 'all' ? ds.events.filter((e) => e.account === account) : ds.events;
+  const cur = evAll.filter((e) => inWin(e.timestamp, win));
+  const cfg = ds.config ?? { git: true };
+  return gitCorrelation(cur, ds.projectPaths ?? new Map(), win, cfg.git !== false);
+}
+
 export function buildPayload(ds, range, now, account) {
   const win = rangeWindow(range, now), prior = priorWindow(range, now);
   const pick = (arr) => (account && account !== 'all' ? arr.filter((x) => x.account === account) : arr);
@@ -164,7 +175,10 @@ export function buildPayload(ds, range, now, account) {
   const prev = evAll.filter((e) => inWin(e.timestamp, prior));
   const commits = coAll.filter((c) => inWin(c.timestamp, win));
   const activity = acAll.filter((a) => inWin(a.timestamp, win));
+  const toolcalls = (account && account !== 'all' ? (ds.toolcalls ?? []).filter((t) => t.account === account) : (ds.toolcalls ?? []))
+    .filter((t) => inWin(t.timestamp, win));
   const lastAll = [...cur.map((e) => e.timestamp), ...commits.map((c) => c.timestamp), ...activity.map((a) => a.timestamp)];
+  const cfg = ds.config ?? { git: true, budget: null };
   return {
     summary: summarize(cur, prev),
     breakdowns: { byTool: group(cur, (e) => e.tool), byModel: group(cur, (e) => e.model), byProject: group(cur, (e) => e.project, 12) },
@@ -173,6 +187,11 @@ export function buildPayload(ds, range, now, account) {
     sessions: sessionShape(cur),
     authorship: authorship(commits),
     activity: activitySummary(activity),
+    efficiency: efficiency(cur),
+    routing: modelRouting(cur),
+    toolUsage: toolUsage(toolcalls),
+    gitEnabled: cfg.git !== false,   // git correlation is computed on demand via /api/git
+    budget: budgetStatus(account && account !== 'all' ? evAll : ds.events, cfg.budget, now),
     tools: ds.statuses,
     accounts: ds.accounts ?? [],
     meta: { range, account: account ?? 'all', generatedAt: now.toISOString(), lastActivity: lastAll.reduce((a, t) => (!a || t > a ? t : a), undefined) },

package/src/lib/analytics.mjs

@@ -0,0 +1,73 @@
+import { priceFor } from './pricing.mjs';
+
+const tokensOf = (e) => e.inputTokens + e.outputTokens + e.cacheReadTokens + e.cacheCreateTokens;
+const costAt = (p, e) =>
+  (e.inputTokens * p.input + e.outputTokens * p.output + e.cacheCreateTokens * p.cacheWrite + e.cacheReadTokens * p.cacheRead) / 1e6;
+
+// Leverage & waste signals from token events.
+export function efficiency(events) {
+  const input = events.reduce((a, e) => a + e.inputTokens, 0);
+  const output = events.reduce((a, e) => a + e.outputTokens, 0);
+  const cost = events.reduce((a, e) => a + e.costUsd, 0);
+  // "thrash": a turn with large uncached input but tiny output (context churn / re-reading)
+  const thrash = events.filter((e) => e.inputTokens > 20_000 && e.outputTokens < 300);
+  return {
+    outputPerInput: input ? output / input : 0,
+    costPerMOutput: output ? cost / (output / 1e6) : 0,
+    avgTokensPerMsg: events.length ? events.reduce((a, e) => a + tokensOf(e), 0) / events.length : 0,
+    thrashCount: thrash.length,
+    thrashCostUsd: thrash.reduce((a, e) => a + e.costUsd, 0),
+  };
+}
+
+// How much of spend is on premium models, and estimated savings if "routine" turns
+// (short outputs) were routed to a cheaper tier (Sonnet-equivalent pricing).
+export function modelRouting(events) {
+  const sonnet = priceFor('sonnet');
+  const premium = /opus/i;
+  let premiumCost = 0, totalCost = 0, routineCount = 0, savings = 0;
+  for (const e of events) {
+    totalCost += e.costUsd;
+    if (premium.test(e.model)) {
+      premiumCost += e.costUsd;
+      if (e.outputTokens < 800) { // routine / trivial turn
+        routineCount += 1;
+        savings += Math.max(0, e.costUsd - costAt(sonnet, e));
+      }
+    }
+  }
+  return {
+    premiumSharePct: totalCost ? (premiumCost / totalCost) * 100 : 0,
+    routineCount,
+    estRoutingSavingsUsd: savings,
+  };
+}
+
+// Tool-call frequency (from transcript tool_use blocks).
+export function toolUsage(toolcalls) {
+  const map = new Map();
+  for (const t of toolcalls) map.set(t.name, (map.get(t.name) ?? 0) + 1);
+  const top = [...map.entries()].map(([key, count]) => ({ key, count })).sort((a, b) => b.count - a.count);
+  return { total: toolcalls.length, top: top.slice(0, 10) };
+}
+
+// Month-to-date budget tracking + straight-line projection.
+export function budgetStatus(events, budget, now) {
+  if (!budget) return null;
+  const y = now.getFullYear(), m = now.getMonth();
+  const mtd = events.filter((e) => { const d = new Date(e.timestamp); return d.getFullYear() === y && d.getMonth() === m; });
+  const spendUsd = mtd.reduce((a, e) => a + e.costUsd, 0);
+  const spendTokens = mtd.reduce((a, e) => a + tokensOf(e), 0);
+  const dayOfMonth = now.getDate();
+  const daysInMonth = new Date(y, m + 1, 0).getDate();
+  const project = (v) => (dayOfMonth ? (v / dayOfMonth) * daysInMonth : v);
+  return {
+    monthlyUsd: budget.monthlyUsd ?? null,
+    monthlyTokens: budget.monthlyTokens ?? null,
+    spendUsd, spendTokens,
+    projectedUsd: project(spendUsd), projectedTokens: project(spendTokens),
+    usdPct: budget.monthlyUsd ? (spendUsd / budget.monthlyUsd) * 100 : null,
+    tokensPct: budget.monthlyTokens ? (spendTokens / budget.monthlyTokens) * 100 : null,
+    dayOfMonth, daysInMonth,
+  };
+}

package/src/lib/config.mjs

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const HOME = homedir();
+
+// ~/.usagelens.json — all optional:
+// {
+//   "sources": [ { "tool": "claude", "dir": "~/.claude", "label": "work@x.com" } ],
+//   "pricing": { "opus": { "input": 15, "output": 75, "cacheWrite": 18.75, "cacheRead": 1.5 } },
+//   "budget":  { "monthlyUsd": 500, "monthlyTokens": 2000000000 },
+//   "git":     true,
+//   "planUsd": 200
+// }
+let cached;
+export function loadConfig() {
+  if (cached) return cached;
+  const path = join(HOME, '.usagelens.json');
+  let raw = {};
+  if (existsSync(path)) {
+    try { raw = JSON.parse(readFileSync(path, 'utf8')); } catch { raw = {}; }
+  }
+  cached = {
+    sources: Array.isArray(raw.sources) ? raw.sources : null,
+    pricing: raw.pricing && typeof raw.pricing === 'object' ? raw.pricing : {},
+    budget: raw.budget && typeof raw.budget === 'object' ? raw.budget : null,
+    git: raw.git !== false, // default on
+    planUsd: typeof raw.planUsd === 'number' ? raw.planUsd : null,
+    configPath: existsSync(path) ? path : null,
+  };
+  return cached;
+}

package/src/lib/git.mjs

@@ -0,0 +1,72 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const tokensOf = (e) => e.inputTokens + e.outputTokens + e.cacheReadTokens + e.cacheCreateTokens;
+const iso = (d) => d.toISOString();
+
+function isRepo(dir) {
+  try { return existsSync(join(dir, '.git')); } catch { return false; }
+}
+
+// Commits + lines changed in a repo within [start,end], authored by anyone.
+async function repoStats(dir, start, end) {
+  try {
+    const { stdout: out } = await execFileAsync('git', [
+      '-C', dir, 'log', `--since=${iso(start)}`, `--until=${iso(end)}`,
+      '--no-merges', '--numstat', '--pretty=format:%x01%H',
+    ], { encoding: 'utf8', timeout: 6000, maxBuffer: 1 << 24 });
+    let commits = 0, added = 0, deleted = 0;
+    for (const line of out.split('\n')) {
+      if (line.startsWith('\x01')) { commits += 1; continue; }
+      const m = line.split('\t');
+      if (m.length === 3) { added += Number(m[0]) || 0; deleted += Number(m[1]) || 0; }
+    }
+    return { commits, linesChanged: added + deleted };
+  } catch { return null; }
+}
+
+// Correlate AI token spend per project with real git activity in the window.
+// Async + parallel across repos (each repo's `git log` runs concurrently).
+export async function gitCorrelation(events, projectPaths, window, enabled) {
+  if (!enabled) return { available: false, note: 'disabled in config', rows: [], totals: null };
+  const byProject = new Map();
+  for (const e of events) {
+    const cur = byProject.get(e.project) ?? { costUsd: 0, tokens: 0 };
+    cur.costUsd += e.costUsd; cur.tokens += tokensOf(e); byProject.set(e.project, cur);
+  }
+  // top projects by cost, so we bound how many git calls we make
+  const top = [...byProject.entries()].sort((a, b) => b[1].costUsd - a[1].costUsd).slice(0, 15);
+  const candidates = top
+    .map(([project, agg]) => ({ project, agg, dir: projectPaths.get?.(project) ?? projectPaths[project] }))
+    .filter((c) => c.dir && isRepo(c.dir));
+  const stats = await Promise.all(candidates.map((c) => repoStats(c.dir, window.start, window.end)));
+  const rows = [];
+  let anyRepo = false;
+  candidates.forEach((c, i) => {
+    const st = stats[i];
+    if (!st) return;
+    anyRepo = true;
+    rows.push({
+      project: c.project, costUsd: c.agg.costUsd, tokens: c.agg.tokens,
+      commits: st.commits, linesChanged: st.linesChanged,
+      usdPerCommit: st.commits ? c.agg.costUsd / st.commits : null,
+      usdPerKLine: st.linesChanged ? c.agg.costUsd / (st.linesChanged / 1000) : null,
+    });
+  });
+  rows.sort((a, b) => b.costUsd - a.costUsd);
+  const totals = rows.reduce((t, r) => ({
+    costUsd: t.costUsd + r.costUsd, commits: t.commits + r.commits, linesChanged: t.linesChanged + r.linesChanged,
+  }), { costUsd: 0, commits: 0, linesChanged: 0 });
+  return {
+    available: anyRepo, note: anyRepo ? null : 'no git repos found for active projects',
+    rows,
+    totals: anyRepo ? {
+      ...totals,
+      usdPerCommit: totals.commits ? totals.costUsd / totals.commits : null,
+      usdPerKLine: totals.linesChanged ? totals.costUsd / (totals.linesChanged / 1000) : null,
+    } : null,
+  };
+}

package/src/lib/pricing.mjs

@@ -8,8 +8,16 @@ const TABLE = [
 ];
 const DEFAULT = { input: 3, output: 15, cacheWrite: 3.75, cacheRead: 0.3 };
 
+// Optional per-key overrides from ~/.usagelens.json, e.g. { "opus": { "input": 12 } }
+let OVERRIDES = {};
+export function setPricingOverrides(o) { OVERRIDES = o && typeof o === 'object' ? o : {}; }
+
 export function priceFor(model) {
-  return (TABLE.find((r) => r.m.test(model || ''))?.p) ?? DEFAULT;
+  const base = (TABLE.find((r) => r.m.test(model || ''))?.p) ?? DEFAULT;
+  for (const key in OVERRIDES) {
+    if (new RegExp(key, 'i').test(model || '')) return { ...base, ...OVERRIDES[key] };
+  }
+  return base;
 }
 
 export function costOf(model, t) {

package/src/lib/report.mjs

@@ -0,0 +1,44 @@
+const tok = (n) => n >= 1e9 ? (n / 1e9).toFixed(2) + 'B' : n >= 1e6 ? (n / 1e6).toFixed(1) + 'M' : n >= 1e3 ? (n / 1e3).toFixed(1) + 'K' : String(Math.round(n));
+const usd = (n) => n >= 1000 ? '$' + (n / 1000).toFixed(1) + 'K' : '$' + n.toFixed(2);
+const pct = (n) => (n >= 0 ? '+' : '') + n.toFixed(1) + '%';
+
+export function reportText(p) {
+  const s = p.summary, L = [];
+  L.push(`# usagelens · last ${p.meta.range}`);
+  L.push('');
+  L.push(`You wrote **${tok(s.totalTokens)} tokens** across **${s.sessions} sessions** (${s.messages} messages, ${s.activeDays} active days, streak ${s.currentStreak}d).`);
+  L.push('');
+  L.push(`- Est. cost: **${usd(s.costUsd)}** (${pct(s.deltas.costPct)} vs prior)`);
+  L.push(`- Tokens: ${tok(s.totalTokens)} (${pct(s.deltas.tokensPct)} vs prior)`);
+  L.push(`- Cache hit: ${(s.cacheHitRate * 100).toFixed(0)}% · saved ${usd(s.cacheSavingsUsd)}`);
+  L.push('');
+  L.push('## Tools');
+  for (const t of p.breakdowns.byTool) L.push(`- ${t.key}: ${tok(t.tokens)} · ${usd(t.costUsd)} · ${t.sharePct.toFixed(0)}%`);
+  L.push('');
+  L.push('## Models');
+  for (const m of p.breakdowns.byModel.slice(0, 6)) L.push(`- ${m.key}: ${m.sharePct.toFixed(1)}% · ${usd(m.costUsd)}`);
+  L.push('');
+  L.push('## Top projects');
+  for (const pr of p.breakdowns.byProject.slice(0, 8)) L.push(`- ${pr.key}: ${tok(pr.tokens)} · ${usd(pr.costUsd)}`);
+  L.push('');
+  L.push('## Efficiency');
+  L.push(`- Output/input leverage: ${p.efficiency.outputPerInput.toFixed(2)}×`);
+  L.push(`- Premium (Opus) share: ${p.routing.premiumSharePct.toFixed(0)}%`);
+  L.push(`- Est. routing savings: ${usd(p.routing.estRoutingSavingsUsd)} (${p.routing.routineCount} routine turns → Sonnet)`);
+  L.push('');
+  if (p.git.available) {
+    L.push('## Cost per shipped code (git)');
+    const g = p.git.totals;
+    L.push(`- ${usd(g.costUsd)} across ${g.commits} commits, ${tok(g.linesChanged)} lines`);
+    L.push(`- ${g.usdPerCommit != null ? usd(g.usdPerCommit) : '—'} / commit · ${g.usdPerKLine != null ? usd(g.usdPerKLine) : '—'} / 1K lines`);
+    for (const r of p.git.rows.slice(0, 6)) L.push(`  - ${r.project}: ${usd(r.costUsd)} · ${r.commits}c · ${r.usdPerCommit != null ? usd(r.usdPerCommit) + '/c' : '—'}`);
+    L.push('');
+  }
+  if (p.toolUsage.total) {
+    L.push('## Tool usage');
+    for (const t of p.toolUsage.top.slice(0, 8)) L.push(`- ${t.key}: ${t.count}`);
+    L.push('');
+  }
+  L.push(`_Generated ${p.meta.generatedAt} · cost is estimated API-equivalent, not a bill._`);
+  return L.join('\n') + '\n';
+}

package/src/public/app.js

@@ -50,6 +50,18 @@ function barRow(label, right, pctWidth, color) {
   ]);
 }
 
+function budgetRow(label, value, ofText, pct, proj) {
+  const p = pct ?? 0;
+  const color = p >= 100 ? 'var(--warn)' : p >= 80 ? 'var(--c2)' : 'var(--good)';
+  return el('div', { class: 'barRow' }, [
+    el('div', { class: 'top' }, [
+      el('span', {}, `${label} ${value} `),
+      el('span', { class: 'r' }, `${ofText} · ${p.toFixed(0)}% · ${proj}`),
+    ]),
+    el('div', { class: 'track' }, [el('div', { class: 'fill', style: `width:${Math.min(100, Math.max(1, p))}%;background:${color}` })]),
+  ]);
+}
+
 // SVG bar chart (daily tokens)
 function barChart(data, h = 170) {
   const w = 1000, pad = 4, max = Math.max(1, ...data.map((d) => d.tokens));
@@ -133,6 +145,50 @@ function panel(titleText, meta, body) {
   return el('div', { class: 'card' }, [head, body]);
 }
 
+// ---- git cost-per-shipped-code: on-demand, cached per range ----
+const gitState = {}; // range -> computed git result
+function renderGitBody(g) {
+  if (!g.available) return el('div', { class: 'csub' }, g.note || 'no git repos found for active projects');
+  const t = g.totals;
+  return el('div', {}, [
+    el('div', { class: 'statPair', style: 'margin-bottom:12px' }, [
+      el('div', {}, [el('div', { class: 'k' }, '$ / COMMIT'), el('div', { class: 'v' }, t.usdPerCommit != null ? fmtUsd(t.usdPerCommit) : '—')]),
+      el('div', {}, [el('div', { class: 'k' }, '$ / 1K LINES'), el('div', { class: 'v' }, t.usdPerKLine != null ? fmtUsd(t.usdPerKLine) : '—')]),
+      el('div', {}, [el('div', { class: 'k' }, 'COMMITS'), el('div', { class: 'v' }, fmtInt(t.commits))]),
+      el('div', {}, [el('div', { class: 'k' }, 'LINES SHIPPED'), el('div', { class: 'v' }, fmtTok(t.linesChanged))]),
+    ]),
+    ...g.rows.map((r) => el('div', { class: 'barRow' }, [
+      el('div', { class: 'top' }, [
+        el('span', {}, r.project),
+        el('span', { class: 'r' }, `${fmtUsd(r.costUsd)} · ${fmtInt(r.commits)}c · ${r.usdPerCommit != null ? fmtUsd(r.usdPerCommit) + '/c' : '—'}`),
+      ]),
+      el('div', { class: 'track' }, [el('div', { class: 'fill', style: `width:${(r.costUsd / (g.rows[0].costUsd || 1)) * 100}%;background:var(--c1)` })]),
+    ])),
+  ]);
+}
+function gitPanel(d) {
+  const body = el('div', {});
+  const fillButton = () => {
+    body.innerHTML = '';
+    if (!d.gitEnabled) { body.append(el('div', { class: 'csub' }, 'git correlation disabled in config')); return; }
+    const btn = el('button', { class: 'bigbtn' }, '⚡ Compute cost-per-shipped-code');
+    const note = el('div', { class: 'csub', style: 'margin-top:10px' }, 'Maps AI spend to real git commits & lines in your repos. Runs `git log` locally — takes a few seconds.');
+    btn.addEventListener('click', async () => {
+      btn.disabled = true; btn.textContent = 'Computing… (scanning repos)';
+      try {
+        const g = await (await fetch('/api/git?range=' + range)).json();
+        gitState[range] = g; body.innerHTML = ''; body.append(renderGitBody(g));
+      } catch (e) {
+        btn.disabled = false; btn.textContent = '⚡ Compute cost-per-shipped-code';
+      }
+    });
+    body.append(btn, note);
+  };
+  if (gitState[range]) body.append(renderGitBody(gitState[range]));
+  else fillButton();
+  return panel('COST PER SHIPPED CODE · GIT × AI SPEND', 'AI $ mapped to real commits & lines · on-demand', body);
+}
+
 function render(d) {
   const app = $('#app'); app.innerHTML = '';
   const s = d.summary, rng = d.meta.range;
@@ -208,6 +264,37 @@ function render(d) {
   ]);
   app.append(el('div', { class: 'grid two' }, [panel('SESSION SHAPE', 'by token size', shBody), panel('CACHE EFFECTIVENESS', 'daily hit rate', cacheBody)]));
 
+  // budget (only if configured)
+  if (d.budget && (d.budget.monthlyUsd || d.budget.monthlyTokens)) {
+    const b = d.budget;
+    const rows = [];
+    if (b.monthlyUsd) rows.push(budgetRow('SPEND (MTD)', fmtUsd(b.spendUsd), `of ${fmtUsd(b.monthlyUsd)}`, b.usdPct, `proj ${fmtUsd(b.projectedUsd)}`));
+    if (b.monthlyTokens) rows.push(budgetRow('TOKENS (MTD)', fmtTok(b.spendTokens), `of ${fmtTok(b.monthlyTokens)}`, b.tokensPct, `proj ${fmtTok(b.projectedTokens)}`));
+    app.append(el('div', { class: 'grid' }, [panel('BUDGET', `day ${b.dayOfMonth}/${b.daysInMonth} this month`, el('div', {}, rows))]));
+  }
+
+  // cost per shipped code (git) — on-demand (shells out to git; ~seconds)
+  app.append(el('div', { class: 'grid' }, [gitPanel(d)]));
+
+  // efficiency + routing, and tool usage
+  const eff = d.efficiency, rt = d.routing;
+  const effBody = el('div', {}, [
+    el('div', { style: 'font-size:30px;font-weight:700;color:var(--good)' }, fmtUsd(rt.estRoutingSavingsUsd)),
+    el('div', { class: 'csub', style: 'margin-bottom:12px' }, `est. saved if ${fmtInt(rt.routineCount)} routine Opus turns routed to Sonnet`),
+    el('div', { class: 'statPair' }, [
+      el('div', {}, [el('div', { class: 'k' }, 'PREMIUM SHARE'), el('div', { class: 'v' }, rt.premiumSharePct.toFixed(0) + '%')]),
+      el('div', {}, [el('div', { class: 'k' }, 'OUTPUT/INPUT'), el('div', { class: 'v' }, eff.outputPerInput.toFixed(2) + '×')]),
+      el('div', {}, [el('div', { class: 'k' }, '$ / 1M OUT'), el('div', { class: 'v' }, fmtUsd(eff.costPerMOutput))]),
+    ]),
+    el('div', { class: 'csub', style: 'margin-top:10px' }, `${fmtInt(eff.thrashCount)} thrash turns (big input, tiny output) · ${fmtUsd(eff.thrashCostUsd)}`),
+  ]);
+  const tu = d.toolUsage;
+  const maxTu = tu.top[0]?.count || 1;
+  const tuBody = tu.total === 0
+    ? el('div', { class: 'csub' }, 'no tool-call data in range')
+    : el('div', {}, tu.top.map((t) => barRow(t.key, fmtInt(t.count), (t.count / maxTu) * 100, 'var(--c4)')));
+  app.append(el('div', { class: 'grid two' }, [panel('COST EFFICIENCY · MODEL ROUTING', 'where spend could shrink', effBody), panel('TOOL USAGE', `${fmtInt(tu.total)} calls`, tuBody)]));
+
   // authorship
   let authBody;
   if (d.authorship.totalCommits === 0) authBody = el('div', { class: 'csub' }, 'No Cursor commit data in this range.');
@@ -256,4 +343,11 @@ $('#toggle').addEventListener('click', (e) => {
   [...$('#toggle').children].forEach((c) => c.classList.toggle('on', c === b));
   $('#app').innerHTML = '<div class="loading">Loading…</div>'; load();
 });
+$('#refresh').addEventListener('click', async () => {
+  const btn = $('#refresh'); btn.disabled = true; btn.textContent = '⟳ Scanning…';
+  for (const k in gitState) delete gitState[k]; // git cache is stale after a re-scan
+  try { await fetch('/api/refresh'); } catch {}
+  await load();
+  btn.disabled = false; btn.textContent = '⟳ Refresh';
+});
 load();

package/src/public/index.html

@@ -23,7 +23,9 @@
   .heroSub{color:var(--sub);font-size:14px;margin:0}
   .heroSub b{color:var(--ink);font-weight:600}
   .controls{display:flex;gap:10px;align-items:center;flex-wrap:wrap}
-  #account{font-family:var(--mono);font-size:13px;color:var(--ink);background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:7px 12px;cursor:pointer;max-width:280px}
+  #refresh{font-family:var(--mono);font-size:13px;color:var(--sub);background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:7px 12px;cursor:pointer}
+  #refresh:hover{color:var(--accent);border-color:var(--accent)}
+  #refresh:disabled{opacity:.5;cursor:wait}
   .toggle{display:inline-flex;gap:2px;background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:3px}
   .toggle button{border:0;background:transparent;color:var(--sub);font-weight:600;font-size:13px;
     padding:6px 14px;border-radius:7px;cursor:pointer;font-family:var(--mono)}
@@ -65,6 +67,8 @@
   .chip b{color:var(--ink)} .chip.on b{color:var(--good)} .chip .d{margin-right:6px}
   .foot{margin-top:22px;font-size:12px;color:var(--sub);font-family:var(--mono)}
   .loading{padding:60px;text-align:center;color:var(--sub)}
+  .bigbtn{font-family:var(--mono);font-size:14px;font-weight:600;color:#fff;background:var(--accent);border:0;border-radius:10px;padding:12px 20px;cursor:pointer}
+  .bigbtn:hover{filter:brightness(1.08)} .bigbtn:disabled{opacity:.6;cursor:wait}
   svg{display:block;width:100%;overflow:visible}
   .tip{fill:var(--sub);font-size:9px;font-family:var(--mono)}
 </style>
@@ -73,10 +77,13 @@
 <div class="wrap">
   <div class="row">
     <div class="eyebrow" id="eyebrow">ANALYTICS · LAST 30 DAYS</div>
-    <div class="toggle" id="toggle">
-      <button data-r="7d">7d</button>
-      <button data-r="30d" class="on">30d</button>
-      <button data-r="90d">90d</button>
+    <div class="controls">
+      <button id="refresh" title="Re-scan local data">⟳ Refresh</button>
+      <div class="toggle" id="toggle">
+        <button data-r="7d">7d</button>
+        <button data-r="30d" class="on">30d</button>
+        <button data-r="90d">90d</button>
+      </div>
     </div>
   </div>
   <div id="app"><div class="loading">Reading your local AI data…</div></div>

package/src/server.mjs

@@ -13,7 +13,7 @@ import { platform } from 'node:os';
 import { extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadAll } from './lib/adapters.mjs';
-import { buildPayload } from './lib/aggregate.mjs';
+import { buildPayload, gitReport } from './lib/aggregate.mjs';
 
 const PUBLIC = join(fileURLToPath(new URL('.', import.meta.url)), 'public');
 const MIME = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml' };
@@ -27,14 +27,39 @@ function parseArgs(argv) {
   return o;
 }
 
+function scan(quiet) {
+  const t0 = Date.now();
+  const ds = loadAll();
+  if (!quiet) {
+    process.stdout.write(`usagelens · loaded ${ds.events.length} usage events + ${ds.commits.length} commits + ${ds.activity.length} activity in ${Date.now() - t0}ms\n`);
+    process.stdout.write(`usagelens · accounts: ${ds.accounts.join(', ') || 'none'}\n`);
+    for (const s of ds.statuses) process.stdout.write(`   ${s.available ? '✓' : '·'} ${s.tool}${s.count != null ? ` (${s.count})` : ''}${s.note ? ' — ' + s.note : ''}\n`);
+  }
+  return ds;
+}
+
+// ---- headless report mode: `usagelens report [--json] [--range 30d] ----
+if (process.argv[2] === 'report') {
+  const args = process.argv.slice(3);
+  const json = args.includes('--json');
+  const ri = args.indexOf('--range');
+  const range = ri >= 0 && ['7d', '30d', '90d'].includes(args[ri + 1]) ? args[ri + 1] : '30d';
+  const { reportText } = await import('./lib/report.mjs');
+  const ds = scan(true);
+  const now = new Date();
+  const payload = buildPayload(ds, range, now, 'all');
+  payload.git = await gitReport(ds, range, now, 'all'); // report includes git (CLI can afford it)
+  process.stdout.write(json ? JSON.stringify(payload, null, 2) + '\n' : reportText(payload));
+  process.exit(0);
+}
+
 const { port, open } = parseArgs(process.argv.slice(2));
 
 process.stdout.write('usagelens · scanning Claude, Codex, Cursor, Antigravity …\n');
-const t0 = Date.now();
-const dataset = loadAll();
-process.stdout.write(`usagelens · loaded ${dataset.events.length} usage events + ${dataset.commits.length} commits + ${dataset.activity.length} activity in ${Date.now() - t0}ms\n`);
-process.stdout.write(`usagelens · accounts: ${dataset.accounts.join(', ') || 'none'}\n`);
-for (const s of dataset.statuses) process.stdout.write(`   ${s.available ? '✓' : '·'} ${s.tool}${s.count != null ? ` (${s.count})` : ''}${s.note ? ' — ' + s.note : ''}\n`);
+let dataset = scan(false);
+
+const gitCache = new Map();  // key `range|account` -> JSON string; cleared on refresh
+const dashCache = new Map(); // same; snapshot valid until next refresh
 
 const server = createServer((req, res) => {
   const url = new URL(req.url ?? '/', 'http://localhost');
@@ -42,10 +67,32 @@ const server = createServer((req, res) => {
     const rq = url.searchParams.get('range');
     const range = ['7d', '30d', '90d'].includes(rq) ? rq : '30d';
     const account = url.searchParams.get('account') || 'all';
-    const body = JSON.stringify(buildPayload(dataset, range, new Date(), account));
+    const key = `${range}|${account}`;
+    let body = dashCache.get(key);
+    if (!body) { body = JSON.stringify(buildPayload(dataset, range, new Date(), account)); dashCache.set(key, body); }
     res.writeHead(200, { 'content-type': 'application/json' }).end(body);
     return;
   }
+  if (url.pathname === '/api/git') {
+    const rq = url.searchParams.get('range');
+    const range = ['7d', '30d', '90d'].includes(rq) ? rq : '30d';
+    const account = url.searchParams.get('account') || 'all';
+    const key = `${range}|${account}`;
+    if (gitCache.has(key)) { res.writeHead(200, { 'content-type': 'application/json' }).end(gitCache.get(key)); return; }
+    gitReport(dataset, range, new Date(), account).then((g) => {
+      const body = JSON.stringify(g);
+      gitCache.set(key, body);
+      res.writeHead(200, { 'content-type': 'application/json' }).end(body);
+    }).catch((e) => { res.writeHead(500, { 'content-type': 'application/json' }).end(JSON.stringify({ available: false, note: 'git error: ' + e.message, rows: [] })); });
+    return;
+  }
+  if (url.pathname === '/api/refresh') {
+    dataset = scan(true);
+    gitCache.clear();
+    dashCache.clear();
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ok: true, events: dataset.events.length }));
+    return;
+  }
   const name = url.pathname === '/' ? 'index.html' : url.pathname.replace(/^\/+/, '').replace(/\.\./g, '');
   const file = join(PUBLIC, name);
   if (existsSync(file) && statSync(file).isFile()) {
@@ -56,7 +103,8 @@ const server = createServer((req, res) => {
   }
 });
 
-server.listen(port, () => {
+// Bind to loopback only — the dashboard exposes your usage/projects/cost.
+server.listen(port, '127.0.0.1', () => {
   const link = `http://localhost:${port}`;
   process.stdout.write(`\nusagelens · dashboard → ${link}\n`);
   if (open) {