claude-agent-ledger 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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

package/README.md

@@ -29,6 +29,8 @@ npm 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 --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
 ```
@@ -41,7 +43,10 @@ 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 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)
@@ -56,17 +61,24 @@ Run `agent-ledger week --summary` once and decide.
 ```
 agent-ledger week summary  2026-04-15 → 2026-04-22
 
-  Shadow cost           $13,356.27
-  Sessions              217
+  Shadow cost           $13,450.05
+  Sessions              219
+  Projects              9
   Plan reference        $200/mo (Max)
-  Multiplier            250× vs Max plan
+  Multiplier            252× 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
+  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
 
-  Cache 1h writes       119.45M tokens · $3583.42
-  Cache reads           5.54B tokens · $8162.93
+  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
 ```
@@ -166,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

@@ -37,8 +37,13 @@ function usage(): never {
 Flags:
   --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
+  --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)
@@ -75,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 {
@@ -128,12 +139,13 @@ async function main(): Promise<void> {
 	const turns = await collectTurns({ from, to });
 
 	if (args.summary) {
-		const [bySub, byMod, byDay] = await Promise.all([
+		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, args.period));
+		console.log(formatSummary(bySub, byMod, byDay, byProj, args.period));
 		return;
 	}
 
@@ -148,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.3.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,9 +1,17 @@
 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 = (() => {
 	if (process.env.NO_COLOR) return false;
@@ -52,8 +60,8 @@ function pct(part: number, whole: number): string {
 	return `${((part / whole) * 100).toFixed(0)}%`;
 }
 
-function formatRow(row: AggregatedRow, isTotal = false): string {
-	const labelText = row.subagent.padEnd(PAD_LABEL);
+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}`;
@@ -126,19 +134,20 @@ function deriveInsights(report: LedgerReport): string[] {
 	return lines;
 }
 
-export function formatTable(report: LedgerReport, label: string): string {
+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} ${label.includes('day') ? 'days' : label.includes('model') ? 'models' : 'agents'}`;
+		`  ${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) +
@@ -148,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 = [
@@ -156,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)
@@ -251,11 +260,12 @@ function deriveDailyInsights(report: LedgerReport): string[] {
 	return lines;
 }
 
-// Single-screen dashboard. Aggregates the same period across 3 dimensions.
+// 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;
@@ -267,6 +277,9 @@ export function formatSummary(
 	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}`;
@@ -281,28 +294,43 @@ export function formatSummary(
 		'',
 		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)}` : '—'),
-		'',
-		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}`,
-		),
 	];
+
+	// 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;