claude-agent-ledger 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to `claude-agent-ledger` will be documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] — 2026-04-22
+
+### Added
+- `--by project` — group spend by Claude Code project directory.
+  Decodes `~/.claude/projects/-Users-xiangjie-clawbot` → `~/clawbot` so you can
+  see which project is burning budget.
+- `--by session` — group by session ID. Surfaces the single most expensive
+  conversations (useful for hunting the one that went sideways).
+- Summary dashboard now shows:
+  - `Projects` count
+  - `Top project` line
+  - `Project mix` block — top 3 projects with $ and %
+- `decodeProjectId()` exported for reuse. Special-cases the `~/` home prefix,
+  falls back to slash-joined path for other roots.
+- Row label column now auto-widens up to 40 chars for project paths.
+
+### Changed
+- `formatTable` takes an optional `groupName` arg so the header column matches
+  the group (e.g. "project", "session").
+
+## [0.3.0] — 2026-04-22
+
+### Added
+- `--summary` flag — single-screen dashboard with shadow cost, top subagent /
+  model / day, cache reuse ratio, and **leverage vs $200/mo Max plan**.
+  This is the killer view for "why install over /cost?"
+- Auto-derived insights footer on the default table:
+  - Top contributor with %
+  - 1h cache spend call-out (when ≥5% of total)
+  - Cache reuse ratio (read/write) with verdict
+  - Monthly $ equivalent + leverage vs Max plan
+- Daily-mode insights: peak day, avg/day, peak/trough variance
+
+### Changed
+- `--by day` polish:
+  - Bar fixed to 40-char width so session counts align in their own column
+  - Brighter cyan (`\x1b[96m`) bar character
+  - Total row separated by horizontal rule, properly aligned
+- Header line now shows period + total + sessions + group count at a glance:
+  `agent-ledger week  2026-04-15 → 2026-04-22  ·  $13,356.27 shadow  ·  217 sessions  ·  7 agents`
+
 ## [0.2.0] — 2026-04-21
 
 ### Added

package/README.md

@@ -27,15 +27,61 @@ If you run **seven** subagents daily (reliability, release, review, iOS factory,
 npm install -g claude-agent-ledger
 # or: bun install -g claude-agent-ledger
 
-agent-ledger today                 # today's spend, by subagent
-agent-ledger week --by model       # last 7 days, by Claude model
-agent-ledger week --by day         # daily bar chart
+agent-ledger week --summary        # the dashboard (start here)
+agent-ledger week --by model       # which Claude model burned the budget
+agent-ledger week --by project     # which project ate your tokens
+agent-ledger week --by session     # which single sessions went sideways
+agent-ledger week --by day         # daily bar chart with peak/avg/variance
 agent-ledger month --md > report.md
 ```
 
 No server. No account. No data leaves your machine.
 
-## Example output (real)
+## Why this and not `/cost`?
+
+Claude Code's built-in `/cost` shows the **current session** cost. That's it.
+
+`claude-agent-ledger` answers questions `/cost` can't:
+
+- Which of my **10+ subagents** burned the budget? (default)
+- Which **Claude model** burned the budget — Opus vs Sonnet vs Haiku? (`--by model`)
+- Which **project** in `~/.claude/projects/` ate the tokens? (`--by project`)
+- Which **single sessions** went sideways and burned $X? (`--by session`)
+- Which **day** of last week was the expensive one? (`--by day`)
+- What would my Claude Max usage have cost on **pay-as-you-go**? (the "shadow cost" framing)
+- Is my **cache reuse ratio** healthy? (auto-derived insight)
+- What's the **leverage** I'm getting from my $200/mo subscription? (e.g. 250×)
+
+Run `agent-ledger week --summary` once and decide.
+
+## Example output (real, from the author's machine)
+
+### `--summary` (the dashboard)
+
+```
+agent-ledger week summary  2026-04-15 → 2026-04-22
+
+  Shadow cost           $13,450.05
+  Sessions              219
+  Projects              9
+  Plan reference        $200/mo (Max)
+  Multiplier            252× vs Max plan
+
+  Top subagent          (main)            $12,787.19 (95%)
+  Top model             claude-opus-4-7   $7,278.87 (54%)
+  Top project           ~/clawbot         $6,657.93 (50%)
+  Peak day              2026-04-15        $3,679.16
+
+  Project mix
+    ~/clawbot                      $6,657.93 (50%)
+    ~/clawbot-work                 $4,433.32 (33%)
+    ~/ZStack-zstack-workspace      $1,890.02 (14%)
+
+  Cache 1h writes       119.65M tokens · $3589.46
+  Cache reads           5.59B tokens · $8236.15
+  Cache reuse           38× reads/writes
+  Server tools          none
+```
 
 ### Default — by subagent
 
@@ -132,7 +178,8 @@ If Anthropic's actual rate differs (or web_fetch has its own price), open an iss
 
 | Flag | What it does |
 |---|---|
-| `--by <subagent\|model\|day>` | Group rows. Default: `subagent`. `day` renders as ASCII bar chart. |
+| `--summary` | One-screen dashboard with all the headline numbers |
+| `--by <subagent\|model\|day\|project\|session>` | Group rows. Default: `subagent`. `day` renders as ASCII bar chart. |
 | `--md` | Markdown table output (good for committing or sharing) |
 | `--json` | Raw JSON output (pipe into jq) |
 | `--plan pro\|max` | Hide dollar columns; show token utilization only |

package/bin/agent-ledger.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { aggregate, type GroupKey } from '../src/aggregator.ts';
-import { formatMarkdown, formatTable, formatTrend } from '../src/format.ts';
+import { formatMarkdown, formatSummary, formatTable, formatTrend } from '../src/format.ts';
 import { parseAll } from '../src/parser.ts';
-import type { LedgerReport } from '../src/types.ts';
+import type { LedgerReport, SessionTurn } from '../src/types.ts';
 
 type Period = 'today' | 'week' | 'month';
 type Plan = 'payg' | 'pro' | 'max';
@@ -13,6 +13,7 @@ interface Args {
 	json: boolean;
 	plan: Plan;
 	by: GroupKey;
+	summary: boolean;
 }
 
 function periodRange(period: Period): { from: Date; to: Date } {
@@ -34,24 +35,29 @@ function usage(): never {
 	console.error(`Usage: agent-ledger <today|week|month> [flags]
 
 Flags:
-  --by <subagent|model|day>   Group rows by subagent (default), model, or day.
-                              "day" renders as a daily trend bar chart.
-  --md                        Emit Markdown table (good for sharing / commits)
-  --json                      Emit raw JSON (for piping into other tools)
+  --summary                   One-screen dashboard: total + top subagent + top
+                              model + peak day + cache reuse + leverage vs $200/mo plan
+  --by <subagent|model|day|project|session>
+                              Group rows by:
+                                subagent  (default) — agent attribution
+                                model     — opus vs sonnet vs haiku
+                                day       — daily ASCII bar chart
+                                project   — by Claude Code project (decoded path)
+                                session   — by session id (top spenders)
+  --md                        Markdown table output (good for sharing / commits)
+  --json                      Raw JSON output (for piping into jq)
   --plan pro|max              Suppress dollar columns (token utilization only)
-                              Default is pay-as-you-go: shows shadow cost in $.
 
 Environment:
   NO_COLOR=1                  Disable ANSI colors
-  FORCE_COLOR=1               Force colors even when piping
+  FORCE_COLOR=1               Force colors when piping
 
 Examples:
-  agent-ledger today
-  agent-ledger week --by model
+  agent-ledger week --summary           # the dashboard
   agent-ledger week --by day            # daily bar chart
-  agent-ledger week --md > week.md
-  agent-ledger month --json | jq '.total.cost.totalCost'
-  agent-ledger week --plan max
+  agent-ledger week --by model          # which Claude model burned the budget
+  agent-ledger month --md > month.md
+  agent-ledger week --json | jq '.total.cost.totalCost'
 `);
 	process.exit(1);
 }
@@ -74,7 +80,13 @@ function parseArgs(argv: string[]): Args {
 			}
 		} else if (flag === '--by') {
 			const next = rest[i + 1];
-			if (next === 'subagent' || next === 'model' || next === 'day') {
+			if (
+				next === 'subagent' ||
+				next === 'model' ||
+				next === 'day' ||
+				next === 'project' ||
+				next === 'session'
+			) {
 				by = next;
 				i++;
 			} else {
@@ -88,6 +100,7 @@ function parseArgs(argv: string[]): Args {
 		json: rest.includes('--json'),
 		plan,
 		by,
+		summary: rest.includes('--summary'),
 	};
 }
 
@@ -109,10 +122,34 @@ function planMask(report: LedgerReport, plan: Plan): LedgerReport {
 	};
 }
 
+// Materialize once so --summary can re-aggregate by 3 dimensions cheaply.
+async function collectTurns(opts: { from: Date; to: Date }): Promise<SessionTurn[]> {
+	const out: SessionTurn[] = [];
+	for await (const t of parseAll(opts)) out.push(t);
+	return out;
+}
+
+async function* iterTurns(turns: SessionTurn[]): AsyncGenerator<SessionTurn> {
+	for (const t of turns) yield t;
+}
+
 async function main(): Promise<void> {
 	const args = parseArgs(process.argv.slice(2));
 	const { from, to } = periodRange(args.period);
-	let report = await aggregate(parseAll({ from, to }), from, to, args.by);
+	const turns = await collectTurns({ from, to });
+
+	if (args.summary) {
+		const [bySub, byMod, byDay, byProj] = await Promise.all([
+			aggregate(iterTurns(turns), from, to, 'subagent'),
+			aggregate(iterTurns(turns), from, to, 'model'),
+			aggregate(iterTurns(turns), from, to, 'day'),
+			aggregate(iterTurns(turns), from, to, 'project'),
+		]);
+		console.log(formatSummary(bySub, byMod, byDay, byProj, args.period));
+		return;
+	}
+
+	let report = await aggregate(iterTurns(turns), from, to, args.by);
 	report = planMask(report, args.plan);
 
 	let output: string;
@@ -123,7 +160,7 @@ async function main(): Promise<void> {
 	} else if (args.by === 'day') {
 		output = formatTrend(report, args.period);
 	} else {
-		output = formatTable(report, args.period);
+		output = formatTable(report, args.period, args.by);
 	}
 	console.log(output);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-agent-ledger",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "See exactly where your Claude Code budget goes — per subagent, per task.",
   "type": "module",
   "bin": {

package/src/aggregator.ts

@@ -3,8 +3,26 @@ import type { AggregatedRow, LedgerReport, SessionTurn } from './types.ts';
 
 const MAIN_AGENT_LABEL = '(main)';
 const UNKNOWN_MODEL_LABEL = '(no-model)';
-
-export type GroupKey = 'subagent' | 'model' | 'day';
+const UNKNOWN_PROJECT_LABEL = '(no-project)';
+
+export type GroupKey = 'subagent' | 'model' | 'day' | 'project' | 'session';
+
+// Decode Claude Code's project directory name to something readable.
+// Encoding rule: absolute path with `/` replaced by `-` (leading `-` for root).
+//   "-Users-xiangjie-clawbot"             → "~/clawbot"
+//   "-Users-xiangjie-newlive-agent-ledger" → "~/newlive/agent-ledger"  (best-effort; ambiguous on dirs containing '-')
+// We special-case the "$HOME" prefix (`-Users-<user>-`) to render `~` and skip the rest of the
+// "-" → "/" conversion, since that's the only place we can be sure of segment boundaries.
+export function decodeProjectId(encoded: string): string {
+	if (!encoded.startsWith('-')) return encoded;
+	const parts = encoded.slice(1).split('-'); // drop leading '-'
+	// Match common $HOME pattern: ['Users', '<user>', ...rest]
+	if (parts.length >= 3 && parts[0] === 'Users') {
+		return '~/' + parts.slice(2).join('-');
+	}
+	// Fallback: just convert all - to /
+	return '/' + parts.join('/');
+}
 
 function emptyRow(label: string): AggregatedRow {
 	return {
@@ -44,6 +62,8 @@ function splitCache(turn: SessionTurn): { fiveMin: number; oneHour: number } {
 function keyOf(turn: SessionTurn, group: GroupKey): string {
 	if (group === 'model') return turn.model ?? UNKNOWN_MODEL_LABEL;
 	if (group === 'day') return turn.timestamp.slice(0, 10);
+	if (group === 'project') return decodeProjectId(turn.projectId ?? UNKNOWN_PROJECT_LABEL);
+	if (group === 'session') return turn.sessionId.slice(0, 8);
 	return turn.subagentType ?? MAIN_AGENT_LABEL;
 }
 

package/src/format.ts

@@ -1,6 +1,16 @@
 import type { AggregatedRow, LedgerReport } from './types.ts';
 
 const PAD_LABEL = 22;
+const PAD_LABEL_WIDE = 40; // for project paths
+const BAR_WIDTH = 40;
+const PLAN_MAX_PRICE = 200; // monthly USD reference for shadow-cost leverage
+
+// Detect when we should give labels more room (project paths can be long).
+function widestLabel(rows: { subagent: string }[]): number {
+	let w = 0;
+	for (const r of rows) if (r.subagent.length > w) w = r.subagent.length;
+	return w;
+}
 
 // Color helpers — TTY-aware, NO_COLOR-respecting (https://no-color.org/).
 const USE_COLOR = (() => {
@@ -14,6 +24,7 @@ const c = {
 	bold: USE_COLOR ? '\x1b[1m' : '',
 	green: USE_COLOR ? '\x1b[32m' : '',
 	cyan: USE_COLOR ? '\x1b[36m' : '',
+	cyanBright: USE_COLOR ? '\x1b[96m' : '',
 	yellow: USE_COLOR ? '\x1b[33m' : '',
 	red: USE_COLOR ? '\x1b[31m' : '',
 	magenta: USE_COLOR ? '\x1b[35m' : '',
@@ -22,6 +33,7 @@ const c = {
 };
 
 function fmtTokens(n: number): string {
+	if (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(2)}B`;
 	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
 	if (n >= 1_000) return `${(n / 1_000).toFixed(0)}K`;
 	return String(n);
@@ -31,6 +43,10 @@ function fmtUsd(n: number): string {
 	return `$${n.toFixed(2)}`;
 }
 
+function fmtUsdComma(n: number): string {
+	return `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
 function colorCost(n: number, padded: string): string {
 	if (!USE_COLOR) return padded;
 	if (n >= 1000) return `${c.bold}${c.red}${padded}${c.reset}`;
@@ -39,8 +55,13 @@ function colorCost(n: number, padded: string): string {
 	return `${c.dim}${padded}${c.reset}`;
 }
 
-function formatRow(row: AggregatedRow, isTotal = false): string {
-	const labelText = row.subagent.padEnd(PAD_LABEL);
+function pct(part: number, whole: number): string {
+	if (whole === 0) return '0%';
+	return `${((part / whole) * 100).toFixed(0)}%`;
+}
+
+function formatRow(row: AggregatedRow, padWidth: number, isTotal = false): string {
+	const labelText = row.subagent.padEnd(padWidth);
 	const label = isTotal
 		? `${c.bold}${labelText}${c.reset}`
 		: `${c.cyan}${labelText}${c.reset}`;
@@ -54,14 +75,79 @@ function formatRow(row: AggregatedRow, isTotal = false): string {
 	return `  ${label}${sessions}  ${io}  ${c.dim}1h:${c.reset}${cached1h} ${c.dim}5m:${c.reset}${cached5m} ${c.dim}r:${c.reset}${cacheRead}  ${cost}`;
 }
 
-export function formatTable(report: LedgerReport, label: string): string {
-	const header =
-		`${c.bold}agent-ledger ${label}${c.reset} ${c.dim}·${c.reset} ` +
-		`${c.gray}${report.period.from.toISOString().slice(0, 10)} → ${report.period.to.toISOString().slice(0, 10)}${c.reset}`;
+// Auto-derived insights. The whole point of installing the tool over /cost.
+function deriveInsights(report: LedgerReport): string[] {
+	const lines: string[] = [];
+	const total = report.total.cost.totalCost;
+	if (total === 0) return lines;
+
+	// Top contributor with %
+	const top = report.rows[0];
+	if (top && top.cost.totalCost > 0) {
+		lines.push(
+			`  ${c.cyanBright}⚡${c.reset} top: ${c.cyan}${top.subagent}${c.reset} drives ${c.bold}${pct(top.cost.totalCost, total)}${c.reset} of spend  ${c.dim}(${fmtUsd(top.cost.totalCost)} of ${fmtUsd(total)})${c.reset}`,
+		);
+	}
+
+	// 1h cache call-out (if non-trivial)
+	const oneHourCost =
+		report.total.cost.cacheCreation1hCost ?? 0;
+	if (oneHourCost >= total * 0.05) {
+		lines.push(
+			`  ${c.yellow}💾${c.reset} 1h cache writes: ${fmtTokens(report.total.cacheCreation1hTokens)} tokens · ${fmtUsd(oneHourCost)} ${c.dim}(${pct(oneHourCost, total)} of total)${c.reset}`,
+		);
+	}
+
+	// Cache reuse ratio — read vs write
+	const writeTokens =
+		report.total.cacheCreation1hTokens + report.total.cacheCreation5mTokens;
+	if (writeTokens > 0) {
+		const ratio = report.total.cacheReadTokens / writeTokens;
+		const verdict =
+			ratio >= 20
+				? `${c.green}excellent reuse${c.reset}`
+				: ratio >= 5
+					? `${c.yellow}OK reuse${c.reset}`
+					: `${c.red}low reuse${c.reset}`;
+		lines.push(
+			`  ${c.cyanBright}📥${c.reset} cache reuse: ${fmtTokens(report.total.cacheReadTokens)} reads / ${fmtTokens(writeTokens)} writes = ${c.bold}${ratio.toFixed(0)}×${c.reset} ${c.dim}(${verdict}${c.dim})${c.reset}`,
+		);
+	}
+
+	// Plan leverage
+	const dayCount =
+		Math.max(
+			1,
+			Math.round(
+				(report.period.to.getTime() - report.period.from.getTime()) /
+					(1000 * 60 * 60 * 24),
+			),
+		);
+	const monthlyEquivalent = (total / dayCount) * 30;
+	const leverage = monthlyEquivalent / PLAN_MAX_PRICE;
+	if (leverage >= 1) {
+		lines.push(
+			`  ${c.magenta}💸${c.reset} ${fmtUsdComma(monthlyEquivalent)}/mo equivalent  ${c.dim}vs $${PLAN_MAX_PRICE}/mo plan = ${c.reset}${c.bold}${leverage.toFixed(0)}×${c.reset} ${c.dim}leverage${c.reset}`,
+		);
+	}
+
+	return lines;
+}
+
+export function formatTable(report: LedgerReport, label: string, groupName: string = 'subagent'): string {
+	const padWidth = Math.max(PAD_LABEL, Math.min(PAD_LABEL_WIDE, widestLabel(report.rows) + 2));
+	const summaryLine =
+		`${c.gray}${report.period.from.toISOString().slice(0, 10)} → ${report.period.to.toISOString().slice(0, 10)}${c.reset}` +
+		`  ${c.dim}·${c.reset}  ` +
+		`${c.bold}${fmtUsdComma(report.total.cost.totalCost)}${c.reset} ${c.dim}shadow${c.reset}` +
+		`  ${c.dim}·${c.reset}  ${report.total.sessionCount} sessions` +
+		`  ${c.dim}·${c.reset}  ${report.rows.length} ${groupName}s`;
+
+	const header = `${c.bold}agent-ledger ${label}${c.reset}  ${summaryLine}`;
 
 	const colsRaw =
 		'  ' +
-		'subagent'.padEnd(PAD_LABEL) +
+		groupName.padEnd(padWidth) +
 		'sess'.padStart(4) +
 		'  ' +
 		'tokens(in/out)'.padStart(18) +
@@ -71,7 +157,7 @@ export function formatTable(report: LedgerReport, label: string): string {
 		'cost'.padStart(9);
 	const cols = `${c.gray}${colsRaw}${c.reset}`;
 
-	const sepRaw = '  ' + '─'.repeat(PAD_LABEL + 4 + 2 + 18 + 2 + 32 + 2 + 9);
+	const sepRaw = '  ' + '─'.repeat(padWidth + 4 + 2 + 18 + 2 + 32 + 2 + 9);
 	const sep = `${c.gray}${sepRaw}${c.reset}`;
 
 	const lines = [
@@ -79,9 +165,9 @@ export function formatTable(report: LedgerReport, label: string): string {
 		'',
 		cols,
 		sep,
-		...report.rows.map((r) => formatRow(r)),
+		...report.rows.map((r) => formatRow(r, padWidth)),
 		sep,
-		formatRow({ ...report.total, subagent: 'total' }, true),
+		formatRow({ ...report.total, subagent: 'total' }, padWidth, true),
 	];
 
 	// Server tool footer (only when present, since most rows have 0)
@@ -95,35 +181,156 @@ export function formatTable(report: LedgerReport, label: string): string {
 		);
 	}
 
+	// Insights
+	const insights = deriveInsights(report);
+	if (insights.length) {
+		lines.push('');
+		lines.push(...insights);
+	}
+
 	return lines.join('\n');
 }
 
-// Daily trend chart: vertical-ish ASCII bars per day.
+// Daily trend chart with fixed-width bars.
 export function formatTrend(report: LedgerReport, label: string): string {
 	const max = report.rows.reduce((m, r) => Math.max(m, r.cost.totalCost), 0);
-	const barWidth = 36;
 
-	const header =
-		`${c.bold}agent-ledger ${label} (daily)${c.reset} ${c.dim}·${c.reset} ` +
-		`${c.gray}${report.period.from.toISOString().slice(0, 10)} → ${report.period.to.toISOString().slice(0, 10)}${c.reset}`;
+	const summaryLine =
+		`${c.gray}${report.period.from.toISOString().slice(0, 10)} → ${report.period.to.toISOString().slice(0, 10)}${c.reset}` +
+		`  ${c.dim}·${c.reset}  ` +
+		`${c.bold}${fmtUsdComma(report.total.cost.totalCost)}${c.reset} ${c.dim}shadow${c.reset}` +
+		`  ${c.dim}·${c.reset}  ${report.total.sessionCount} sessions across ${report.rows.length} days`;
+
+	const header = `${c.bold}agent-ledger ${label} (daily)${c.reset}  ${summaryLine}`;
 
 	const lines = [header, ''];
 	for (const row of report.rows) {
-		const bars = Math.round((row.cost.totalCost / Math.max(max, 0.01)) * barWidth);
-		const bar =
-			(USE_COLOR ? c.cyan : '') + '█'.repeat(bars) + (USE_COLOR ? c.reset : '');
+		const bars = Math.round((row.cost.totalCost / Math.max(max, 0.01)) * BAR_WIDTH);
+		const barFilled = '█'.repeat(bars);
+		const barPadding = ' '.repeat(BAR_WIDTH - bars);
+		const bar = `${USE_COLOR ? c.cyanBright : ''}${barFilled}${USE_COLOR ? c.reset : ''}${barPadding}`;
 		const dateLabel = `${c.gray}${row.subagent}${c.reset}`;
-		const cost = colorCost(row.cost.totalCost, fmtUsd(row.cost.totalCost).padStart(9));
-		const sessions = `${c.gray}(${row.sessionCount} sess)${c.reset}`;
-		lines.push(`  ${dateLabel}  ${cost}  ${bar} ${sessions}`);
+		const cost = colorCost(row.cost.totalCost, fmtUsd(row.cost.totalCost).padStart(10));
+		const sessionsRaw = `${row.sessionCount} sess`;
+		const sessions = `${c.dim}·  ${sessionsRaw}${c.reset}`;
+		lines.push(`  ${dateLabel}  ${cost}  ${bar}  ${sessions}`);
 	}
-	lines.push('');
+	const sepWidth = 12 + 2 + 10 + 2 + BAR_WIDTH + 2 + 10;
+	lines.push(`  ${c.gray}${'─'.repeat(sepWidth)}${c.reset}`);
+	const totalLabel = `${c.bold}total${c.reset}`.padEnd(12 + (USE_COLOR ? c.bold.length + c.reset.length : 0));
+	const totalCost = colorCost(
+		report.total.cost.totalCost,
+		fmtUsd(report.total.cost.totalCost).padStart(10),
+	);
+	lines.push(`  ${totalLabel}       ${totalCost}`);
+
+	// Daily-mode insights
+	const insights = deriveDailyInsights(report);
+	if (insights.length) {
+		lines.push('');
+		lines.push(...insights);
+	}
+
+	return lines.join('\n');
+}
+
+function deriveDailyInsights(report: LedgerReport): string[] {
+	if (report.rows.length === 0) return [];
+	const lines: string[] = [];
+	const peak = [...report.rows].sort((a, b) => b.cost.totalCost - a.cost.totalCost)[0]!;
+	const trough = [...report.rows]
+		.filter((r) => r.cost.totalCost > 0)
+		.sort((a, b) => a.cost.totalCost - b.cost.totalCost)[0];
+	const avg = report.total.cost.totalCost / report.rows.length;
+
 	lines.push(
-		`  ${c.bold}total${c.reset.padEnd(PAD_LABEL - 5)}${' '.repeat(2)}${colorCost(
-			report.total.cost.totalCost,
-			fmtUsd(report.total.cost.totalCost).padStart(9),
-		)}`,
+		`  ${c.cyanBright}⚡${c.reset} peak: ${c.cyan}${peak.subagent}${c.reset} ${c.bold}${fmtUsd(peak.cost.totalCost)}${c.reset} ${c.dim}(${peak.sessionCount} sess)${c.reset}`,
 	);
+	lines.push(
+		`  ${c.gray}📊${c.reset} avg/day: ${fmtUsd(avg)}`,
+	);
+	if (trough && trough.cost.totalCost > 0) {
+		const variance = peak.cost.totalCost / trough.cost.totalCost;
+		if (variance >= 3) {
+			lines.push(
+				`  ${c.yellow}🌪${c.reset} variance: ${c.bold}${variance.toFixed(0)}×${c.reset} ${c.dim}between peak (${peak.subagent}) and trough (${trough.subagent})${c.reset}`,
+			);
+		}
+	}
+	return lines;
+}
+
+// Single-screen dashboard. Aggregates the same period across 4 dimensions.
+export function formatSummary(
+	bySubagent: LedgerReport,
+	byModel: LedgerReport,
+	byDay: LedgerReport,
+	byProject: LedgerReport,
+	label: string,
+): string {
+	const total = bySubagent.total.cost.totalCost;
+	const dayCount = Math.max(1, byDay.rows.length);
+	const monthlyEquivalent = (total / dayCount) * 30;
+	const leverage = monthlyEquivalent / PLAN_MAX_PRICE;
+
+	const top = (rows: AggregatedRow[]) => rows[0];
+	const tSub = top(bySubagent.rows);
+	const tMod = top(byModel.rows);
+	const tDay = [...byDay.rows].sort((a, b) => b.cost.totalCost - a.cost.totalCost)[0];
+	const tProj = top(byProject.rows);
+	// Top 3 projects for quick distribution view
+	const topProjects = byProject.rows.slice(0, 3);
+
+	const k = (label: string, value: string) =>
+		`  ${c.gray}${label.padEnd(20)}${c.reset}  ${value}`;
+	const dollar = (n: number) => `${c.bold}${fmtUsdComma(n)}${c.reset}`;
+
+	const writeTokens =
+		bySubagent.total.cacheCreation1hTokens + bySubagent.total.cacheCreation5mTokens;
+	const reuseRatio = writeTokens > 0 ? bySubagent.total.cacheReadTokens / writeTokens : 0;
+
+	const lines = [
+		`${c.bold}agent-ledger ${label} summary${c.reset}  ${c.gray}${bySubagent.period.from.toISOString().slice(0, 10)} → ${bySubagent.period.to.toISOString().slice(0, 10)}${c.reset}`,
+		'',
+		k('Shadow cost', dollar(total)),
+		k('Sessions', `${bySubagent.total.sessionCount}`),
+		k('Projects', `${byProject.rows.length}`),
+		k('Plan reference', `$${PLAN_MAX_PRICE}/mo (Max)`),
+		k('Multiplier', `${c.bold}${leverage.toFixed(0)}×${c.reset} ${c.dim}vs Max plan${c.reset}`),
+		'',
+		k('Top subagent', tSub ? `${c.cyan}${tSub.subagent}${c.reset}  ${dollar(tSub.cost.totalCost)} ${c.dim}(${pct(tSub.cost.totalCost, total)})${c.reset}` : '—'),
+		k('Top model', tMod ? `${c.cyan}${tMod.subagent}${c.reset}  ${dollar(tMod.cost.totalCost)} ${c.dim}(${pct(tMod.cost.totalCost, total)})${c.reset}` : '—'),
+		k('Top project', tProj ? `${c.cyan}${tProj.subagent}${c.reset}  ${dollar(tProj.cost.totalCost)} ${c.dim}(${pct(tProj.cost.totalCost, total)})${c.reset}` : '—'),
+		k('Peak day', tDay ? `${c.cyan}${tDay.subagent}${c.reset}  ${dollar(tDay.cost.totalCost)}` : '—'),
+	];
+
+	// If multiple projects, list top 3 as a small breakdown
+	if (topProjects.length > 1) {
+		lines.push('');
+		lines.push(`  ${c.gray}Project mix${c.reset}`);
+		for (const p of topProjects) {
+			lines.push(
+				`    ${c.cyan}${p.subagent.padEnd(36)}${c.reset} ${dollar(p.cost.totalCost)} ${c.dim}(${pct(p.cost.totalCost, total)})${c.reset}`,
+			);
+		}
+	}
+
+	lines.push('');
+	lines.push(k('Cache 1h writes', `${fmtTokens(bySubagent.total.cacheCreation1hTokens)} tokens · ${fmtUsd(bySubagent.total.cost.cacheCreation1hCost)}`));
+	lines.push(k('Cache reads', `${fmtTokens(bySubagent.total.cacheReadTokens)} tokens · ${fmtUsd(bySubagent.total.cost.cacheReadCost)}`));
+	lines.push(k(
+		'Cache reuse',
+		writeTokens > 0
+			? `${c.bold}${reuseRatio.toFixed(0)}×${c.reset} ${c.dim}reads/writes${c.reset}`
+			: 'n/a',
+	));
+	lines.push(k(
+		'Server tools',
+		bySubagent.total.webSearchRequests + bySubagent.total.webFetchRequests > 0
+			? `web_search ×${bySubagent.total.webSearchRequests}, web_fetch ×${bySubagent.total.webFetchRequests} (${fmtUsd(bySubagent.total.cost.serverToolUseCost)})`
+			: `${c.dim}none${c.reset}`,
+	));
+
 	return lines.join('\n');
 }
 

package/src/parser.ts

@@ -13,6 +13,7 @@ export interface ParseOptions {
 
 interface LogFile {
 	path: string;
+	projectId: string;
 	subagentType: string | undefined;
 }
 
@@ -34,11 +35,11 @@ export async function* findSessionLogs(
 		return;
 	}
 	for (const project of projects) {
-		yield* walkForJsonl(join(projectsDir, project));
+		yield* walkForJsonl(join(projectsDir, project), project);
 	}
 }
 
-async function* walkForJsonl(dir: string): AsyncGenerator<LogFile> {
+async function* walkForJsonl(dir: string, projectId: string): AsyncGenerator<LogFile> {
 	let entries: string[] = [];
 	try {
 		entries = await readdir(dir);
@@ -55,11 +56,11 @@ async function* walkForJsonl(dir: string): AsyncGenerator<LogFile> {
 			continue;
 		}
 		if (isDir) {
-			yield* walkForJsonl(full);
+			yield* walkForJsonl(full, projectId);
 			continue;
 		}
 		if (name.endsWith('.jsonl')) {
-			yield { path: full, subagentType: await resolveSubagentType(full) };
+			yield { path: full, projectId, subagentType: await resolveSubagentType(full) };
 		}
 	}
 }
@@ -81,6 +82,7 @@ async function resolveSubagentType(jsonlPath: string): Promise<string | undefine
 export async function* parseFile(
 	path: string,
 	subagentType?: string,
+	projectId?: string,
 ): AsyncGenerator<SessionTurn> {
 	const file = Bun.file(path);
 	const text = await file.text();
@@ -94,7 +96,7 @@ export async function* parseFile(
 		} catch {
 			continue;
 		}
-		yield extractTurn(obj, sessionId, subagentType);
+		yield extractTurn(obj, sessionId, subagentType, projectId);
 	}
 }
 
@@ -102,6 +104,7 @@ function extractTurn(
 	obj: Record<string, unknown>,
 	sessionId: string,
 	subagentType: string | undefined,
+	projectId: string | undefined,
 ): SessionTurn {
 	const msg = (obj.message ?? {}) as Record<string, unknown>;
 	const usage = (msg.usage ?? undefined) as TokenUsage | undefined;
@@ -109,11 +112,13 @@ function extractTurn(
 	// If the raw turn carries its own subagentType (our fixture format), prefer it;
 	// otherwise fall back to the directory-derived one.
 	const perTurnSubagent = ((obj.subagentType as string) ?? undefined) || undefined;
+	const perTurnProject = ((obj.projectId as string) ?? undefined) || undefined;
 
 	return {
 		type: ((obj.type as string) ?? 'assistant') as SessionTurn['type'],
 		timestamp: (obj.timestamp as string) ?? new Date().toISOString(),
 		sessionId,
+		projectId: perTurnProject ?? projectId,
 		subagentType: perTurnSubagent ?? subagentType,
 		model,
 		usage,
@@ -125,7 +130,7 @@ function extractTurn(
 export async function* parseAll(opts: ParseOptions = {}): AsyncGenerator<SessionTurn> {
 	const dir = opts.projectsDir ?? CLAUDE_PROJECTS_DIR;
 	for await (const file of findSessionLogs(dir)) {
-		for await (const turn of parseFile(file.path, file.subagentType)) {
+		for await (const turn of parseFile(file.path, file.subagentType, file.projectId)) {
 			if (opts.from && new Date(turn.timestamp) < opts.from) continue;
 			if (opts.to && new Date(turn.timestamp) > opts.to) continue;
 			yield turn;

package/src/types.ts

@@ -32,6 +32,7 @@ export interface SessionTurn {
 	type: TurnType;
 	timestamp: string;
 	sessionId: string;
+	projectId?: string | undefined;
 	subagentType?: string | undefined;
 	model?: ModelId | undefined;
 	usage?: TokenUsage | undefined;