Local-first cost ledger for AI coding agents. Node 22.5+, zero dependencies, no network.
$ brew install garyleelty/agentledger/agentledger $ npm install -g git+https://github.com/garyleelty/agentledger.git $ agentledger agentledger — 231 session files scanned Metric Tokens Est. cost ───────────── ─────── ───────── Input tokens 335.96M $826 Cache read 2.73B $344 Cache write 366.4k $0.0842 Output tokens 11.31M $64.66 TOTAL 3.08B $1235 Agent Tokens Est. cost Records ─────────── ─────── ───────── ─────── dsh 1.57B $939 7004 codex 219.45M $193 3059 opencode 291.09M $25.42 4298 claude-code 205.05M $2.24 1462 cherry-studio 765.8k $2.11 29 openclaw 31.39M $1.28 959 kilo 3.32M $0.3186 103 pi 47.7k $0.0000 5
A real run on the machine it was written on. Nothing had told the author that one Codex session had already burned $118.
# from the release tarball — no npm account, no registry: $ npm install -g https://github.com/garyleelty/agentledger/releases/download/v0.6.0/agentledger-cli-0.6.0.tgz # or straight from the repository: $ npm install -g git+https://github.com/garyleelty/agentledger.git $ npx --package=git+https://github.com/garyleelty/agentledger.git agentledger # or without npm at all: $ curl -fsSL https://raw.githubusercontent.com/garyleelty/agentledger/main/install.sh | sh
Each release attaches its tarball using the repo's own token,
so the first form installs whether or not agentledger-cli is on
the registry (it is not yet — plain npx agentledger-cli still
404s). Node 22.5+.
If you pay per token, your invoice is a lagging indicator — you find out after the money is gone. agentledger answers the question while you are still working: what has this agent, this model, this week actually cost?
~/.claude/projects, ~/.codex/sessions, ~/.local/share/opencode, ~/.local/share/kilo, ~/.dsh/sessions, ~/.openclaw/agents, ~/.pi/agent/sessions, ~/Library/Application Support/CherryStudio/Data, ~/.gemini/tmp, ~/Library/Application Support/CodeBuddy CN/logs, ~/Library/Application Support/Lingma/SharedClientCache/cache/db--prices my-prices.json overrides any model, partial entries merge over the built-in table; prices --template writes the file for you, naming exactly the models your ledger could not pricetools/crosscheck.mjs diffs token totals against ccusage on the same logs (it found four real bugs), and tools/audit_pricing.py diffs every price against the LiteLLM database weekly in CIagentledger blocks groups your usage into the windows a subscription quota resets in, with the active window's burn rate and projection. Every agent, not just Claude Codeagentledger statusline in Claude Code's statusLine hook: live session cost, the active billing block, zero file reads on current payloads| Command | What you get |
|---|---|
agentledger | totals + per-agent breakdown |
agentledger waste | where the cache-read spend is concentrated |
agentledger savings | what prompt caching saved, against no cache |
agentledger by-project | cost per repository |
agentledger by-branch | cost per git branch |
agentledger by-model | which model is eating the budget |
agentledger by-day -d 30 | daily spend curve |
agentledger by-week | the same, rolled up by week |
agentledger by-month | the same, rolled up by month |
agentledger blocks | billing blocks — the windows a subscription quota resets in |
agentledger sessions -n 20 | most expensive sessions |
agentledger budget -b 100 | spend against a limit, with a run rate |
agentledger watch | live totals |
agentledger aggregate | shareable totals — no session ids, no paths |
agentledger json | every record, including session ids |
| Agent | Logs read | Status |
|---|---|---|
| Claude Code | ~/.claude/projects | supported |
| Codex CLI | ~/.codex/sessions | supported |
| OpenCode | ~/.local/share/opencode/opencode.db | supported |
| Kilo | ~/.local/share/kilo | supported |
| DSH (DeepSeek Harness) | ~/.dsh/sessions | supported |
| OpenClaw | ~/.openclaw/agents/*/sessions | supported |
| pi-agent | ~/.pi/agent/sessions | supported |
| Cherry Studio | ~/Library/Application Support/CherryStudio/Data | supported |
| Gemini CLI | ~/.gemini/tmp | supported |
| CodeBuddy CN | ~/Library/Application Support/CodeBuddy CN/logs | supported |
| Lingma (通义灵码) | ~/Library/Application Support/Lingma/SharedClientCache/cache/db | supported |
| Cursor, Aider, Amp… | --path + sniffing | partial |
json is the debugging shape: one row per record, with the
session id in it. On Claude Code and Codex that id names a real log file under
the agent's own directory, so a report built from it maps your projects and
timestamps. aggregate is the shareable one — totals plus
per-agent and per-model groupings, about 3 kB, and it is what the
weekly digest is built from.
paid pre>paid 000
without cache $3853
saved $2854 74.1% cheaper
cache reads 2.73B of 3.08B total tokens (85%)
concentration top 10 of 315 sessions = 75.3% of all cache reads
priciest $118 one Codex session in one repo
branch $206 the web branch alone
Priced the same ledger with every cache-read token billed at its model's
fresh-input rate and caching is worth $2,854 — the tool does not
just report spend, it prices what prompt caching is worth.
agentledger savings prints it. Concentration that high is not
ordinary usage — it is context churn: a long session that keeps re-sending its
prefix, or a tool returning large output every turn. agentledger waste
points at which one.
ccusage is the incumbent and it
covers more agents, prefers Claude Code's own costUSD,
but reports reasoning token counts only — it does not bill them in the
OpenCode or Kilo lanes. If you want the most complete tool, use it.
Where agentledger is now level or ahead: Anthropic's 5-minute vs 1-hour
cache-write TTLs are billed apart (x1.25 / x2) from the nested
cache_creation block when logs carry it; every built-in price is
reconciled against live LiteLLM in a weekly CI job, so a stale
entry fails a build on a schedule instead of waiting on a manual refresh;
savings prices the counterfactual — what this ledger would have cost
with no prompt caching; and DSH (DeepSeek Harness) is a source it cannot read
at all, which on this machine is 1.48B tokens, more than every other agent
combined.
Two of its lanes report $0.00 for every model: OpenClaw's
glm-4.7:cloud and stepfun/…:free are both missing from
its embedded price table, so 31.39M tokens of real spend price to zero there.
agentledger prices glm-4.7:cloud from six LiteLLM vendor rows that
agree exactly on $0.60/$2.20.
The pitch that stays narrower and honest: ~5600 lines, zero dependencies, no network, no build step. You can read the whole thing before you trust it with logs that are effectively your entire coding history.
agentledger is MIT-licensed and free forever. If it saved you a surprise bill, you can send something directly — no account, no signup, no intermediary:
ETH 0xB30a208B84814D3F7091Bb779f2b0225288349aE BTC 1EKTrfpKc7fQwNYUv4oHLa2cna6NqDq3sM
Verify these before sending — the BTC address carries a
base58 checksum and the ETH address an EIP-55 checksum, so a typo will not silently
send funds somewhere else. You can also run python3 tools/tip.py from the
repo to confirm the balance from public endpoints.
These are not just pasted in —
python3 tools/prove_control.py re-derives both from the private key and
signs with it, so you can confirm the addresses are really the project's before sending.
No ads, no paid tier, no license keys. Tipping is the only way this project makes money, and it is entirely optional.