claude-agent-ledger 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.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,49 @@ 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 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? (`--by model` / default)
+- 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,356.27
+  Sessions              217
+  Plan reference        $200/mo (Max)
+  Multiplier            250× vs Max plan
+
+  Top subagent          (main)            $12,701.19 (95%)
+  Top model             claude-opus-4-7   $7,184.45 (54%)
+  Peak day              2026-04-15        $3,679.80
+
+  Cache 1h writes       119.45M tokens · $3583.42
+  Cache reads           5.54B tokens · $8162.93
+  Cache reuse           38× reads/writes
+  Server tools          none
+```
 
 ### Default — by subagent
 

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,24 @@ 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>   Group rows by subagent (default), model, or day
+                              "day" renders as a daily ASCII bar chart
+  --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);
 }
@@ -88,6 +89,7 @@ function parseArgs(argv: string[]): Args {
 		json: rest.includes('--json'),
 		plan,
 		by,
+		summary: rest.includes('--summary'),
 	};
 }
 
@@ -109,10 +111,33 @@ 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] = await Promise.all([
+			aggregate(iterTurns(turns), from, to, 'subagent'),
+			aggregate(iterTurns(turns), from, to, 'model'),
+			aggregate(iterTurns(turns), from, to, 'day'),
+		]);
+		console.log(formatSummary(bySub, byMod, byDay, args.period));
+		return;
+	}
+
+	let report = await aggregate(iterTurns(turns), from, to, args.by);
 	report = planMask(report, args.plan);
 
 	let output: string;

package/package.json

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

package/src/format.ts

@@ -1,6 +1,8 @@
 import type { AggregatedRow, LedgerReport } from './types.ts';
 
 const PAD_LABEL = 22;
+const BAR_WIDTH = 40;
+const PLAN_MAX_PRICE = 200; // monthly USD reference for shadow-cost leverage
 
 // Color helpers — TTY-aware, NO_COLOR-respecting (https://no-color.org/).
 const USE_COLOR = (() => {
@@ -14,6 +16,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 +25,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 +35,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,6 +47,11 @@ function colorCost(n: number, padded: string): string {
 	return `${c.dim}${padded}${c.reset}`;
 }
 
+function pct(part: number, whole: number): string {
+	if (whole === 0) return '0%';
+	return `${((part / whole) * 100).toFixed(0)}%`;
+}
+
 function formatRow(row: AggregatedRow, isTotal = false): string {
 	const labelText = row.subagent.padEnd(PAD_LABEL);
 	const label = isTotal
@@ -54,10 +67,74 @@ 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}`;
 }
 
+// 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): 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}`;
+	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} ${label.includes('day') ? 'days' : label.includes('model') ? 'models' : 'agents'}`;
+
+	const header = `${c.bold}agent-ledger ${label}${c.reset}  ${summaryLine}`;
 
 	const colsRaw =
 		'  ' +
@@ -95,35 +172,137 @@ 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}`);
+	}
+	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);
 	}
-	lines.push('');
+
+	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.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.bold}total${c.reset.padEnd(PAD_LABEL - 5)}${' '.repeat(2)}${colorCost(
-			report.total.cost.totalCost,
-			fmtUsd(report.total.cost.totalCost).padStart(9),
-		)}`,
+		`  ${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 3 dimensions.
+export function formatSummary(
+	bySubagent: LedgerReport,
+	byModel: LedgerReport,
+	byDay: 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 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('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('Peak day', tDay ? `${c.cyan}${tDay.subagent}${c.reset}  ${dollar(tDay.cost.totalCost)}` : '—'),
+		'',
+		k('Cache 1h writes', `${fmtTokens(bySubagent.total.cacheCreation1hTokens)} tokens · ${fmtUsd(bySubagent.total.cost.cacheCreation1hCost)}`),
+		k('Cache reads', `${fmtTokens(bySubagent.total.cacheReadTokens)} tokens · ${fmtUsd(bySubagent.total.cost.cacheReadCost)}`),
+		k(
+			'Cache reuse',
+			writeTokens > 0
+				? `${c.bold}${reuseRatio.toFixed(0)}×${c.reset} ${c.dim}reads/writes${c.reset}`
+				: 'n/a',
+		),
+		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');
 }