token-ledger

token-ledger shows what each turn costs and how much of it the cache absorbed. A line pinned under the Claude Code prompt carries the session cost, the last turn’s cost and tokens, and the cache hit ratio. /ledger opens a pane with one row per turn.

What it does

• The pinned line updates when a turn ends: session cost, the last turn’s cost, its tokens in and out, and the cache share. in on the line counts fresh input, cache reads and cache writes together, and cache is the part of that read from the cache. A figure the engine does not have is left out.
• The /ledger pane lists turns newest first: turn number, model, input tokens (fresh input only, here), output, cache reads, cache writes, hit ratio, duration and cost, with a totals row and the engine’s session total underneath. Run /ledger again to close it.
• When the pane is too narrow, columns drop in this order: duration, cache writes, turn number, model, hit ratio, cache reads, output, input. Cost is never dropped.
• Subagent turns get their own rows, marked with * and drawn dim.

Install

Needs Claude Code 2.1.287 or later.

claude plugin marketplace add Arunjay4213/claude-mods
claude plugin install token-ledger@claude-mods

claude-mods is the author’s marketplace, not this site; it also carries context-lens and quota-meter. The line is pinned when the session starts and fills in after the first turn. Run /ledger for the table.

How it works

Token counts, the model name and the duration come straight from the turn.complete event: they are the API’s own figures for that turn, not an estimate. The cache hit ratio is cache reads over everything the turn was read from (fresh input, cache reads and cache writes); when that is zero the cell shows -.

Cost is a difference, not a price list. The mod reads cost.usd from $.session.usage() at session start and after every turn, and a turn’s cost is how much that figure moved. There is no pricing table in the plugin, so it cannot quote a rate that went stale; it only repeats what the engine already priced.

The ledger keeps the last 200 turns in memory and mirrors them into $.store under the session id, so /ledger still has the history after /resume. A new session or a /clear starts empty rather than showing another transcript’s turns. The mod makes no network calls and sends nothing to the model.

Limitations

• A turn is priced only once a baseline exists, and the first reading is taken at session.start. Where the host reports no cost, the cost column shows - and the line drops the dollar figures.
• Cost lands on whichever turn finished between two readings. A subagent that finishes inside the main turn takes that cost, and the main turn’s row shows what was left.
• The pane draws the newest 40 rows; older turns still count in the totals. Dollar figures are rounded (2 decimals from $1, 4 below it), so the totals row can differ from the engine’s session total by a fraction of a cent.
• The pane docks beside the transcript from 110 columns and sits inline above the prompt below that. The author documents terminal sessions only.