# Claude Agent Ledger

> Per-subagent cost attribution for Claude Code. Reads local JSONL session logs, computes shadow cost at marginal Anthropic API rates with proper TTL pricing.

- **Type:** MCP server
- **Install:** `agentstack add mcp-xjm-free-claude-agent-ledger`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [XJM-free](https://agentstack.voostack.com/s/xjm-free)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [XJM-free](https://github.com/XJM-free)
- **Source:** https://github.com/XJM-free/claude-agent-ledger
- **Website:** https://jiexiang.dev

## Install

```sh
agentstack add mcp-xjm-free-claude-agent-ledger
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# claude-agent-ledger

> See exactly where your Claude Code budget goes — per subagent, per model, per day.

[](https://www.npmjs.com/package/claude-agent-ledger)
[](LICENSE)

> *Even I needed `--anonymize` before posting my own data publicly.
> That's why the flag exists. Use it before you screenshot.*

---

## 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 model (Opus / Sonnet / Haiku) ate the budget
- Which day of last week was the expensive one
- 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.

`claude-agent-ledger` reads Claude Code's local session logs and gives you a per-subagent ledger. That's it.

## Install

```bash
npm install -g claude-agent-ledger
# or: bun install -g claude-agent-ledger

agent-ledger week --summary        # the dashboard (start here)
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            # heuristic: top-3 turns + tool/model breakdown
ANTHROPIC_API_KEY=sk-ant-... agent-ledger explain 
                                            # LLM mode: Haiku 4.5 ≤4-bullet root cause (~$0.001/run)
```

No server. No account. No data leaves your machine.

## Why this and not `/cost`?

Claude Code's built-in `/cost` shows the **current session** cost. That's it.

`claude-agent-ledger` answers questions `/cost` can't:

- Which of my **10+ subagents** burned the budget? (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)
- What's the **leverage** I'm getting from my $200/mo subscription? (e.g. 250×)

Run `agent-ledger week --summary` once and decide.

## Example output (real, from the author's machine)

### `--summary` (the dashboard)

```
agent-ledger week summary  2026-04-15 → 2026-04-22

  Shadow cost           $13,450.05
  Sessions              219
  Projects              9
  Plan reference        $200/mo (Max)
  Multiplier            252× vs Max plan

  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

  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
```

### Default — by subagent

```
agent-ledger week · 2026-04-14 → 2026-04-21

  subagent              sess      tokens(in/out)         cache tokens (1h/5m/read)       cost
  ───────────────────────────────────────────────────────────────────────────────────────────
  (main)                  28       514K / 15.87M  1h:116.10M 5m:      0 r:5229.48M  $12524.97
  general-purpose        148         113K / 955K  1h:      0 5m: 20.67M r: 183.94M    $599.97
  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                  216       916K / 17.57M  1h:116.10M 5m: 26.62M r:5495.71M  $13172.14
```

### `--by model`

```
  subagent              sess      tokens(in/out)         cache tokens (1h/5m/read)       cost
  ───────────────────────────────────────────────────────────────────────────────────────────
  claude-opus-4-7         16        59K / 8.35M   1h: 61.15M 5m:  2.32M r:2974.59M   $6967.29
  claude-opus-4-6        127       544K / 8.25M   1h: 55.02M 5m: 13.30M r:2422.18M   $6160.46
  claude-sonnet-4-6       65        135K / 946K   1h:      0 5m:  8.81M r:  98.12M     $77.07
  claude-haiku-4-5        13        178K /  67K   1h:      0 5m:  2.19M r:  21.57M      $4.33
```

### `--by day` (ASCII bar chart)

```
  2026-04-15   $3749.84  ████████████████████████████████████ (18 sess)
  2026-04-16   $2492.99  ████████████████████████             (175 sess)
  2026-04-17   $2111.63  ████████████████████                 (9 sess)
  2026-04-18   $1840.02  ██████████████████                   (18 sess)
  2026-04-19    $644.97  ██████                               (5 sess)
  2026-04-20   $1095.58  ███████████                          (6 sess)
  2026-04-21   $1273.55  ████████████                         (9 sess)
```

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. 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
- Justifying a Max subscription internally ("our shadow cost is $13K/wk, Max is $200/mo — that's a 65× discount")

If you're on pay-as-you-go, the `cost` column is roughly your bill (±5–10% depending on tier / geography / `server_tool_use` calibration).

## How it works

Claude Code writes every conversation turn to `~/.claude/projects//*.jsonl`.
Each turn records input/output tokens, cache tokens (with TTL split), the model used,
and any `server_tool_use` (web_search / web_fetch) requests. Subagent invocations live
under `/subagents/agent-*.jsonl`, with a sidecar `.meta.json` carrying the real
subagent name (e.g. `Reality Checker`, `ios-factory`).

`claude-agent-ledger` walks the tree, resolves subagent types from the sidecar metadata,
and aggregates by your chosen key (subagent, model, or day). 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). `claude-agent-ledger` breaks them out explicitly — see `src/pricing.ts`.

### Server tool pricing

`web_search_requests` and `web_fetch_requests` are counted at $0.01/request and shown in a footer when present:

```
  server tools: web_search ×7, web_fetch ×0  ($0.07)
```

If Anthropic's actual rate differs (or web_fetch has its own price), open an issue.

## Flags

| Flag | What it does |
|---|---|
| `--summary` | One-screen dashboard with all the headline numbers |
| `--by ` | Group rows. Default: `subagent`. `day` renders as ASCII bar chart. |
| `--anonymize` | Replace project paths and session ids with `~/repo-A`, `sess-A`, ... so you can share screenshots without doxing your employer / private repos. |
| `--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 |

| Env | What it does |
|---|---|
| `NO_COLOR=1` | Disable ANSI colors |
| `FORCE_COLOR=1` | Force ANSI colors when piping |

## What it's not

- Not a real-time dashboard (post-hoc log reader)
- Not a tracker for direct Anthropic API calls (those logs live server-side)
- 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 on Claude Max and want to know what your "free" usage is worth
- You're building AI Agent systems and want observability primitives, not vendor dashboards

## Status

`v0.2.0` shipped 2026-04-21. Validated on ~200K turns of real Claude Code logs.
Pricing 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` calibration). Calibration PRs welcome — see issue
templates.

- [x] Log parser (JSONL streaming, recursive subagent discovery)
- [x] Per-subagent aggregation
- [x] Per-model aggregation (`--by model`)
- [x] Per-day aggregation with bar chart (`--by day`)
- [x] Terminal table + Markdown + JSON output
- [x] ANSI color, TTY-aware
- [x] Cache 1h/5m TTL split pricing
- [x] `--plan pro|max` to mask shadow cost
- [x] `server_tool_use` pricing (web_search, web_fetch)
- [ ] Cost forecasting (trailing 7-day burn rate)
- [ ] Calibration against real Anthropic invoices
- [ ] Homebrew tap

## Install from source

```bash
git clone https://github.com/XJM-free/claude-agent-ledger.git
cd claude-agent-ledger
bun install
bun link
agent-ledger today
```

## Development

```bash
bun test           # 22 pass, 0 fail
bun run typecheck
```

## Author

Built by [@XJM-free](https://jiexiang.dev) while running seven production Claude Code
subagents for infrastructure work. More context coming on the blog.

## License

MIT.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [XJM-free](https://github.com/XJM-free)
- **Source:** [XJM-free/claude-agent-ledger](https://github.com/XJM-free/claude-agent-ledger)
- **License:** MIT
- **Homepage:** https://jiexiang.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-xjm-free-claude-agent-ledger
- Seller: https://agentstack.voostack.com/s/xjm-free
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.