claude-agent-ledger 0.1.0

package/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report incorrect output, crashes, or wrong attribution
+title: ''
+labels: bug
+---
+
+## What happened
+
+<!-- What did agent-ledger do? What did you expect it to do instead? -->
+
+## How to reproduce
+
+```bash
+agent-ledger <your-exact-command>
+```
+
+## Output (redact sensitive paths / subagent names)
+
+```
+<paste the output here>
+```
+
+## Your setup
+
+- OS: <!-- macOS 15.3 / Ubuntu 22.04 / ... -->
+- Bun version: <!-- `bun --version` -->
+- agent-ledger version: <!-- `agent-ledger --version` (pre-alpha: use commit SHA) -->
+- Claude Code version: <!-- `claude --version` -->
+
+## If you're on pay-as-you-go, the calibration ask
+
+If you compare `agent-ledger month` against a real Anthropic invoice and
+they differ by > 10%, I want to hear about it. Even one line: "agent-ledger
+says $X, invoice says $Y" is incredibly useful. Thanks.

package/.github/ISSUE_TEMPLATE/model-pricing.md

@@ -0,0 +1,29 @@
+---
+name: Model pricing gap
+about: A model ID shows $0 in your ledger — we're missing it from the price table
+title: 'pricing: add <model-id>'
+labels: pricing
+---
+
+## Model ID
+
+<!-- e.g. claude-opus-4-8-20260301 -->
+
+## Anthropic's published rates
+
+- Input: $<X> / 1M tokens
+- Output: $<Y> / 1M tokens
+- Link to Anthropic pricing page (with date):
+
+## Where you saw it
+
+Sample from your log (redact the content, keep the model field):
+
+```json
+{"message":{"model":"<model-id>", "usage":{"input_tokens":..., "output_tokens":...}}}
+```
+
+## Optional: PR
+
+If you want to open the PR, the pricing table lives in `src/pricing.ts`. Add a
+matching test in `test/pricing.test.ts`.

package/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## What this PR does
+
+<!-- One or two sentences. -->
+
+## Checklist
+
+- [ ] `bun run typecheck` passes
+- [ ] `bun test` passes
+- [ ] If you touched `src/pricing.ts`, there's a matching test in
+      `test/pricing.test.ts`
+- [ ] If you touched `src/parser.ts`, the change doesn't break the nested
+      `subagents/` walk (see `test/parser.test.ts`)
+- [ ] No runtime dependencies added (this tool intentionally has none)
+
+## Log snippet (if relevant)
+
+<!-- If the change is about handling some real log shape, include a redacted
+example of what it looks like. Helps me reason about whether other tools
+produce the same shape. -->

package/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run typecheck
+      - run: bun test

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `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).
+
+## [Unreleased]
+
+### Added
+- JSONL parser with recursive walk of `~/.claude/projects/**`, including nested
+  `subagents/` directories
+- Per-subagent attribution via sidecar `agent-<hash>.meta.json` files
+- Pricing with cache TTL split: `ephemeral_5m_input_tokens` (1.25×) vs
+  `ephemeral_1h_input_tokens` (2×)
+- Terminal table output (default) and Markdown export (`--md`)
+- JSON output (`--json`) for piping into other tools
+- `--plan pro|max` to suppress dollar columns on fixed-price subscriptions
+- Support for current and prior-generation model IDs (Opus 4.6/4.7,
+  Sonnet 4.5/4.6, Haiku 4.0/4.5)
+- Family-prefix fallback for unknown future models (e.g. `claude-opus-5-*`
+  resolves to Opus pricing)
+- `<synthetic>` turns (Claude Code context compaction) correctly priced at $0
+
+### Not yet
+- `--by model` breakdown
+- Cost forecasting (trailing 7-day burn rate)
+- `server_tool_use` pricing (web_search_requests, web_fetch_requests)
+- Homebrew tap
+
+## [0.0.1] — 2026-04-21
+
+Initial skeleton, not yet published.

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for looking. This project is pre-alpha and in active shape — I'm still learning
+what people actually need from a Claude Code ledger.
+
+## Quick help
+
+The most useful contributions right now:
+
+1. **Run it on your own logs and tell me what it got wrong.** Open an issue with
+   the shadow cost number `agent-ledger month` reports, and the actual Anthropic
+   invoice if you're on pay-as-you-go. I want to calibrate.
+2. **Add a model I missed.** `src/pricing.ts` has the table. Open a PR with the
+   model ID and the published rates, plus a test in `test/pricing.test.ts`.
+3. **Report a log format surprise.** If `agent-ledger` skips usage records or
+   attributes them to `(main)` when they should be a subagent, paste a redacted
+   log snippet into an issue.
+
+## Running locally
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run bin/agent-ledger.ts today
+```
+
+## Style
+
+- TypeScript strict. `noUncheckedIndexedAccess` is on.
+- Short functions. If a function needs a comment to explain what it does, the
+  function is probably doing too much.
+- No runtime dependencies except Bun built-ins (we want a small install surface).
+- Tests use `bun:test`. Fixtures live in `test/fixtures/`.
+
+## Out of scope (for now)
+
+- Real-time dashboards / web UIs
+- Sending data anywhere (the tool is read-only by design)
+- Tracking API keys or authenticating to Anthropic
+
+If you want those, that's a different tool — and that's fine, just not this one.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jie Xiang
+
+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,157 @@
+# agent-ledger
+
+> See exactly where your Claude Code budget goes — per subagent, per task, per day.
+
+[![status](https://img.shields.io/badge/status-pre--alpha-orange)](#status)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+---
+
+## Why
+
+Claude Code's invoice at month-end tells you one number. It doesn't tell you:
+
+- Which of your subagents burned most of it
+- Which tasks cost $5 and which cost $0.05
+- Whether last week's refactor was 10× more expensive than it should have been
+- Whether your "cheap" Haiku agent is actually quietly expensive
+
+If you run **one** Claude Code session, this is fine — you already know.
+If you run **seven** subagents daily (reliability, release, review, iOS factory, docs, ...), you're flying blind.
+
+`agent-ledger` reads Claude Code's local session logs and gives you a per-subagent ledger. That's it.
+
+## What it is
+
+A single-file CLI. No server. No account. No data leaves your machine.
+
+```bash
+# Install
+npm install -g claude-agent-ledger
+# or: bun install -g claude-agent-ledger
+
+# Today's spend, grouped by subagent
+agent-ledger today
+
+# Last 7 days
+agent-ledger week
+
+# Last 30 days + markdown export
+agent-ledger month --md > month-report.md
+```
+
+## Example output
+
+```
+agent-ledger week · 2026-04-14 → 2026-04-21
+
+  subagent              sess      tokens(in/out)          cache tokens (1h/5m/read)        cost
+  ────────────────────────────────────────────────────────────────────────────────────────────
+  (main)                  27       513K / 15.15M   1h:111.06M 5m:     0  r:4892.68M  $11814.53
+  general-purpose        145         112K / 876K   1h:     0  5m:19.47M  r: 168.34M    $548.25
+  Swift Developer         13           4K / 574K   1h:     0  5m: 1.61M  r:  47.55M     $28.93
+  Market Researcher       10          107K / 74K   1h:     0  5m:  863K  r:   8.61M      $7.26
+  Explore                 13          176K / 77K   1h:     0  5m: 2.60M  r:  22.38M      $6.47
+  zstackws                 3           232 / 20K   1h:     0  5m:  829K  r:   3.52M      $4.47
+  claude-code-guide        1             2K / 2K   1h:     0  5m:   56K  r:    223K      $0.08
+  ────────────────────────────────────────────────────────────────────────────────────────────
+  total                  212        915K / 16.77M  1h:111.06M 5m:25.43M  r:5143.30M  $12409.98
+```
+
+Yes those are real numbers. Yes it's a lot. See [Shadow cost vs actual bill](#shadow-cost-vs-actual-bill).
+
+## Shadow cost vs actual bill
+
+The `cost` column shows what you **would** pay at Anthropic's pay-as-you-go API rates.
+
+If you're on a fixed-price subscription (Claude Pro / Max / Claude Code plan), your actual bill is capped — the shadow cost is what the same usage **would** have cost through the raw API. It's useful for:
+
+- Understanding where time-and-token budget goes, regardless of how you pay
+- Spotting runaway agents (a 10× spike is still a 10× spike, capped or not)
+- Deciding when to downshift to Haiku or up to Opus per task
+
+If you're on pay-as-you-go, the `cost` column is roughly your bill (±5% depending on tier / geography).
+
+## How it works
+
+Claude Code writes every conversation turn to `~/.claude/projects/<encoded-path>/*.jsonl`.
+Each turn records input/output tokens, cache tokens (with TTL split), and the model used.
+Subagent invocations live under a nested `<session>/subagents/agent-*.jsonl`, with a sidecar
+`.meta.json` that carries the real subagent name (e.g. `Reality Checker`, `ios-factory`).
+
+`agent-ledger` walks the tree, resolves subagent types from the sidecar metadata, and
+aggregates by subagent. Pricing is applied locally from `src/pricing.ts`. Nothing is sent
+anywhere — the tool never touches the network after install.
+
+### Cache accounting
+
+Anthropic's prompt caching has two TTLs in current logs:
+
+| Bucket | Multiplier | Notes |
+|---|---|---|
+| `ephemeral_5m_input_tokens` | 1.25× base input | 5-minute TTL (default) |
+| `ephemeral_1h_input_tokens` | 2.00× base input | 1-hour TTL (long-lived sessions) |
+| `cache_read_input_tokens` | 0.10× base input | Read price (90% discount, TTL-agnostic) |
+
+Naive trackers lump these together as "input" and either overstate (by counting all creation as 1.25×) or understate (by ignoring the 1-hour writes entirely). `agent-ledger` breaks them out explicitly — see `src/pricing.ts`.
+
+## What it's not
+
+- Not a real-time dashboard (post-hoc log reader)
+- Not a tracker for direct Anthropic API calls (those logs live elsewhere)
+- Not a cost-limiter or kill-switch (read-only, by design)
+- Not affiliated with Anthropic
+
+## Who this is for
+
+- You run ≥ 2 Claude Code subagents and genuinely don't know the per-agent split
+- You're about to have a "wait, I spent *what*?" moment at invoice time
+- You're building AI Agent systems and want observability primitives, not vendor dashboards
+
+## Status
+
+Pre-alpha. Validated on ~200K turns of real Claude Code logs on the author's machine.
+Pricing model matches Anthropic published rates as of 2026-04-21. Shadow cost values
+may drift ±5-10% from Anthropic's actual invoice in edge cases (retries, tier bumps,
+server_tool_use which is not yet accounted for).
+
+- [x] Log parser (JSONL streaming, recursive subagent discovery)
+- [x] Per-subagent aggregation (from `<session>/subagents/*.meta.json`)
+- [x] Terminal table output
+- [x] Markdown export (`--md`)
+- [x] Cache 1h/5m TTL split pricing
+- [ ] `--plan pro|max` mode (mask shadow cost, show utilization only)
+- [ ] `--json` output mode
+- [ ] Per-model breakdown (`agent-ledger week --by model`)
+- [ ] Cost forecasting (trailing 7-day burn rate)
+- [ ] `server_tool_use` pricing (web search, file fetch)
+- [ ] Homebrew tap
+
+First tagged release: **2026-05-05**.
+
+## Install from source
+
+```bash
+git clone https://github.com/XJM-free/agent-ledger.git
+cd agent-ledger
+bun install
+bun link
+agent-ledger today
+```
+
+## Development
+
+```bash
+bun test
+bun run typecheck
+```
+
+## Author
+
+Built by [@XJM-free](https://jiexiang.dev) while running seven production Claude Code
+subagents for infrastructure work. More context: [How I run 7 production AI agents with
+Claude Code](https://jiexiang.dev).
+
+## License
+
+MIT.

package/bin/agent-ledger.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env bun
+import { aggregate } from '../src/aggregator.ts';
+import { formatMarkdown, formatTable } from '../src/format.ts';
+import { parseAll } from '../src/parser.ts';
+import type { LedgerReport } from '../src/types.ts';
+
+type Period = 'today' | 'week' | 'month';
+type Plan = 'payg' | 'pro' | 'max';
+
+interface Args {
+	period: Period;
+	markdown: boolean;
+	json: boolean;
+	plan: Plan;
+}
+
+function periodRange(period: Period): { from: Date; to: Date } {
+	const now = new Date();
+	const to = new Date(now);
+	const from = new Date(now);
+
+	if (period === 'today') {
+		from.setHours(0, 0, 0, 0);
+	} else if (period === 'week') {
+		from.setDate(from.getDate() - 7);
+	} else {
+		from.setDate(from.getDate() - 30);
+	}
+	return { from, to };
+}
+
+function usage(): never {
+	console.error(`Usage: agent-ledger <today|week|month> [flags]
+
+Flags:
+  --md              Emit a Markdown table (good for sharing / commits)
+  --json            Emit raw JSON (for piping into other tools)
+  --plan pro|max    Suppress dollar columns. Report token utilization only.
+                    (Default is pay-as-you-go, which shows shadow cost in $.)
+
+Examples:
+  agent-ledger today
+  agent-ledger week --md > week.md
+  agent-ledger month --json | jq '.total.cost.totalCost'
+  agent-ledger week --plan max
+`);
+	process.exit(1);
+}
+
+function parseArgs(argv: string[]): Args {
+	const [period, ...rest] = argv;
+	if (!period || !['today', 'week', 'month'].includes(period)) usage();
+
+	let plan: Plan = 'payg';
+	for (let i = 0; i < rest.length; i++) {
+		const flag = rest[i];
+		if (flag === '--plan') {
+			const next = rest[i + 1];
+			if (next === 'pro' || next === 'max') {
+				plan = next;
+				i++;
+			} else {
+				usage();
+			}
+		}
+	}
+	return {
+		period: period as Period,
+		markdown: rest.includes('--md'),
+		json: rest.includes('--json'),
+		plan,
+	};
+}
+
+function planMask(report: LedgerReport, plan: Plan): LedgerReport {
+	if (plan === 'payg') return report;
+	// On Pro/Max the per-call dollar number isn't what you pay, so hide it.
+	// Keep tokens visible — those are the real utilization signal.
+	const zero = () => ({
+		inputCost: 0,
+		outputCost: 0,
+		cacheCreation5mCost: 0,
+		cacheCreation1hCost: 0,
+		cacheReadCost: 0,
+		totalCost: 0,
+	});
+	return {
+		period: report.period,
+		rows: report.rows.map((r) => ({ ...r, cost: zero() })),
+		total: { ...report.total, cost: zero() },
+	};
+}
+
+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);
+	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 {
+		output = formatTable(report, args.period);
+	}
+	console.log(output);
+}
+
+main().catch((err) => {
+	console.error('agent-ledger: fatal error');
+	console.error(err);
+	process.exit(1);
+});

package/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "agent-ledger",
+      "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.6.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.12", "https://registry.npmmirror.com/@types/bun/-/bun-1.3.12.tgz", { "dependencies": { "bun-types": "1.3.12" } }, "sha512-DBv81elK+/VSwXHDlnH3Qduw+KxkTIWi7TXkAeh24zpi5l0B2kUg9Ga3tb4nJaPcOFswflgi/yAvMVBPrxMB+A=="],
+
+    "@types/node": ["@types/node@25.6.0", "https://registry.npmmirror.com/@types/node/-/node-25.6.0.tgz", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "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=="],
+
+    "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

@@ -0,0 +1,36 @@
+{
+  "name": "claude-agent-ledger",
+  "version": "0.1.0",
+  "description": "See exactly where your Claude Code budget goes — per subagent, per task.",
+  "type": "module",
+  "bin": {
+    "agent-ledger": "./bin/agent-ledger.ts"
+  },
+  "scripts": {
+    "dev": "bun run bin/agent-ledger.ts",
+    "test": "bun test",
+    "build": "bun build bin/agent-ledger.ts --target=node --outdir dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "ai-agents",
+    "cost-tracking",
+    "observability",
+    "cli"
+  ],
+  "author": "Jie Xiang <jie.xiang.jm@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XJM-free/claude-agent-ledger.git"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  }
+}

package/src/aggregator.ts

@@ -0,0 +1,96 @@
+import { costFor } from './pricing.ts';
+import type { AggregatedRow, LedgerReport, SessionTurn } from './types.ts';
+
+const MAIN_AGENT_LABEL = '(main)';
+
+function emptyRow(subagent: string): AggregatedRow {
+	return {
+		subagent,
+		sessionCount: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheCreation5mTokens: 0,
+		cacheCreation1hTokens: 0,
+		cacheReadTokens: 0,
+		cost: {
+			inputCost: 0,
+			outputCost: 0,
+			cacheCreation5mCost: 0,
+			cacheCreation1hCost: 0,
+			cacheReadCost: 0,
+			totalCost: 0,
+		},
+	};
+}
+
+function splitCache(turn: SessionTurn): { fiveMin: number; oneHour: number } {
+	const usage = turn.usage;
+	if (!usage) return { fiveMin: 0, oneHour: 0 };
+	if (usage.cache_creation) {
+		return {
+			fiveMin: usage.cache_creation.ephemeral_5m_input_tokens ?? 0,
+			oneHour: usage.cache_creation.ephemeral_1h_input_tokens ?? 0,
+		};
+	}
+	return { fiveMin: usage.cache_creation_input_tokens ?? 0, oneHour: 0 };
+}
+
+export async function aggregate(
+	turns: AsyncIterable<SessionTurn>,
+	from: Date,
+	to: Date,
+): Promise<LedgerReport> {
+	const rowsByAgent = new Map<string, AggregatedRow>();
+	const sessionsByAgent = new Map<string, Set<string>>();
+
+	for await (const turn of turns) {
+		if (turn.type !== 'assistant' || !turn.usage) continue;
+
+		const agent = turn.subagentType ?? MAIN_AGENT_LABEL;
+		const row = rowsByAgent.get(agent) ?? emptyRow(agent);
+
+		const cost = costFor(turn.usage, turn.model);
+		const { fiveMin, oneHour } = splitCache(turn);
+
+		row.inputTokens += turn.usage.input_tokens;
+		row.outputTokens += turn.usage.output_tokens;
+		row.cacheCreation5mTokens += fiveMin;
+		row.cacheCreation1hTokens += oneHour;
+		row.cacheReadTokens += turn.usage.cache_read_input_tokens ?? 0;
+		row.cost.inputCost += cost.inputCost;
+		row.cost.outputCost += cost.outputCost;
+		row.cost.cacheCreation5mCost += cost.cacheCreation5mCost;
+		row.cost.cacheCreation1hCost += cost.cacheCreation1hCost;
+		row.cost.cacheReadCost += cost.cacheReadCost;
+		row.cost.totalCost += cost.totalCost;
+
+		const sessions = sessionsByAgent.get(agent) ?? new Set<string>();
+		sessions.add(turn.sessionId);
+		sessionsByAgent.set(agent, sessions);
+
+		rowsByAgent.set(agent, row);
+	}
+
+	for (const [agent, row] of rowsByAgent) {
+		row.sessionCount = sessionsByAgent.get(agent)?.size ?? 0;
+	}
+
+	const rows = [...rowsByAgent.values()].sort((a, b) => b.cost.totalCost - a.cost.totalCost);
+	const total = rows.reduce<AggregatedRow>((acc, row) => {
+		acc.sessionCount += row.sessionCount;
+		acc.inputTokens += row.inputTokens;
+		acc.outputTokens += row.outputTokens;
+		acc.cacheCreation5mTokens += row.cacheCreation5mTokens;
+		acc.cacheCreation1hTokens += row.cacheCreation1hTokens;
+		acc.cacheReadTokens += row.cacheReadTokens;
+		acc.cost.inputCost += row.cost.inputCost;
+		acc.cost.outputCost += row.cost.outputCost;
+		acc.cost.cacheCreation5mCost += row.cost.cacheCreation5mCost;
+		acc.cost.cacheCreation1hCost += row.cost.cacheCreation1hCost;
+		acc.cost.cacheReadCost += row.cost.cacheReadCost;
+		acc.cost.totalCost += row.cost.totalCost;
+		return acc;
+	}, emptyRow('total'));
+
+	return { period: { from, to }, rows, total };
+}

package/src/format.ts

@@ -0,0 +1,78 @@
+import type { AggregatedRow, LedgerReport } from './types.ts';
+
+const PAD_SUBAGENT = 22;
+
+function fmtTokens(n: number): string {
+	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);
+}
+
+function fmtUsd(n: number): string {
+	return `$${n.toFixed(2)}`;
+}
+
+function formatRow(row: AggregatedRow): string {
+	const subagent = row.subagent.padEnd(PAD_SUBAGENT);
+	const sessions = String(row.sessionCount).padStart(4);
+	const io = `${fmtTokens(row.inputTokens)} / ${fmtTokens(row.outputTokens)}`.padStart(18);
+	const cached1h = fmtTokens(row.cacheCreation1hTokens).padStart(7);
+	const cached5m = fmtTokens(row.cacheCreation5mTokens).padStart(7);
+	const cacheRead = fmtTokens(row.cacheReadTokens).padStart(8);
+	const cost = fmtUsd(row.cost.totalCost).padStart(9);
+	return `  ${subagent}${sessions}  ${io}  1h:${cached1h} 5m:${cached5m} r:${cacheRead}  ${cost}`;
+}
+
+export function formatTable(report: LedgerReport, label: string): string {
+	const header = `agent-ledger ${label} · ${report.period.from.toISOString().slice(0, 10)}` +
+		` → ${report.period.to.toISOString().slice(0, 10)}`;
+
+	const cols = '  ' +
+		'subagent'.padEnd(PAD_SUBAGENT) +
+		'sess'.padStart(4) + '  ' +
+		'tokens(in/out)'.padStart(18) + '  ' +
+		'cache tokens (1h/5m/read)'.padStart(32) + '  ' +
+		'cost'.padStart(9);
+
+	const sep = '  ' + '─'.repeat(PAD_SUBAGENT + 4 + 2 + 18 + 2 + 32 + 2 + 9);
+
+	return [
+		header,
+		'',
+		cols,
+		sep,
+		...report.rows.map(formatRow),
+		sep,
+		formatRow({ ...report.total, subagent: 'total' }),
+	].join('\n');
+}
+
+export function formatMarkdown(report: LedgerReport, label: string): string {
+	const header = '| subagent | sessions | input | output | cache 1h | cache 5m | cache read | cost |';
+	const sep = '|---|---:|---:|---:|---:|---:|---:|---:|';
+	const rows = report.rows.map(
+		(r) =>
+			`| ${r.subagent} | ${r.sessionCount} | ${fmtTokens(r.inputTokens)} | ${fmtTokens(
+				r.outputTokens,
+			)} | ${fmtTokens(r.cacheCreation1hTokens)} | ${fmtTokens(r.cacheCreation5mTokens)} | ${fmtTokens(
+				r.cacheReadTokens,
+			)} | ${fmtUsd(r.cost.totalCost)} |`,
+	);
+	const totalRow = `| **total** | ${report.total.sessionCount} | ${fmtTokens(
+		report.total.inputTokens,
+	)} | ${fmtTokens(report.total.outputTokens)} | ${fmtTokens(
+		report.total.cacheCreation1hTokens,
+	)} | ${fmtTokens(report.total.cacheCreation5mTokens)} | ${fmtTokens(
+		report.total.cacheReadTokens,
+	)} | **${fmtUsd(report.total.cost.totalCost)}** |`;
+
+	return [
+		`# agent-ledger · ${label}`,
+		`_${report.period.from.toISOString().slice(0, 10)} → ${report.period.to.toISOString().slice(0, 10)}_`,
+		'',
+		header,
+		sep,
+		...rows,
+		totalRow,
+	].join('\n');
+}

package/src/parser.ts

@@ -0,0 +1,134 @@
+import { readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import type { SessionTurn, TokenUsage } from './types.ts';
+
+const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+
+export interface ParseOptions {
+	from?: Date;
+	to?: Date;
+	projectsDir?: string;
+}
+
+interface LogFile {
+	path: string;
+	subagentType: string | undefined;
+}
+
+// Walk the projects directory and yield every JSONL log.
+// Real Claude Code layout (as of 2026-04):
+//   ~/.claude/projects/<encoded-project>/<session-uuid>.jsonl             (main session)
+//   ~/.claude/projects/<encoded-project>/<session-uuid>/subagents/agent-<hash>.jsonl  (subagent)
+//   ~/.claude/projects/<encoded-project>/<session-uuid>/subagents/agent-<hash>.meta.json
+//
+// The .meta.json next to each subagent .jsonl carries { "agentType": "...", "description": "..." }.
+// We read it to attribute the subagent by its real name (e.g. "Reality Checker") rather than an opaque hash.
+export async function* findSessionLogs(
+	projectsDir: string = CLAUDE_PROJECTS_DIR,
+): AsyncGenerator<LogFile> {
+	let projects: string[] = [];
+	try {
+		projects = await readdir(projectsDir);
+	} catch {
+		return;
+	}
+	for (const project of projects) {
+		yield* walkForJsonl(join(projectsDir, project));
+	}
+}
+
+async function* walkForJsonl(dir: string): AsyncGenerator<LogFile> {
+	let entries: string[] = [];
+	try {
+		entries = await readdir(dir);
+	} catch {
+		return;
+	}
+	for (const name of entries) {
+		if (name.startsWith('.') || name === 'memory') continue;
+		const full = join(dir, name);
+		let isDir = false;
+		try {
+			isDir = (await stat(full)).isDirectory();
+		} catch {
+			continue;
+		}
+		if (isDir) {
+			yield* walkForJsonl(full);
+			continue;
+		}
+		if (name.endsWith('.jsonl')) {
+			yield { path: full, subagentType: await resolveSubagentType(full) };
+		}
+	}
+}
+
+async function resolveSubagentType(jsonlPath: string): Promise<string | undefined> {
+	// Subagent logs live under `.../subagents/agent-<hash>.jsonl` with a sibling `.meta.json`.
+	if (basename(dirname(jsonlPath)) !== 'subagents') return undefined;
+	const metaPath = jsonlPath.replace(/\.jsonl$/, '.meta.json');
+	try {
+		const text = await Bun.file(metaPath).text();
+		const meta = JSON.parse(text) as { agentType?: string };
+		return meta.agentType;
+	} catch {
+		return undefined;
+	}
+}
+
+// Stream-parse one JSONL file. Skips malformed lines rather than aborting.
+export async function* parseFile(
+	path: string,
+	subagentType?: string,
+): AsyncGenerator<SessionTurn> {
+	const file = Bun.file(path);
+	const text = await file.text();
+	const sessionId = basename(path).replace('.jsonl', '');
+
+	for (const line of text.split('\n')) {
+		if (!line.trim()) continue;
+		let obj: Record<string, unknown>;
+		try {
+			obj = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		yield extractTurn(obj, sessionId, subagentType);
+	}
+}
+
+function extractTurn(
+	obj: Record<string, unknown>,
+	sessionId: string,
+	subagentType: string | undefined,
+): SessionTurn {
+	const msg = (obj.message ?? {}) as Record<string, unknown>;
+	const usage = (msg.usage ?? undefined) as TokenUsage | undefined;
+	const model = (msg.model ?? undefined) as string | undefined;
+	// 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;
+
+	return {
+		type: ((obj.type as string) ?? 'assistant') as SessionTurn['type'],
+		timestamp: (obj.timestamp as string) ?? new Date().toISOString(),
+		sessionId,
+		subagentType: perTurnSubagent ?? subagentType,
+		model,
+		usage,
+		raw: obj,
+	};
+}
+
+// Convenience: stream every turn across every log under ~/.claude/projects.
+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)) {
+			if (opts.from && new Date(turn.timestamp) < opts.from) continue;
+			if (opts.to && new Date(turn.timestamp) > opts.to) continue;
+			yield turn;
+		}
+	}
+}

package/src/pricing.ts

@@ -0,0 +1,95 @@
+import type { CostBreakdown, ModelId, TokenUsage } from './types.ts';
+
+// Prices are per 1M tokens, USD. Keep in sync with
+// https://www.anthropic.com/pricing as of 2026-04-21.
+//
+// Prompt caching (Anthropic):
+//   cache_creation 5-min TTL: 1.25× base input rate
+//   cache_creation 1-hour TTL: 2×    base input rate
+//   cache_read (any TTL):      0.10× base input rate (90% discount)
+//
+// We include both current and prior-generation model IDs because real logs span
+// version bumps (Claude Code does not auto-rewrite historical logs when you upgrade).
+const PRICING: Record<string, { input: number; output: number }> = {
+	// Current generation (2026-04)
+	'claude-opus-4-7': { input: 15, output: 75 },
+	'claude-sonnet-4-6': { input: 3, output: 15 },
+	'claude-haiku-4-5-20251001': { input: 0.8, output: 4 },
+	// Prior generation (still appears in logs written before model upgrades)
+	'claude-opus-4-6': { input: 15, output: 75 },
+	'claude-opus-4-5': { input: 15, output: 75 },
+	'claude-sonnet-4-5': { input: 3, output: 15 },
+	'claude-haiku-4-0': { input: 0.8, output: 4 },
+};
+
+// Internal Claude Code markers that we should treat as free.
+// `<synthetic>` turns are context summaries / compaction events with no real API call.
+const FREE_MODELS = new Set<string>(['<synthetic>']);
+
+const CACHE_5M_MULTIPLIER = 1.25;
+const CACHE_1H_MULTIPLIER = 2.0;
+const CACHE_READ_MULTIPLIER = 0.1;
+
+function resolveModel(model: ModelId | undefined): { input: number; output: number } {
+	if (!model) return { input: 0, output: 0 };
+	if (FREE_MODELS.has(model)) return { input: 0, output: 0 };
+	const exact = PRICING[model];
+	if (exact) return exact;
+	// Fuzzy family prefix match as a safety net for unknown subversions.
+	// e.g. "claude-opus-4-8-20260301" falls back to Opus pricing until we add it.
+	for (const key of Object.keys(PRICING)) {
+		if (model.startsWith(key)) return PRICING[key] as { input: number; output: number };
+	}
+	if (model.startsWith('claude-opus-')) return { input: 15, output: 75 };
+	if (model.startsWith('claude-sonnet-')) return { input: 3, output: 15 };
+	if (model.startsWith('claude-haiku-')) return { input: 0.8, output: 4 };
+	return { input: 0, output: 0 };
+}
+
+interface CacheBreakdown {
+	fiveMin: number;
+	oneHour: number;
+}
+
+function splitCacheCreation(usage: TokenUsage): CacheBreakdown {
+	if (usage.cache_creation) {
+		return {
+			fiveMin: usage.cache_creation.ephemeral_5m_input_tokens ?? 0,
+			oneHour: usage.cache_creation.ephemeral_1h_input_tokens ?? 0,
+		};
+	}
+	return {
+		fiveMin: usage.cache_creation_input_tokens ?? 0,
+		oneHour: 0,
+	};
+}
+
+export function costFor(usage: TokenUsage, model: ModelId | undefined): CostBreakdown {
+	const rate = resolveModel(model);
+	const cacheRead = usage.cache_read_input_tokens ?? 0;
+	const { fiveMin, oneHour } = splitCacheCreation(usage);
+
+	const perMillion = (tokens: number, price: number) => (tokens / 1_000_000) * price;
+
+	const inputCost = perMillion(usage.input_tokens, rate.input);
+	const outputCost = perMillion(usage.output_tokens, rate.output);
+	const cacheCreation5mCost = perMillion(fiveMin, rate.input * CACHE_5M_MULTIPLIER);
+	const cacheCreation1hCost = perMillion(oneHour, rate.input * CACHE_1H_MULTIPLIER);
+	const cacheReadCost = perMillion(cacheRead, rate.input * CACHE_READ_MULTIPLIER);
+
+	return {
+		inputCost,
+		outputCost,
+		cacheCreation5mCost,
+		cacheCreation1hCost,
+		cacheReadCost,
+		totalCost: inputCost + outputCost + cacheCreation5mCost + cacheCreation1hCost + cacheReadCost,
+	};
+}
+
+export function isKnownModel(model: ModelId | undefined): boolean {
+	if (!model) return false;
+	if (FREE_MODELS.has(model)) return true;
+	if (PRICING[model]) return true;
+	return Object.keys(PRICING).some((key) => model.startsWith(key));
+}

package/src/types.ts

@@ -0,0 +1,58 @@
+export type ModelId =
+	| 'claude-opus-4-7'
+	| 'claude-sonnet-4-6'
+	| 'claude-haiku-4-5-20251001'
+	| string;
+
+export type TurnType = 'user' | 'assistant' | 'summary' | 'system';
+
+export interface CacheCreationDetail {
+	ephemeral_5m_input_tokens?: number;
+	ephemeral_1h_input_tokens?: number;
+}
+
+export interface TokenUsage {
+	input_tokens: number;
+	output_tokens: number;
+	// Legacy flat counter. Real logs also carry `cache_creation` with TTL split; if present,
+	// prefer that for accurate pricing.
+	cache_creation_input_tokens?: number;
+	cache_read_input_tokens?: number;
+	cache_creation?: CacheCreationDetail;
+}
+
+export interface SessionTurn {
+	type: TurnType;
+	timestamp: string;
+	sessionId: string;
+	subagentType?: string | undefined;
+	model?: ModelId | undefined;
+	usage?: TokenUsage | undefined;
+	raw: unknown;
+}
+
+export interface CostBreakdown {
+	inputCost: number;
+	outputCost: number;
+	cacheCreation5mCost: number;
+	cacheCreation1hCost: number;
+	cacheReadCost: number;
+	totalCost: number;
+}
+
+export interface AggregatedRow {
+	subagent: string;
+	sessionCount: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheCreation5mTokens: number;
+	cacheCreation1hTokens: number;
+	cacheReadTokens: number;
+	cost: CostBreakdown;
+}
+
+export interface LedgerReport {
+	period: { from: Date; to: Date };
+	rows: AggregatedRow[];
+	total: AggregatedRow;
+}

package/test/aggregator.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+import { aggregate } from '../src/aggregator.ts';
+import { parseFile } from '../src/parser.ts';
+
+const FIXTURE = join(import.meta.dir, 'fixtures', 'sample.jsonl');
+
+describe('aggregate()', () => {
+	test('groups assistant turns by subagent', async () => {
+		const from = new Date('2026-04-21T00:00:00Z');
+		const to = new Date('2026-04-21T23:59:59Z');
+		const report = await aggregate(parseFile(FIXTURE), from, to);
+
+		const agents = report.rows.map((r) => r.subagent);
+		expect(agents).toContain('ios-factory');
+		expect(agents).toContain('Reality Checker');
+		expect(agents).toContain('(main)');
+	});
+
+	test('skips user turns (no usage data)', async () => {
+		const from = new Date('2026-04-21T00:00:00Z');
+		const to = new Date('2026-04-21T23:59:59Z');
+		const report = await aggregate(parseFile(FIXTURE), from, to);
+
+		// 4 assistant turns in fixture (3 subagents, some with >1 turn each).
+		const totalSessions = report.total.sessionCount;
+		expect(totalSessions).toBeGreaterThan(0);
+	});
+
+	test('rows are sorted by total cost descending', async () => {
+		const from = new Date('2026-04-21T00:00:00Z');
+		const to = new Date('2026-04-21T23:59:59Z');
+		const report = await aggregate(parseFile(FIXTURE), from, to);
+
+		for (let i = 1; i < report.rows.length; i++) {
+			const prev = report.rows[i - 1]!.cost.totalCost;
+			const curr = report.rows[i]!.cost.totalCost;
+			expect(prev).toBeGreaterThanOrEqual(curr);
+		}
+	});
+
+	test('total row sums all agent rows', async () => {
+		const from = new Date('2026-04-21T00:00:00Z');
+		const to = new Date('2026-04-21T23:59:59Z');
+		const report = await aggregate(parseFile(FIXTURE), from, to);
+
+		const sumCost = report.rows.reduce((s, r) => s + r.cost.totalCost, 0);
+		expect(report.total.cost.totalCost).toBeCloseTo(sumCost, 6);
+	});
+});

package/test/fixtures/projects/proj-a/session-abc/subagents/agent-deadbeef.jsonl

@@ -0,0 +1,2 @@
+{"type":"assistant","timestamp":"2026-04-21T10:05:00Z","message":{"role":"assistant","model":"claude-sonnet-4-6","usage":{"input_tokens":4200,"output_tokens":1300,"cache_creation_input_tokens":2000,"cache_read_input_tokens":22000}}}
+{"type":"assistant","timestamp":"2026-04-21T10:07:00Z","message":{"role":"assistant","model":"claude-sonnet-4-6","usage":{"input_tokens":800,"output_tokens":220,"cache_read_input_tokens":26000}}}

package/test/fixtures/projects/proj-a/session-abc/subagents/agent-deadbeef.meta.json

@@ -0,0 +1 @@
+{"agentType":"Reality Checker","description":"Review migration safety"}

package/test/fixtures/projects/proj-a/session-abc.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-04-21T10:00:00Z","message":{"role":"user","content":"hello"}}
+{"type":"assistant","timestamp":"2026-04-21T10:00:12Z","message":{"role":"assistant","model":"claude-opus-4-7","usage":{"input_tokens":1200,"output_tokens":420,"cache_read_input_tokens":8000}}}

package/test/fixtures/sample.jsonl

@@ -0,0 +1,6 @@
+{"type":"user","timestamp":"2026-04-21T10:00:00Z","message":{"role":"user","content":"Fix the release script"}}
+{"type":"assistant","timestamp":"2026-04-21T10:00:12Z","subagentType":"ios-factory","message":{"role":"assistant","model":"claude-opus-4-7","usage":{"input_tokens":4200,"output_tokens":1180,"cache_creation_input_tokens":2400,"cache_read_input_tokens":18000}}}
+{"type":"assistant","timestamp":"2026-04-21T10:01:02Z","subagentType":"ios-factory","message":{"role":"assistant","model":"claude-opus-4-7","usage":{"input_tokens":2100,"output_tokens":640,"cache_read_input_tokens":22000}}}
+{"type":"user","timestamp":"2026-04-21T11:30:00Z","message":{"role":"user","content":"Review this PR"}}
+{"type":"assistant","timestamp":"2026-04-21T11:30:08Z","subagentType":"Reality Checker","message":{"role":"assistant","model":"claude-sonnet-4-6","usage":{"input_tokens":8800,"output_tokens":1520,"cache_creation_input_tokens":1200,"cache_read_input_tokens":44000}}}
+{"type":"assistant","timestamp":"2026-04-21T15:10:00Z","message":{"role":"assistant","model":"claude-haiku-4-5-20251001","usage":{"input_tokens":1200,"output_tokens":320}}}

package/test/parser.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+import { aggregate } from '../src/aggregator.ts';
+import { parseAll } from '../src/parser.ts';
+
+const PROJECTS_DIR = join(import.meta.dir, 'fixtures', 'projects');
+
+describe('parseAll()', () => {
+	test('walks nested subagents/ directories and attributes subagent type', async () => {
+		const from = new Date('2026-04-21T00:00:00Z');
+		const to = new Date('2026-04-21T23:59:59Z');
+
+		const report = await aggregate(
+			parseAll({ from, to, projectsDir: PROJECTS_DIR }),
+			from,
+			to,
+		);
+
+		const agents = report.rows.map((r) => r.subagent).sort();
+		expect(agents).toContain('(main)');
+		expect(agents).toContain('Reality Checker');
+	});
+
+	test('main-session turns are attributed to (main), not to any subagent', async () => {
+		const from = new Date('2026-04-21T00:00:00Z');
+		const to = new Date('2026-04-21T23:59:59Z');
+
+		const report = await aggregate(
+			parseAll({ from, to, projectsDir: PROJECTS_DIR }),
+			from,
+			to,
+		);
+
+		const main = report.rows.find((r) => r.subagent === '(main)');
+		const realityChecker = report.rows.find((r) => r.subagent === 'Reality Checker');
+
+		expect(main).toBeDefined();
+		expect(realityChecker).toBeDefined();
+		expect(main!.sessionCount).toBe(1);
+		expect(realityChecker!.sessionCount).toBe(1);
+	});
+
+	test('respects date range filter', async () => {
+		const from = new Date('2030-01-01T00:00:00Z');
+		const to = new Date('2030-01-02T00:00:00Z');
+
+		const report = await aggregate(
+			parseAll({ from, to, projectsDir: PROJECTS_DIR }),
+			from,
+			to,
+		);
+
+		expect(report.rows.length).toBe(0);
+	});
+});

package/test/pricing.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from 'bun:test';
+import { costFor, isKnownModel } from '../src/pricing.ts';
+
+describe('costFor()', () => {
+	test('Opus output is $75/M', () => {
+		const cost = costFor(
+			{ input_tokens: 0, output_tokens: 1_000_000 },
+			'claude-opus-4-7',
+		);
+		expect(cost.outputCost).toBeCloseTo(75, 6);
+	});
+
+	test('Opus input is $15/M', () => {
+		const cost = costFor(
+			{ input_tokens: 1_000_000, output_tokens: 0 },
+			'claude-opus-4-7',
+		);
+		expect(cost.inputCost).toBeCloseTo(15, 6);
+	});
+
+	test('5-minute cache creation is 1.25× base input', () => {
+		const cost = costFor(
+			{
+				input_tokens: 0,
+				output_tokens: 0,
+				cache_creation: { ephemeral_5m_input_tokens: 1_000_000 },
+			},
+			'claude-opus-4-7',
+		);
+		// Opus input $15 × 1.25 = $18.75 per 1M
+		expect(cost.cacheCreation5mCost).toBeCloseTo(18.75, 4);
+		expect(cost.cacheCreation1hCost).toBeCloseTo(0, 6);
+	});
+
+	test('1-hour cache creation is 2× base input (the TTL trap)', () => {
+		const cost = costFor(
+			{
+				input_tokens: 0,
+				output_tokens: 0,
+				cache_creation: { ephemeral_1h_input_tokens: 1_000_000 },
+			},
+			'claude-opus-4-7',
+		);
+		// Opus input $15 × 2 = $30 per 1M
+		expect(cost.cacheCreation1hCost).toBeCloseTo(30, 4);
+		expect(cost.cacheCreation5mCost).toBeCloseTo(0, 6);
+	});
+
+	test('cache read is 10% of base input', () => {
+		const cost = costFor(
+			{
+				input_tokens: 0,
+				output_tokens: 0,
+				cache_read_input_tokens: 1_000_000,
+			},
+			'claude-opus-4-7',
+		);
+		// Opus input $15 × 0.1 = $1.50 per 1M
+		expect(cost.cacheReadCost).toBeCloseTo(1.5, 4);
+	});
+
+	test('legacy flat cache_creation_input_tokens falls back to 5m TTL pricing', () => {
+		const cost = costFor(
+			{
+				input_tokens: 0,
+				output_tokens: 0,
+				cache_creation_input_tokens: 1_000_000,
+			},
+			'claude-opus-4-7',
+		);
+		expect(cost.cacheCreation5mCost).toBeCloseTo(18.75, 4);
+	});
+
+	test('prior-generation model IDs (opus-4-6) resolve to current pricing', () => {
+		const cost = costFor(
+			{ input_tokens: 1_000_000, output_tokens: 0 },
+			'claude-opus-4-6',
+		);
+		expect(cost.inputCost).toBeCloseTo(15, 6);
+	});
+
+	test('unknown future opus variant falls back to opus family pricing', () => {
+		const cost = costFor(
+			{ input_tokens: 1_000_000, output_tokens: 0 },
+			'claude-opus-9-9',
+		);
+		expect(cost.inputCost).toBeCloseTo(15, 6);
+	});
+
+	test('<synthetic> model is free', () => {
+		const cost = costFor(
+			{
+				input_tokens: 1_000_000,
+				output_tokens: 1_000_000,
+				cache_read_input_tokens: 1_000_000,
+			},
+			'<synthetic>',
+		);
+		expect(cost.totalCost).toBe(0);
+	});
+
+	test('isKnownModel recognizes current, prior, and family matches', () => {
+		expect(isKnownModel('claude-opus-4-7')).toBe(true);
+		expect(isKnownModel('claude-opus-4-6')).toBe(true);
+		expect(isKnownModel('claude-sonnet-4-6')).toBe(true);
+		expect(isKnownModel('<synthetic>')).toBe(true);
+		expect(isKnownModel('something-entirely-unknown')).toBe(false);
+		expect(isKnownModel(undefined)).toBe(false);
+	});
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["bun-types"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*", "bin/**/*", "test/**/*"]
+}