claude-agent-ledger 0.4.1 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,101 @@ 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.7.0] — 2026-04-23
+
+### Added — live tail + property tests
+
+- **`agent-ledger watch [intervalSec]`** — live polling mode. Re-aggregates
+  today's cost every N seconds (default 10), prints a delta meter:
+
+  ```
+  [14:46:34] today $3310.71  ↑ +$3310.71  · 9560 turns (Δ9560) · top: (main) $3167.95
+  [14:46:40] today $3310.71  · +$0.00  · 9560 turns (Δ0) · top: (main) $3167.95
+  ```
+
+  Answers "what's happening right now" without needing to re-run queries.
+  Ctrl-C to exit.
+
+- **Property tests via `fast-check`** — 7 new tests, 1400+ generated cases
+  covering:
+  - `costFor()` returns non-negative for any valid input
+  - `totalCost === sum(components)` exactly (ε < 1e-9)
+  - `cache_read ≤ fresh input` cost (90% discount holds)
+  - `cache_1h ≥ cache_5m` cost (1h tier always more expensive)
+  - `Aggregator.total === sum(rows)` for any random turn stream
+  - Non-assistant turns contribute 0 cost
+  - `SubagentGraph.totalCost ≥ selfCost` (children only add)
+
+  Total test count: 22 → 29 (kept all prior tests passing).
+
+## [0.6.0] — 2026-04-23
+
+### Added — `agent-ledger explain <sessionId>` (the LLM-native move)
+
+A new subcommand that answers **"why was this single session expensive?"**
+This is the question Helicone / Langfuse / OpenLLMetry physically cannot
+answer — they observe API calls, not Claude Code's prompts and tool calls.
+
+Two modes:
+
+- **Heuristic mode** (default, no API key needed) — analyzes the session
+  JSONL and prints:
+  - Subagent + total cost + turn count
+  - Model breakdown (which model dominated)
+  - Tool invocation count (Read/Bash/Grep/Edit/MCP — top 8)
+  - Top 3 most expensive turns with full token + tool breakdown
+  - Cache reuse ratio + verdict (`<5×` warning, `>20×` good)
+
+- **LLM mode** (set `ANTHROPIC_API_KEY`) — pipes the heuristic evidence into
+  Haiku 4.5 with a tightly-scoped prompt: "identify the SPECIFIC root cause
+  + ONE concrete action to cut this session's cost by 50%+." Costs about
+  $0.001/run. Cite turn numbers from the breakdown.
+
+```bash
+agent-ledger explain 63063a38
+agent-ledger explain b988bd89-803a-4c78    # full uuid or 8-char prefix both work
+```
+
+## [0.5.0] — 2026-04-23
+
+### Added — performance + production-readiness foundation
+
+- **Streaming JSONL parser** — replaces `await file.text()` (which OOM'd on
+  10GB+ logs). Now reads via `Bun.file().stream()` + `TextDecoder` line-by-line.
+  Memory profile is constant regardless of log size.
+- **Concurrent file walk** — `findSessionLogs` parallelizes per-project
+  `readdir` (`Promise.all`), and `parseAll` reads up to 8 JSONL files
+  concurrently. ~5–10× cold-start speedup on multi-project setups.
+- **Zero materialization** — bin no longer collects every turn into an array
+  before aggregating. Instead one parser stream fans out to N `Aggregator`
+  instances in parallel. Memory is now O(unique-keys) not O(turns).
+- **`--by tool`** — new GroupKey. Attribute spend per tool call (`Read`,
+  `Bash`, `Grep`, `Write`, MCP tool names). Answers "which tool is eating my
+  budget" — the most actionable lens for a Claude Code user.
+- **`--tree` (the MOAT)** — subagent-graph cost attribution. Walks the
+  parent→child orchestration tree and shows
+  `orchestrator → 3×researcher + 6×swift-dev = $312`. Helicone / Langfuse /
+  OpenLLMetry can't do this — they observe API calls, not Claude Code's
+  multi-agent runtime.
+- **`--budget <USD>`** — exit code `2` if total cost exceeds budget. Wire it
+  into your CI / shell startup / `pre-commit` to gate spend.
+- **`--json` works for `--summary`** — previously summary was text-only.
+  Now pipe-friendly: `agent-ledger week --summary --json | jq`.
+- **`--verbose`** — print parse stats (turns / elapsed) to stderr.
+
+### Changed
+
+- `Aggregator` is now a class (`add()` / `finalize()`) instead of an async
+  function. Enables single-pass fan-out and live-tail in v0.6.
+- `parseAll` and `parseFile` no longer block on full file reads.
+- `SessionTurn` adds `parentSessionId` and `toolUses[]` fields.
+
+### Internal
+
+- Backwards-compatible: the old `aggregate(turns, from, to, group)` async
+  function still exists and wraps the new `Aggregator` class. All v0.4.x
+  tests pass without modification (22/22).
+
 ## [0.4.1] — 2026-04-22
 
 ### Added

package/README.md

@@ -5,6 +5,9 @@
 [![npm](https://img.shields.io/npm/v/claude-agent-ledger.svg)](https://www.npmjs.com/package/claude-agent-ledger)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
+> *Even I needed `--anonymize` before posting my own data publicly.
+> That's why the flag exists. Use it before you screenshot.*
+
 ---
 
 ## Why
@@ -28,11 +31,24 @@ npm install -g claude-agent-ledger
 # or: bun install -g claude-agent-ledger
 
 agent-ledger week --summary        # the dashboard (start here)
-agent-ledger week --by model       # which Claude model burned the budget
+agent-ledger week --tree           # subagent fan-out tree (the MOAT view) — new in 0.5
+agent-ledger week --by tool        # which tool ate the budget (Read/Bash/Grep/MCP) — new in 0.5
+agent-ledger week --by model       # opus vs sonnet vs haiku
 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 today --budget 50     # CI gate: exit 2 if today > $50 — new in 0.5
+agent-ledger week --json | jq      # JSON output for ANY view incl. summary — new in 0.5
 agent-ledger month --md > report.md
+
+# Live tail — polling delta meter — new in 0.7
+agent-ledger watch                          # refresh every 10s
+agent-ledger watch 4                        # refresh every 4s
+
+# Root-cause analysis on a single expensive session — new in 0.6
+agent-ledger explain <session-id>           # heuristic: top-3 turns + tool/model breakdown
+ANTHROPIC_API_KEY=sk-ant-... agent-ledger explain <session-id>
+                                            # LLM mode: Haiku 4.5 ≤4-bullet root cause (~$0.001/run)
 ```
 
 No server. No account. No data leaves your machine.

package/bin/agent-ledger.ts

@@ -1,8 +1,10 @@
 #!/usr/bin/env bun
-import { aggregate, type GroupKey } from '../src/aggregator.ts';
+import { Aggregator, type GroupKey, SubagentGraph } from '../src/aggregator.ts';
+import { analyzeSession, formatHeuristic, llmExplain } from '../src/explain.ts';
 import { formatMarkdown, formatSummary, formatTable, formatTrend } from '../src/format.ts';
 import { parseAll } from '../src/parser.ts';
-import type { LedgerReport, SessionTurn } from '../src/types.ts';
+import { formatTree, formatTreeMarkdown } from '../src/tree.ts';
+import type { LedgerReport } from '../src/types.ts';
 
 type Period = 'today' | 'week' | 'month';
 type Plan = 'payg' | 'pro' | 'max';
@@ -14,7 +16,10 @@ interface Args {
 	plan: Plan;
 	by: GroupKey;
 	summary: boolean;
+	tree: boolean;
 	anonymize: boolean;
+	budget?: number; // USD threshold; non-zero exit if exceeded
+	verbose: boolean;
 }
 
 function periodRange(period: Period): { from: Date; to: Date } {
@@ -33,35 +38,39 @@ function periodRange(period: Period): { from: Date; to: Date } {
 }
 
 function usage(): never {
-	console.error(`Usage: agent-ledger <today|week|month> [flags]
+	console.error(`Usage:
+  agent-ledger <today|week|month> [flags]    — aggregate views
+  agent-ledger explain <sessionId>           — root-cause why one session was expensive (new in 0.6)
 
 Flags:
-  --summary                   One-screen dashboard: total + top subagent + top
-                              model + peak day + cache reuse + leverage vs $200/mo plan
-  --by <subagent|model|day|project|session>
+  --summary                   One-screen dashboard (start here).
+  --by <subagent|model|day|project|session|tool>
                               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)
+                                tool      — by Read/Bash/Write/Grep — what your turns burn on
+  --tree                      Subagent graph: parent→child cost attribution.
+                              The MOAT view: orchestrator → 3×researcher + 6×swift-dev = $312.
+  --budget <USD>              Exit non-zero (code 2) if total cost > USD. Pipe-friendly.
   --md                        Markdown table output (good for sharing / commits)
-  --json                      Raw JSON output (for piping into jq)
+  --json                      Raw JSON output (also works with --summary now)
   --plan pro|max              Suppress dollar columns (token utilization only)
-  --anonymize                 Replace project paths and session ids with safe
-                              placeholders (~/repo-A, sess-A) so the output is
-                              shareable without doxing yourself.
+  --anonymize                 Replace project paths and session ids with safe placeholders.
+  --verbose                   Print parse stats (files, turns, elapsed) to stderr.
 
 Environment:
   NO_COLOR=1                  Disable ANSI colors
   FORCE_COLOR=1               Force colors when piping
 
 Examples:
-  agent-ledger week --summary           # the dashboard
-  agent-ledger week --by day            # daily bar chart
-  agent-ledger week --by model          # which Claude model burned the budget
-  agent-ledger month --md > month.md
+  agent-ledger week --summary               # the dashboard
+  agent-ledger week --tree                  # subagent fan-out tree
+  agent-ledger week --by tool               # which Claude tool ate the budget
   agent-ledger week --json | jq '.total.cost.totalCost'
+  agent-ledger today --budget 50            # CI gate: fail if today > $50
 `);
 	process.exit(1);
 }
@@ -72,6 +81,7 @@ function parseArgs(argv: string[]): Args {
 
 	let plan: Plan = 'payg';
 	let by: GroupKey = 'subagent';
+	let budget: number | undefined;
 	for (let i = 0; i < rest.length; i++) {
 		const flag = rest[i];
 		if (flag === '--plan') {
@@ -89,13 +99,24 @@ function parseArgs(argv: string[]): Args {
 				next === 'model' ||
 				next === 'day' ||
 				next === 'project' ||
-				next === 'session'
+				next === 'session' ||
+				next === 'tool'
 			) {
 				by = next;
 				i++;
 			} else {
+				console.error(`agent-ledger: unknown --by value '${next}'`);
 				usage();
 			}
+		} else if (flag === '--budget') {
+			const next = rest[i + 1];
+			const n = Number(next);
+			if (!Number.isFinite(n) || n <= 0) {
+				console.error(`agent-ledger: --budget requires a positive number (got '${next}')`);
+				usage();
+			}
+			budget = n;
+			i++;
 		}
 	}
 	return {
@@ -105,19 +126,17 @@ function parseArgs(argv: string[]): Args {
 		plan,
 		by,
 		summary: rest.includes('--summary'),
+		tree: rest.includes('--tree'),
 		anonymize: rest.includes('--anonymize'),
+		budget,
+		verbose: rest.includes('--verbose'),
 	};
 }
 
-// Replace identifying labels with safe placeholders. Run after aggregation,
-// before formatting. We anonymize project paths (which leak employer + repo
-// names) and session ids; leave subagent / model / day untouched (those are
-// either public Anthropic info or generic agent type names).
 function anonymizeReport(report: LedgerReport, group: GroupKey): LedgerReport {
 	if (group !== 'project' && group !== 'session') return report;
 	const prefix = group === 'project' ? '~/repo-' : 'sess-';
 	const labelFor = (i: number): string => {
-		// Use A..Z then AA..ZZ for many entries
 		if (i < 26) return prefix + String.fromCharCode(65 + i);
 		return prefix + String.fromCharCode(65 + Math.floor(i / 26) - 1) + String.fromCharCode(65 + (i % 26));
 	};
@@ -125,11 +144,6 @@ function anonymizeReport(report: LedgerReport, group: GroupKey): LedgerReport {
 	return { ...report, rows: newRows };
 }
 
-// For --summary we may need to anonymize multiple sub-reports.
-function anonymizeForSummary(byProject: LedgerReport): LedgerReport {
-	return anonymizeReport(byProject, 'project');
-}
-
 function planMask(report: LedgerReport, plan: Plan): LedgerReport {
 	if (plan === 'payg') return report;
 	const zero = () => ({
@@ -148,49 +162,172 @@ 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;
+// `--watch` live-tail mode. Re-aggregates "today" every N seconds and
+// prints a clean delta meter. Polling-based (no inotify) so it works on
+// any platform Bun runs on. Ctrl-C to exit.
+async function watchCmd(intervalSec: number): Promise<void> {
+	const interval = Math.max(2, intervalSec);
+	let prevCost = 0;
+	let prevTurnCount = 0;
+	const t0 = Date.now();
+	console.log(`agent-ledger watch — refreshing every ${interval}s · Ctrl-C to exit`);
+	console.log('');
+	const tick = async () => {
+		const { from, to } = periodRange('today');
+		const agg = new Aggregator('subagent', from, to);
+		let turns = 0;
+		for await (const turn of parseAll({ from, to })) {
+			turns++;
+			agg.add(turn);
+		}
+		const report = agg.finalize();
+		const cost = report.total.cost.totalCost;
+		const dCost = cost - prevCost;
+		const dTurns = turns - prevTurnCount;
+		const elapsedMin = ((Date.now() - t0) / 60000).toFixed(1);
+		const arrow = dCost > 0 ? '↑' : dCost < 0 ? '↓' : '·';
+		const ts = new Date().toISOString().slice(11, 19);
+		const top = report.rows[0];
+		const topLabel = top ? `top: ${top.subagent} ${fmtUsdInline(top.cost.totalCost)}` : 'no data';
+		console.log(
+			`[${ts}] today $${cost.toFixed(2)}  ${arrow} +$${dCost.toFixed(2)}  · ${turns} turns (Δ${dTurns}) · ${topLabel} · live ${elapsedMin}m`,
+		);
+		prevCost = cost;
+		prevTurnCount = turns;
+	};
+	await tick();
+	const id = setInterval(() => {
+		tick().catch((e) => console.error('watch tick error:', e));
+	}, interval * 1000);
+	process.on('SIGINT', () => {
+		clearInterval(id);
+		console.log('\nagent-ledger watch — exiting');
+		process.exit(0);
+	});
+	// Keep process alive
+	await new Promise(() => {});
 }
 
-async function* iterTurns(turns: SessionTurn[]): AsyncGenerator<SessionTurn> {
-	for (const t of turns) yield t;
+const fmtUsdInline = (n: number): string => '$' + n.toFixed(n < 0.01 ? 4 : 2);
+
+async function explainCmd(sessionPrefix: string | undefined): Promise<void> {
+	if (!sessionPrefix) {
+		console.error('agent-ledger explain: missing sessionId argument');
+		console.error('Usage: agent-ledger explain <sessionId>');
+		console.error('       (sessionId can be a full uuid or 8-char prefix)');
+		process.exit(1);
+	}
+	const analysis = await analyzeSession(sessionPrefix);
+	if (!analysis) {
+		console.error(`agent-ledger explain: no session found matching '${sessionPrefix}'`);
+		console.error('  (try the 8-char prefix from `agent-ledger week --by session`)');
+		process.exit(1);
+	}
+	const heuristic = formatHeuristic(analysis);
+	console.log(heuristic);
+	const llm = await llmExplain(analysis);
+	if (llm) {
+		console.log('');
+		console.log(llm);
+	} else if (!process.env.ANTHROPIC_API_KEY) {
+		console.log('');
+		console.log('💡 Set ANTHROPIC_API_KEY to enable LLM root-cause analysis (~$0.001/run via Haiku 4.5)');
+	}
 }
 
 async function main(): Promise<void> {
+	// Subcommand dispatch.
+	if (process.argv[2] === 'explain') {
+		return explainCmd(process.argv[3]);
+	}
+	if (process.argv[2] === 'watch') {
+		const interval = Number(process.argv[3]) || 10;
+		return watchCmd(interval);
+	}
 	const args = parseArgs(process.argv.slice(2));
 	const { from, to } = periodRange(args.period);
-	const turns = await collectTurns({ from, to });
-
-	if (args.summary) {
-		const [bySub, byMod, byDay, byProjRaw] = 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'),
-		]);
-		const byProj = args.anonymize ? anonymizeForSummary(byProjRaw) : byProjRaw;
-		console.log(formatSummary(bySub, byMod, byDay, byProj, args.period));
-		return;
+	const t0 = Date.now();
+
+	// Determine which aggregators we need based on flags.
+	// Single parser pass dispatches to all in parallel — no buffering.
+	const aggBySub = new Aggregator('subagent', from, to);
+	const aggByMod = args.summary ? new Aggregator('model', from, to) : undefined;
+	const aggByDay = args.summary ? new Aggregator('day', from, to) : undefined;
+	const aggByProj = args.summary ? new Aggregator('project', from, to) : undefined;
+	const aggUser = !args.summary && !args.tree ? new Aggregator(args.by, from, to) : undefined;
+	const graph = args.tree ? new SubagentGraph() : undefined;
+
+	let turnCount = 0;
+	for await (const turn of parseAll({ from, to })) {
+		turnCount++;
+		aggBySub.add(turn);
+		aggByMod?.add(turn);
+		aggByDay?.add(turn);
+		aggByProj?.add(turn);
+		aggUser?.add(turn);
+		graph?.add(turn);
 	}
 
-	let report = await aggregate(iterTurns(turns), from, to, args.by);
-	if (args.anonymize) report = anonymizeReport(report, args.by);
-	report = planMask(report, args.plan);
-
-	let output: string;
-	if (args.json) {
-		output = JSON.stringify(report, null, 2);
-	} else if (args.markdown) {
-		output = formatMarkdown(report, args.period);
-	} else if (args.by === 'day') {
-		output = formatTrend(report, args.period);
+	if (args.verbose) {
+		const elapsed = Date.now() - t0;
+		console.error(
+			`agent-ledger: parsed ${turnCount} turns from ~/.claude/projects in ${elapsed}ms`,
+		);
+	}
+
+	let totalCost = aggBySub.finalize().total.cost.totalCost;
+
+	if (args.tree) {
+		const roots = graph!.finalize(20);
+		totalCost = roots.reduce((s, r) => s + r.totalCost, 0);
+		const out =
+			args.json
+				? JSON.stringify({ roots, totalCost }, null, 2)
+				: args.markdown
+					? formatTreeMarkdown(roots, totalCost)
+					: formatTree(roots, totalCost);
+		console.log(out);
+	} else if (args.summary) {
+		const bySubR = aggBySub.finalize();
+		const byModR = aggByMod!.finalize();
+		const byDayR = aggByDay!.finalize();
+		let byProjR = aggByProj!.finalize();
+		if (args.anonymize) byProjR = anonymizeReport(byProjR, 'project');
+		totalCost = bySubR.total.cost.totalCost;
+		if (args.json) {
+			console.log(
+				JSON.stringify(
+					{ subagent: bySubR, model: byModR, day: byDayR, project: byProjR, totalCost },
+					null,
+					2,
+				),
+			);
+		} else {
+			console.log(formatSummary(bySubR, byModR, byDayR, byProjR, args.period));
+		}
 	} else {
-		output = formatTable(report, args.period, args.by);
+		let report = aggUser!.finalize();
+		if (args.anonymize) report = anonymizeReport(report, args.by);
+		report = planMask(report, args.plan);
+		totalCost = report.total.cost.totalCost;
+		const output =
+			args.json
+				? JSON.stringify(report, null, 2)
+				: args.markdown
+					? formatMarkdown(report, args.period)
+					: args.by === 'day'
+						? formatTrend(report, args.period)
+						: formatTable(report, args.period, args.by);
+		console.log(output);
+	}
+
+	// Budget gate — non-zero exit code so this can be a CI/shell hook.
+	if (args.budget !== undefined && totalCost > args.budget) {
+		console.error(
+			`agent-ledger: BUDGET EXCEEDED — total $${totalCost.toFixed(2)} > budget $${args.budget.toFixed(2)}`,
+		);
+		process.exit(2);
 	}
-	console.log(output);
 }
 
 main().catch((err) => {

package/bun.lock

@@ -6,6 +6,7 @@
       "name": "agent-ledger",
       "devDependencies": {
         "@types/bun": "latest",
+        "fast-check": "^4.7.0",
         "typescript": "^5.6.0",
       },
     },
@@ -17,6 +18,10 @@
 
     "bun-types": ["bun-types@1.3.12", "https://registry.npmmirror.com/bun-types/-/bun-types-1.3.12.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-HqOLj5PoFajAQciOMRiIZGNoKxDJSr6qigAttOX40vJuSp6DN/CxWp9s3C1Xwm4oH7ybueITwiaOcWXoYVoRkA=="],
 
+    "fast-check": ["fast-check@4.7.0", "", { "dependencies": { "pure-rand": "^8.0.0" } }, "sha512-NsZRtqvSSoCP0HbNjUD+r1JH8zqZalyp6gLY9e7OYs7NK9b6AHOs2baBFeBG7bVNsuoukh89x2Yg3rPsul8ziQ=="],
+
+    "pure-rand": ["pure-rand@8.4.0", "", {}, "sha512-IoM8YF/jY0hiugFo/wOWqfmarlE6J0wc6fDK1PhftMk7MGhVZl88sZimmqBBFomLOCSmcCCpsfj7wXASCpvK9A=="],
+
     "typescript": ["typescript@5.9.3", "https://registry.npmmirror.com/typescript/-/typescript-5.9.3.tgz", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.19.2", "https://registry.npmmirror.com/undici-types/-/undici-types-7.19.2.tgz", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-agent-ledger",
-  "version": "0.4.1",
+  "version": "0.7.0",
   "description": "See exactly where your Claude Code budget goes — per subagent, per task.",
   "type": "module",
   "bin": {
@@ -31,6 +31,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "fast-check": "^4.7.0",
     "typescript": "^5.6.0"
   }
 }