claude-agent-ledger 0.4.1 → 0.7.1

package/CHANGELOG.md

@@ -1,105 +0,0 @@
-# Changelog
-
-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.1] — 2026-04-22
-
-### Added
-- `--anonymize` flag — replaces project paths with `~/repo-A`, `~/repo-B`,
-  ... and session ids with `sess-A`, `sess-B`, ... ordered by spend descending.
-  Use this when you want to share your output publicly (HN / Bluesky /
-  presentation) without leaking employer names or internal repo names.
-  Subagent / model / day labels stay untouched (those are public info).
-
-## [0.4.0] — 2026-04-22
-
-### Added
-- `--by project` — group spend by Claude Code project directory.
-  Decodes `~/.claude/projects/-Users-xiangjie-clawbot` → `~/clawbot` so you can
-  see which project is burning budget.
-- `--by session` — group by session ID. Surfaces the single most expensive
-  conversations (useful for hunting the one that went sideways).
-- Summary dashboard now shows:
-  - `Projects` count
-  - `Top project` line
-  - `Project mix` block — top 3 projects with $ and %
-- `decodeProjectId()` exported for reuse. Special-cases the `~/` home prefix,
-  falls back to slash-joined path for other roots.
-- Row label column now auto-widens up to 40 chars for project paths.
-
-### Changed
-- `formatTable` takes an optional `groupName` arg so the header column matches
-  the group (e.g. "project", "session").
-
-## [0.3.0] — 2026-04-22
-
-### Added
-- `--summary` flag — single-screen dashboard with shadow cost, top subagent /
-  model / day, cache reuse ratio, and **leverage vs $200/mo Max plan**.
-  This is the killer view for "why install over /cost?"
-- Auto-derived insights footer on the default table:
-  - Top contributor with %
-  - 1h cache spend call-out (when ≥5% of total)
-  - Cache reuse ratio (read/write) with verdict
-  - Monthly $ equivalent + leverage vs Max plan
-- Daily-mode insights: peak day, avg/day, peak/trough variance
-
-### Changed
-- `--by day` polish:
-  - Bar fixed to 40-char width so session counts align in their own column
-  - Brighter cyan (`\x1b[96m`) bar character
-  - Total row separated by horizontal rule, properly aligned
-- Header line now shows period + total + sessions + group count at a glance:
-  `agent-ledger week  2026-04-15 → 2026-04-22  ·  $13,356.27 shadow  ·  217 sessions  ·  7 agents`
-
-## [0.2.0] — 2026-04-21
-
-### Added
-- `--by <subagent|model|day>` flag — group rows by subagent (default), by
-  Claude model, or by date. The `day` mode renders an ASCII bar chart of
-  daily spend, useful for spotting "expensive Tuesdays."
-- Server-tool pricing: `web_search_requests` and `web_fetch_requests` from
-  the `server_tool_use` block are now counted at $0.01/request and surface
-  in a footer row when present.
-- ANSI color output, TTY-aware (NO_COLOR / FORCE_COLOR respected).
-  - Subagent / model / day labels in cyan
-  - Cost amounts color-coded by magnitude (red ≥$1000, yellow ≥$100,
-    green ≥$1, dim <$1)
-  - Total row bolded
-- New tests for server-tool pricing, `--by model`, and `--by day`
-  (22 tests, up from 17).
-
-### Changed
-- `aggregate(turns, from, to)` accepts an optional 4th arg `group: GroupKey`
-  (`'subagent' | 'model' | 'day'`). Default behavior unchanged.
-- `AggregatedRow` now carries `webSearchRequests` and `webFetchRequests`
-  counters; `CostBreakdown` adds `serverToolUseCost`.
-
-### Not yet
-- Calibration against real Anthropic invoices (need volunteers — see
-  `.github/ISSUE_TEMPLATE/`)
-- Cost forecasting (trailing 7-day burn rate)
-- Homebrew tap
-
-## [0.1.0] — 2026-04-21
-
-Initial public release.
-
-### 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
-- Published to npm as `claude-agent-ledger`

package/CONTRIBUTING.md

@@ -1,42 +0,0 @@
-# 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/bun.lock

@@ -1,24 +0,0 @@
-{
-  "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/test/aggregator.test.ts

@@ -1,75 +0,0 @@
-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);
-	});
-
-	test('--by model groups by model id', 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, 'model');
-
-		// Fixture has assistant turns with claude-opus-4-7 model
-		const labels = report.rows.map((r) => r.subagent);
-		expect(labels.some((l) => l.includes('claude-') || l === '(no-model)')).toBe(true);
-	});
-
-	test('--by day groups by ISO date and sorts chronologically', 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, 'day');
-
-		// Each row label should look like a date YYYY-MM-DD
-		for (const row of report.rows) {
-			expect(row.subagent).toMatch(/^\d{4}-\d{2}-\d{2}$/);
-		}
-		// Ascending date order
-		for (let i = 1; i < report.rows.length; i++) {
-			expect(report.rows[i - 1]!.subagent <= report.rows[i]!.subagent).toBe(true);
-		}
-	});
-});

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

@@ -1,2 +0,0 @@
-{"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

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

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

@@ -1,2 +0,0 @@
-{"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

@@ -1,6 +0,0 @@
-{"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

@@ -1,55 +0,0 @@
-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

@@ -1,144 +0,0 @@
-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);
-	});
-
-	test('server_tool_use: web_search at $0.01/req', () => {
-		const cost = costFor(
-			{
-				input_tokens: 0,
-				output_tokens: 0,
-				server_tool_use: { web_search_requests: 100 },
-			},
-			'claude-opus-4-7',
-		);
-		// 100 × $0.01 = $1.00
-		expect(cost.serverToolUseCost).toBeCloseTo(1.0, 6);
-		expect(cost.totalCost).toBeCloseTo(1.0, 6);
-	});
-
-	test('server_tool_use: web_fetch counted, summed with web_search', () => {
-		const cost = costFor(
-			{
-				input_tokens: 0,
-				output_tokens: 0,
-				server_tool_use: { web_search_requests: 50, web_fetch_requests: 50 },
-			},
-			'claude-opus-4-7',
-		);
-		expect(cost.serverToolUseCost).toBeCloseTo(1.0, 6);
-	});
-
-	test('server_tool_use absent → no cost', () => {
-		const cost = costFor(
-			{ input_tokens: 1000, output_tokens: 1000 },
-			'claude-opus-4-7',
-		);
-		expect(cost.serverToolUseCost).toBe(0);
-	});
-});

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "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/**/*"]
-}