metrascope 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keshav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# metrascope
+
+See where your coding-agent tokens go. One local command, no upload.
+
+A unified, local dashboard for **multiple coding agents** — pick an agent in the
+header and see its own usage. Auto-detects whatever you have installed.
+
+| Agent | Reads | Tokens | Reasoning | Cache | Est. cost | Rate limit |
+|---|---|---|---|---|---|---|
+| **Codex** | `~/.codex` sessions | ✓ | ✓ | ✓ | — | ✓ |
+| **Claude Code** | `~/.claude/projects` | ✓ | — | ✓ | ✓ | — |
+| **Qwen Code** | `~/.qwen/projects/**/chats` | ✓ | ✓ | ✓ | — | — |
+| **OpenCode** | `~/.local/share/opencode/opencode.db` (SQLite) | ✓ | ✓ | ✓ | ✓ | — |
+| **Gemini CLI** | `~/.gemini` | detected (no per-turn token data) | — | — | — | — |
+
+## Run
+
+```bash
+npx metrascope
+```
+
+That's it — it opens a dashboard in your browser. Or from a clone:
+
+```bash
+npm install
+npm start
+```
+
+> The OpenCode adapter reads a SQLite store via Node's built-in `node:sqlite`,
+> which needs **Node 22.5+**. Everything else works on Node 18+. OpenCode is
+> loaded lazily, so older Node still runs fine for the other agents.
+
+## Options
+
+```bash
+metrascope --port 8080
+metrascope --no-open
+metrascope --codex-home ~/.codex
+```
+
+Per-agent homes can be overridden via env: `CODEX_HOME`, `CLAUDE_HOME`,
+`QWEN_HOME`, `GEMINI_HOME`.
+
+## Architecture
+
+Each agent is an **adapter** in `src/adapters/` exporting
+`{ id, label, mark, accent, capabilities, home, detect, parse }`. Every adapter
+normalizes its raw logs into one shared schema and hands them to
+`aggregate.buildResult()`, which produces the daily/model/project/tool/weekday
+breakdowns and insights. The dashboard reads `capabilities` to show only the
+panels an agent supports (rate-limit for Codex, est. cost for Claude, reasoning
+for Codex/Qwen, …).
+
+To add an agent, drop a new adapter module in `src/adapters/`, register it in
+`src/adapters/index.js`, and the UI picks it up automatically.
+
+- `GET /api/sources` — all known agents + whether their data is present
+- `GET /api/data?source=<id>` — normalized dashboard data for one agent
+- `GET /api/refresh?source=<id>` — re-parse one agent
+
+## Dashboard
+
+- **Agent switcher** — segmented control of detected agents; per-agent accent/branding.
+- **KPI strip** — total / cached tokens, sessions, and an adaptive third stat
+  (reasoning, est. cost, or output depending on the agent).
+- **Rate-limit panel** (Codex) — live 5-hour and weekly window usage with reset countdowns.
+- **Overview** — daily stacked-token chart, model-share donut, top projects, weekday, tools (all hover-interactive).
+- **Sessions** — sortable, searchable, model-filterable table; click a row for a drilldown drawer.
+- **Drilldown drawer** — every prompt in a session, its turn-by-turn token chart, and tool usage.
+- **Prompts** — most expensive prompts across all sessions.
+- **Insights** — actionable findings (context pressure, reasoning share, tool-heavy sessions, marathon threads, est. spend, rate-limit pressure), each with a concrete "try this".
+- **Share card** — render a 1200×630 PNG of your stats locally (nothing is uploaded).
+- Light / dark themes (varna design tokens).
+
+## Notes
+
+Token events expose usage (and, for Codex, rate-limit pressure), not a reliable
+per-token invoice. Costs shown for Claude Code are **API-rate estimates**, not
+your subscription bill. Reasoning tokens are reported as a subset of output
+tokens (`total = input + output`).

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "metrascope",
+  "version": "0.1.0",
+  "description": "See where your coding-agent tokens go. One local command — Codex, Claude Code, Qwen Code, OpenCode & more. Zero upload.",
+  "main": "src/index.js",
+  "bin": {
+    "metrascope": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "check": "node --check src/index.js && node --check src/server.js && node -e \"require('./src/adapters')\""
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "codex",
+    "claude-code",
+    "qwen-code",
+    "opencode",
+    "tokens",
+    "usage",
+    "analytics",
+    "dashboard",
+    "ai-agent",
+    "llm",
+    "cost"
+  ],
+  "author": "Keshav <crownbalaji27@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Buckibarnes17/codex-spend.git"
+  },
+  "homepage": "https://github.com/Buckibarnes17/codex-spend#readme",
+  "bugs": {
+    "url": "https://github.com/Buckibarnes17/codex-spend/issues"
+  },
+  "dependencies": {
+    "express": "^4.21.0",
+    "open": "^10.1.0"
+  }
+}

package/src/adapters/aggregate.js

@@ -0,0 +1,331 @@
+// Shared aggregation: turns normalized per-session data from any adapter into
+// the single dashboard schema (daily/model/project/tool breakdowns + insights).
+const { sum, fmt } = require('./shared');
+
+function addMetric(target, source) {
+  target.inputTokens += source.inputTokens || 0;
+  target.cachedInputTokens += source.cachedInputTokens || 0;
+  target.outputTokens += source.outputTokens || 0;
+  target.reasoningOutputTokens += source.reasoningOutputTokens || 0;
+  target.totalTokens += source.totalTokens || 0;
+}
+
+function groupTokenTotals(sessions, key) {
+  const out = {};
+  for (const session of sessions) {
+    const value = session[key] || 'unknown';
+    out[value] = (out[value] || 0) + session.totalTokens;
+  }
+  return out;
+}
+
+// Group a flat list of turns into prompt buckets (consecutive turns under the
+// same user prompt), attaching per-prompt tool counts. Used by every adapter.
+function buildPromptBreakdown(turns, toolEvents, fallbackTitle) {
+  const promptKey = (prompt, fallback) => {
+    const value = String(prompt || fallback || '(continuation)').trim();
+    return value || '(continuation)';
+  };
+  const groups = [];
+  let current = null;
+  const flush = () => {
+    if (!current) return;
+    current.totalTokens = current.turns.reduce((t, turn) => t + (turn.totalTokens || 0), 0);
+    current.model = Object.entries(current.modelCounts).sort((a, b) => b[1] - a[1])[0]?.[0] || 'unknown';
+    current.tools = Object.entries(current.toolCounts).map(([tool, count]) => ({ tool, count })).sort((a, b) => b.count - a.count);
+    delete current.modelCounts;
+    delete current.toolCounts;
+    groups.push(current);
+    current = null;
+  };
+  for (const turn of turns) {
+    const key = promptKey(turn.prompt, fallbackTitle);
+    if (!current || current.key !== key) {
+      flush();
+      current = {
+        key, prompt: key.slice(0, 700), firstTimestamp: turn.timestamp, lastTimestamp: turn.timestamp,
+        turnIds: [], turnCount: 0, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0,
+        reasoningOutputTokens: 0, totalTokens: 0, maxTurnTokens: 0, model: 'unknown', modelCounts: {}, toolCounts: {}, turns: [],
+      };
+    }
+    current.lastTimestamp = turn.timestamp || current.lastTimestamp;
+    current.turnIds.push(turn.turnId);
+    current.turnCount += 1;
+    current.inputTokens += turn.inputTokens || 0;
+    current.cachedInputTokens += turn.cachedInputTokens || 0;
+    current.outputTokens += turn.outputTokens || 0;
+    current.reasoningOutputTokens += turn.reasoningOutputTokens || 0;
+    current.maxTurnTokens = Math.max(current.maxTurnTokens, turn.totalTokens || 0);
+    if (turn.model) current.modelCounts[turn.model] = (current.modelCounts[turn.model] || 0) + 1;
+    current.turns.push({
+      turnId: turn.turnId, timestamp: turn.timestamp, model: turn.model,
+      inputTokens: turn.inputTokens, cachedInputTokens: turn.cachedInputTokens, outputTokens: turn.outputTokens,
+      reasoningOutputTokens: turn.reasoningOutputTokens, totalTokens: turn.totalTokens, contextWindow: turn.contextWindow,
+    });
+  }
+  flush();
+  for (const toolEvent of toolEvents || []) {
+    const key = promptKey(toolEvent.prompt, fallbackTitle);
+    const group = groups.find((item) => item.key === key);
+    if (!group) continue;
+    const existing = group.tools.find((tool) => tool.tool === toolEvent.name);
+    if (existing) existing.count += 1;
+    else group.tools.push({ tool: toolEvent.name, count: 1 });
+    group.tools.sort((a, b) => b.count - a.count);
+  }
+  return groups.map(({ key, ...group }, index) => ({ rank: index + 1, ...group }));
+}
+
+function generateInsights(sessions, totals, largestTurns, topPrompts, weekdayUsage, caps) {
+  const insights = [];
+  if (sessions.length === 0) return insights;
+  const agent = caps.label || 'the agent';
+
+  const cachedPct = totals.totalTokens > 0 ? totals.cachedInputTokens / totals.totalTokens : 0;
+  if (caps.cache && cachedPct > 0.35) {
+    insights.push({
+      type: 'info',
+      title: `${Math.round(cachedPct * 100)}% of tokens came from cached input`,
+      detail: `${agent} is reusing substantial context. That is usually good for continuity, but long threads can still grow expensive in raw token volume.`,
+      action: 'Cached context is cheaper than fresh reads, so this is mostly healthy. The lever that still matters is thread length — a fresh thread resets the context carried forward.',
+    });
+  }
+
+  if (caps.cost && totals.totalCost > 0) {
+    insights.push({
+      type: 'info',
+      title: `Estimated API-equivalent spend: $${totals.totalCost.toFixed(2)}`,
+      detail: `Across ${fmt(totals.totalTokens)} tokens. This is an API-rate estimate, not your subscription bill — useful for comparing where tokens (and cost) concentrate.`,
+      action: 'Sort the sessions and prompts tables by tokens to find the few threads driving most of the estimated cost.',
+    });
+  }
+
+  const reasoningPct = totals.outputTokens > 0 ? totals.reasoningOutputTokens / totals.outputTokens : 0;
+  if (caps.reasoning && totals.reasoningOutputTokens > 0 && reasoningPct > 0.4) {
+    insights.push({
+      type: 'neutral',
+      title: `${Math.round(reasoningPct * 100)}% of output tokens were reasoning, not final answers`,
+      detail: `${agent} spent ${fmt(totals.reasoningOutputTokens)} tokens thinking versus ${fmt(totals.outputTokens - totals.reasoningOutputTokens)} tokens writing visible replies.`,
+      action: 'Higher reasoning effort helps on hard problems but costs tokens on simple ones. Lower the reasoning effort for routine edits and questions.',
+    });
+  }
+
+  const contextPressured = sessions.filter((s) => s.contextWindow && s.peakInputTokens && s.peakInputTokens / s.contextWindow >= 0.8);
+  if (contextPressured.length >= 3) {
+    insights.push({
+      type: 'warning',
+      title: `${contextPressured.length} sessions filled 80%+ of the context window`,
+      detail: 'When the context window gets close to full, the agent spends more tokens carrying history forward, and older details can be summarized away.',
+      action: 'Start a fresh session for a new task instead of continuing a near-full thread. Paste a short summary into the first message to preserve what matters.',
+    });
+  }
+
+  const outputPct = totals.totalTokens > 0 ? totals.outputTokens / totals.totalTokens : 0;
+  if (outputPct < 0.05 && totals.totalTokens > 0) {
+    insights.push({
+      type: 'neutral',
+      title: `${(outputPct * 100).toFixed(1)}% of tokens were visible output`,
+      detail: 'Most usage is the agent reading context, tool results, instructions, and prior conversation rather than writing final answers.',
+      action: 'Because reading dominates, keeping threads short and pointing the agent at specific files matters far more than asking for shorter answers.',
+    });
+  }
+
+  const longSessions = sessions.filter((session) => session.turnCount >= 50);
+  if (longSessions.length > 0) {
+    const longTokens = longSessions.reduce((s, ses) => s + ses.totalTokens, 0);
+    insights.push({
+      type: 'warning',
+      title: `${longSessions.length} long session${longSessions.length === 1 ? '' : 's'} crossed 50 turns`,
+      detail: `These threads used ${fmt(longTokens)} tokens combined. Long sessions are often where context grows the most.`,
+      action: 'When a session drifts into a new task, start a fresh thread. A handoff note (or CONTEXT.md) carries the important bits without the full history.',
+    });
+  }
+
+  const topProject = Object.entries(groupTokenTotals(sessions, 'project')).sort((a, b) => b[1] - a[1])[0];
+  if (topProject && topProject[1] / Math.max(totals.totalTokens, 1) >= 0.6) {
+    insights.push({
+      type: 'info',
+      title: `${topProject[0]} dominates usage`,
+      detail: `${topProject[0]} accounts for ${Math.round((topProject[1] / totals.totalTokens) * 100)}% of all parsed tokens.`,
+      action: 'Not a problem by itself, but if this project runs long marathon threads, splitting them into focused sessions would shrink its footprint.',
+    });
+  }
+
+  if (largestTurns[0] && largestTurns[0].totalTokens > 100000) {
+    insights.push({
+      type: 'warning',
+      title: 'Your largest turn crossed 100K tokens',
+      detail: `One turn alone used ${fmt(largestTurns[0].totalTokens)} tokens — likely a large context window, many tool outputs, or a long accumulated thread.`,
+      action: 'Single huge turns usually mean the agent re-read a very full context. Breaking the work into smaller asks keeps each turn cheaper.',
+    });
+  }
+
+  const shortExpensive = topPrompts.filter((prompt) => prompt.prompt.length < 40 && prompt.totalTokens > 100000);
+  if (shortExpensive.length > 0) {
+    insights.push({
+      type: 'warning',
+      title: `${shortExpensive.length} short prompt${shortExpensive.length === 1 ? '' : 's'} used 100K+ tokens`,
+      detail: 'Short follow-ups can still be expensive because the agent may be re-reading the full thread, tool output, and workspace context.',
+      action: 'Be specific even on follow-ups. "Yes, update auth.js and run the tests" gives a target so the agent spends fewer turns figuring out what you meant.',
+    });
+  }
+
+  const toolHeavy = sessions.filter((s) => s.promptCount > 0 && s.toolCount > s.promptCount * 4);
+  if (caps.tools && toolHeavy.length >= 3) {
+    const toolTokens = toolHeavy.reduce((s, ses) => s + ses.totalTokens, 0);
+    insights.push({
+      type: 'info',
+      title: `${toolHeavy.length} sessions ran 4x+ more tool calls than prompts`,
+      detail: `These tool-heavy sessions used ${fmt(toolTokens)} tokens. Every tool call (reading files, running commands) is a round trip that re-reads the thread.`,
+      action: 'Point the agent at exact files and lines when you can. "Fix the bug in src/auth.js:42" triggers fewer searches than "fix the login bug".',
+    });
+  }
+
+  const multiTurnPrompts = topPrompts.filter((prompt) => prompt.turnCount >= 5);
+  if (multiTurnPrompts.length > 0) {
+    insights.push({
+      type: 'info',
+      title: `${multiTurnPrompts.length} costly prompt${multiTurnPrompts.length === 1 ? '' : 's'} triggered multiple turns`,
+      detail: 'These prompts likely caused tool-heavy work. Drill into a session to see how much each prompt and continuation consumed.',
+      action: 'Open one of these in the session view to see exactly which continuation turns spent the tokens.',
+    });
+  }
+
+  if (weekdayUsage.length >= 3) {
+    const ranked = [...weekdayUsage].filter((d) => d.sessions > 0).sort((a, b) => b.avgTokens - a.avgTokens);
+    if (ranked.length >= 2) {
+      const busiest = ranked[0];
+      const quietest = ranked[ranked.length - 1];
+      insights.push({
+        type: 'neutral',
+        title: `You use ${agent} most on ${busiest.name}s`,
+        detail: `${busiest.name} sessions average ${fmt(busiest.avgTokens)} tokens each, versus ${fmt(quietest.avgTokens)} on ${quietest.name}s.`,
+        action: null,
+      });
+    }
+  }
+
+  const latestRate = sessions.find((session) => session.rateLimit)?.rateLimit;
+  if (caps.rateLimit && latestRate?.primaryUsedPercent != null && latestRate.primaryUsedPercent >= 80) {
+    insights.push({
+      type: 'warning',
+      title: `Primary limit is ${latestRate.primaryUsedPercent}% used`,
+      detail: 'The latest local rate-limit event is near exhaustion for the current 5-hour window.',
+      action: 'You are close to the cap. Heavy, long-context sessions burn the window fastest — defer big runs until it resets, shown in the limits panel.',
+    });
+  }
+
+  return insights;
+}
+
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+// sessions: normalized session objects. source/capabilities: adapter metadata.
+function buildResult(sessions, source, capabilities, warnings = []) {
+  const caps = { label: source.label, ...capabilities };
+  sessions.sort((a, b) => (b.updatedTimestamp || '').localeCompare(a.updatedTimestamp || ''));
+
+  const dailyMap = {}, weekdayMap = {}, modelMap = {}, projectMap = {}, toolMap = {};
+  const largestTurns = [], topPrompts = [];
+  const totals = {
+    totalSessions: sessions.length, totalTurns: 0, totalPrompts: 0, totalToolCalls: 0,
+    inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0,
+    totalCost: 0, avgTokensPerTurn: 0, avgTokensPerSession: 0, dateRange: null, latestRateLimit: null,
+  };
+
+  for (const session of sessions) {
+    totals.totalTurns += session.turnCount;
+    totals.totalPrompts += session.promptCount;
+    totals.totalToolCalls += session.toolCount;
+    totals.totalCost += session.cost || 0;
+    addMetric(totals, session);
+
+    if (!dailyMap[session.date]) dailyMap[session.date] = { date: session.date, sessions: 0, turns: 0, toolCalls: 0, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0 };
+    dailyMap[session.date].sessions += 1;
+    dailyMap[session.date].turns += session.turnCount;
+    dailyMap[session.date].toolCalls += session.toolCount;
+    addMetric(dailyMap[session.date], session);
+
+    if (session.timestamp) {
+      const wd = new Date(session.timestamp).getDay();
+      if (!weekdayMap[wd]) weekdayMap[wd] = { weekday: wd, sessions: 0, totalTokens: 0 };
+      weekdayMap[wd].sessions += 1;
+      weekdayMap[wd].totalTokens += session.totalTokens;
+    }
+
+    const model = session.model || 'unknown';
+    if (!modelMap[model]) modelMap[model] = { model, sessions: 0, turns: 0, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0 };
+    modelMap[model].sessions += 1;
+    modelMap[model].turns += session.turnCount;
+    addMetric(modelMap[model], session);
+
+    const project = session.project || 'unknown';
+    if (!projectMap[project]) projectMap[project] = { project, sessions: 0, turns: 0, toolCalls: 0, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0 };
+    projectMap[project].sessions += 1;
+    projectMap[project].turns += session.turnCount;
+    projectMap[project].toolCalls += session.toolCount;
+    addMetric(projectMap[project], session);
+
+    for (const [tool, count] of Object.entries(session.toolCounts || {})) {
+      if (!toolMap[tool]) toolMap[tool] = { tool, count: 0 };
+      toolMap[tool].count += count;
+    }
+
+    for (const turn of session.turns) {
+      largestTurns.push({
+        sessionId: session.sessionId, title: session.title, project: session.project, timestamp: turn.timestamp, model: turn.model,
+        prompt: turn.prompt ? String(turn.prompt).slice(0, 260) : session.title,
+        inputTokens: turn.inputTokens, cachedInputTokens: turn.cachedInputTokens, outputTokens: turn.outputTokens,
+        reasoningOutputTokens: turn.reasoningOutputTokens, totalTokens: turn.totalTokens,
+      });
+    }
+    for (const prompt of session.promptBreakdown) {
+      topPrompts.push({
+        sessionId: session.sessionId, title: session.title, project: session.project, date: session.date,
+        timestamp: prompt.firstTimestamp, model: prompt.model, prompt: prompt.prompt, turnCount: prompt.turnCount,
+        inputTokens: prompt.inputTokens, cachedInputTokens: prompt.cachedInputTokens, outputTokens: prompt.outputTokens,
+        reasoningOutputTokens: prompt.reasoningOutputTokens, totalTokens: prompt.totalTokens, maxTurnTokens: prompt.maxTurnTokens, tools: prompt.tools,
+      });
+    }
+    if (session.rateLimit) totals.latestRateLimit = session.rateLimit;
+  }
+
+  const dailyUsage = Object.values(dailyMap).filter((d) => d.date !== 'unknown').sort((a, b) => a.date.localeCompare(b.date));
+  const weekdayUsage = Object.values(weekdayMap)
+    .map((w) => ({ ...w, name: WEEKDAYS[w.weekday], avgTokens: w.sessions ? Math.round(w.totalTokens / w.sessions) : 0 }))
+    .sort((a, b) => a.weekday - b.weekday);
+  totals.avgTokensPerTurn = totals.totalTurns > 0 ? Math.round(totals.totalTokens / totals.totalTurns) : 0;
+  totals.avgTokensPerSession = totals.totalSessions > 0 ? Math.round(totals.totalTokens / totals.totalSessions) : 0;
+  totals.dateRange = dailyUsage.length ? { from: dailyUsage[0].date, to: dailyUsage[dailyUsage.length - 1].date } : null;
+
+  largestTurns.sort((a, b) => b.totalTokens - a.totalTokens);
+  topPrompts.sort((a, b) => b.totalTokens - a.totalTokens);
+
+  return {
+    source, capabilities,
+    sessions, dailyUsage, weekdayUsage,
+    modelBreakdown: Object.values(modelMap).sort((a, b) => b.totalTokens - a.totalTokens),
+    projectBreakdown: Object.values(projectMap).sort((a, b) => b.totalTokens - a.totalTokens),
+    toolBreakdown: Object.values(toolMap).sort((a, b) => b.count - a.count),
+    largestTurns: largestTurns.slice(0, 30),
+    topPrompts: topPrompts.slice(0, 50),
+    insights: generateInsights(sessions, totals, largestTurns, topPrompts, weekdayUsage, caps),
+    totals, warnings,
+  };
+}
+
+function emptyResult(source, capabilities, warnings) {
+  return {
+    source, capabilities,
+    sessions: [], dailyUsage: [], weekdayUsage: [], modelBreakdown: [], projectBreakdown: [], toolBreakdown: [],
+    largestTurns: [], topPrompts: [], insights: [],
+    totals: {
+      totalSessions: 0, totalTurns: 0, totalPrompts: 0, totalToolCalls: 0,
+      inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0,
+      totalCost: 0, avgTokensPerTurn: 0, avgTokensPerSession: 0, dateRange: null, latestRateLimit: null,
+    },
+    warnings,
+  };
+}
+
+module.exports = { buildResult, emptyResult, buildPromptBreakdown };

package/src/adapters/claude.js

@@ -0,0 +1,183 @@
+// Claude Code adapter — reads ~/.claude/projects/**/*.jsonl (assistant usage blocks).
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { expandHome, parseJSONLFile } = require('./shared');
+const { buildResult, emptyResult, buildPromptBreakdown } = require('./aggregate');
+
+const id = 'claude';
+const label = 'Claude Code';
+const mark = 'CC';
+const accent = '#cc785c';
+const capabilities = { cost: true, reasoning: false, rateLimit: false, cache: true, tools: true, contextWindow: false };
+
+// Anthropic API per-token pricing (estimate; subscription billing differs).
+const MODEL_PRICING = {
+  'opus-4.5': { input: 5 / 1e6, output: 25 / 1e6, cacheWrite: 6.25 / 1e6, cacheRead: 0.50 / 1e6 },
+  'opus-4.6': { input: 5 / 1e6, output: 25 / 1e6, cacheWrite: 6.25 / 1e6, cacheRead: 0.50 / 1e6 },
+  'opus-4.0': { input: 15 / 1e6, output: 75 / 1e6, cacheWrite: 18.75 / 1e6, cacheRead: 1.50 / 1e6 },
+  'opus-4.1': { input: 15 / 1e6, output: 75 / 1e6, cacheWrite: 18.75 / 1e6, cacheRead: 1.50 / 1e6 },
+  sonnet: { input: 3 / 1e6, output: 15 / 1e6, cacheWrite: 3.75 / 1e6, cacheRead: 0.30 / 1e6 },
+  'haiku-4.5': { input: 1 / 1e6, output: 5 / 1e6, cacheWrite: 1.25 / 1e6, cacheRead: 0.10 / 1e6 },
+  'haiku-3.5': { input: 0.80 / 1e6, output: 4 / 1e6, cacheWrite: 1.00 / 1e6, cacheRead: 0.08 / 1e6 },
+};
+const DEFAULT_PRICING = MODEL_PRICING.sonnet;
+function getPricing(model) {
+  if (!model) return DEFAULT_PRICING;
+  const m = model.toLowerCase();
+  if (m.includes('opus')) {
+    if (m.includes('4-6') || m.includes('4.6')) return MODEL_PRICING['opus-4.6'];
+    if (m.includes('4-5') || m.includes('4.5')) return MODEL_PRICING['opus-4.5'];
+    if (m.includes('4-1') || m.includes('4.1')) return MODEL_PRICING['opus-4.1'];
+    return MODEL_PRICING['opus-4.0'];
+  }
+  if (m.includes('sonnet')) return MODEL_PRICING.sonnet;
+  if (m.includes('haiku')) return m.includes('4-5') || m.includes('4.5') ? MODEL_PRICING['haiku-4.5'] : MODEL_PRICING['haiku-3.5'];
+  return DEFAULT_PRICING;
+}
+
+function home(options = {}) {
+  return expandHome(options.home || process.env.CLAUDE_HOME) || path.join(os.homedir(), '.claude');
+}
+function detect(options = {}) {
+  return fs.existsSync(path.join(home(options), 'projects'));
+}
+
+// Pair each user prompt with the assistant usage turns that follow it.
+function extractTurns(entries) {
+  const turns = [];
+  let pendingPrompt = null;
+  for (const entry of entries) {
+    if (entry.type === 'user' && entry.message?.role === 'user') {
+      if (entry.isMeta) continue;
+      const content = entry.message.content;
+      if (typeof content === 'string' && (content.startsWith('<local-command') || content.startsWith('<command-name'))) continue;
+      const text = typeof content === 'string'
+        ? content
+        : (Array.isArray(content) ? content.filter((b) => b.type === 'text').map((b) => b.text).join('\n').trim() : '');
+      pendingPrompt = text || null;
+    }
+    if (entry.type === 'assistant' && entry.message?.usage) {
+      const u = entry.message.usage;
+      const model = entry.message.model || 'unknown';
+      if (model === '<synthetic>') continue;
+      const pricing = getPricing(model);
+      const inputTokens = u.input_tokens || 0;
+      const cacheCreate = u.cache_creation_input_tokens || 0;
+      const cacheRead = u.cache_read_input_tokens || 0;
+      const outputTokens = u.output_tokens || 0;
+      // Treat all input flavors (fresh + cache write + cache read) as input volume,
+      // and cacheRead as the "cached" slice, to match the dashboard's token model.
+      const totalInput = inputTokens + cacheCreate + cacheRead;
+      const cost = inputTokens * pricing.input + cacheCreate * pricing.cacheWrite + cacheRead * pricing.cacheRead + outputTokens * pricing.output;
+      const tools = [];
+      if (Array.isArray(entry.message.content)) {
+        for (const b of entry.message.content) if (b.type === 'tool_use' && b.name) tools.push(b.name);
+      }
+      turns.push({
+        turnId: entry.uuid || `turn-${turns.length + 1}`,
+        timestamp: entry.timestamp,
+        prompt: pendingPrompt,
+        model,
+        inputTokens: totalInput,
+        cachedInputTokens: cacheRead,
+        outputTokens,
+        reasoningOutputTokens: 0,
+        totalTokens: totalInput + outputTokens,
+        contextWindow: null,
+        cost,
+        tools,
+      });
+    }
+  }
+  return turns;
+}
+
+function modelLabel(model) {
+  if (!model) return 'unknown';
+  const m = model.toLowerCase();
+  if (m.includes('opus')) return 'claude-opus';
+  if (m.includes('sonnet')) return 'claude-sonnet';
+  if (m.includes('haiku')) return 'claude-haiku';
+  return model;
+}
+
+async function parse(options = {}) {
+  const h = home(options);
+  const source = { id, label, mark, accent, home: h };
+  const projectsDir = path.join(h, 'projects');
+  if (!fs.existsSync(projectsDir)) return emptyResult(source, capabilities, [{ type: 'missing-dir', message: `Claude Code data not found at ${projectsDir}` }]);
+
+  // history.jsonl gives a friendlier first-prompt per session.
+  const historyPath = path.join(h, 'history.jsonl');
+  const historyEntries = fs.existsSync(historyPath) ? await parseJSONLFile(historyPath) : [];
+  const sessionFirstPrompt = {};
+  for (const e of historyEntries) {
+    if (e.sessionId && e.display && !sessionFirstPrompt[e.sessionId]) {
+      const d = e.display.trim();
+      if (d.startsWith('/') && d.length < 30) continue;
+      sessionFirstPrompt[e.sessionId] = d;
+    }
+  }
+
+  const warnings = [];
+  const sessions = [];
+  let projectDirs = [];
+  try { projectDirs = fs.readdirSync(projectsDir).filter((d) => { try { return fs.statSync(path.join(projectsDir, d)).isDirectory(); } catch { return false; } }); } catch { /* */ }
+
+  for (const projectDir of projectDirs) {
+    const dir = path.join(projectsDir, projectDir);
+    let files;
+    try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')); } catch { continue; }
+    for (const file of files) {
+      const filePath = path.join(dir, file);
+      const sessionId = path.basename(file, '.jsonl');
+      let entries;
+      try { entries = await parseJSONLFile(filePath); } catch { continue; }
+      if (!entries.length) continue;
+      const rawTurns = extractTurns(entries);
+      if (!rawTurns.length) continue;
+
+      // Normalize project label from the encoded dir name (cwd path with '-' separators).
+      const cwd = entries.find((e) => e.cwd)?.cwd || projectDir.replace(/^-/, '/').replace(/-/g, '/');
+      const project = cwd.split('/').filter(Boolean).slice(-2).join('/') || projectDir;
+
+      const toolCounts = {};
+      const toolEvents = [];
+      for (const t of rawTurns) for (const name of t.tools || []) {
+        toolCounts[name] = (toolCounts[name] || 0) + 1;
+        toolEvents.push({ name, prompt: t.prompt, timestamp: t.timestamp });
+      }
+
+      const firstTs = entries.find((e) => e.timestamp)?.timestamp || null;
+      const lastTs = entries.slice().reverse().find((e) => e.timestamp)?.timestamp || firstTs;
+      const date = firstTs ? firstTs.split('T')[0] : 'unknown';
+      const modelCounts = {};
+      for (const t of rawTurns) modelCounts[t.model] = (modelCounts[t.model] || 0) + 1;
+      const primaryModel = modelLabel(Object.entries(modelCounts).sort((a, b) => b[1] - a[1])[0]?.[0]);
+      const title = sessionFirstPrompt[sessionId] || rawTurns.find((t) => t.prompt)?.prompt || '(no prompt)';
+      const promptBreakdown = buildPromptBreakdown(rawTurns, toolEvents, title);
+
+      sessions.push({
+        sessionId, filePath, archived: false,
+        title: String(title).slice(0, 240), project, cwd, date,
+        timestamp: firstTs, updatedTimestamp: lastTs, model: primaryModel,
+        turnCount: rawTurns.length, agentMessages: rawTurns.length,
+        toolCount: Object.values(toolCounts).reduce((s, n) => s + n, 0), toolCounts,
+        promptCount: promptBreakdown.length, promptBreakdown,
+        turns: rawTurns.map((t) => ({ ...t, model: modelLabel(t.model) })),
+        inputTokens: rawTurns.reduce((s, t) => s + t.inputTokens, 0),
+        cachedInputTokens: rawTurns.reduce((s, t) => s + t.cachedInputTokens, 0),
+        outputTokens: rawTurns.reduce((s, t) => s + t.outputTokens, 0),
+        reasoningOutputTokens: 0,
+        totalTokens: rawTurns.reduce((s, t) => s + t.totalTokens, 0),
+        cost: rawTurns.reduce((s, t) => s + (t.cost || 0), 0),
+        contextWindow: null, peakInputTokens: 0, peakTurnTokens: 0, rateLimit: null,
+      });
+    }
+  }
+  if (!sessions.length) return emptyResult(source, capabilities, [{ type: 'no-sessions', message: 'No Claude Code sessions with usage found.' }]);
+  return buildResult(sessions, source, capabilities, warnings);
+}
+
+module.exports = { id, label, mark, accent, capabilities, home, detect, parse };