burn local-first · zero-deps · MIT

the local cost ledger for AI coding agents

See what each feature actually cost.

burn reads the transcripts your agents already write to disk — Claude Code, OpenCode, Codex, Gemini CLI — and adds it up per repo, model, day and git branch. Honest about every dollar. Nothing leaves your machine.

Install burn Get the source Read the protocol
~/project — burn
$ burn claude-code, opencode · 118 events $40.08 spent 18.28M tokens cache 50% ──────────────────────────────────────────── 28 billed · 90 estimated cost events By repository ──────────────────────────────────────────── acme/analytics ██████████████ $40.08 225k acme/api ·············· $0.00 222k pet-habit ·············· $0.00 15.88M
Actual output — every figure traced to a real transcript on the machine. Repo names shown redacted.
Tracked across
4 agents
Cost provenance
3 classes
Runtime dependencies
0
Network calls in core
none
Tests · protocol vectors
75 / 8

What it answers

burn blame · work · doctor · plan

Every agent quietly logs exactly what it did. Nobody adds it up across tools, and nobody can tell you what feature/payments-refactor actually cost. burn turns that pile of JSONL and SQLite into a ledger.

Per repo, model, day
Spend broken out by repository and model over time. burn repos burn daily
Dollars per work unit
Joins usage to your git history — explicit marks, branch names, then repo fallback — so you see cost per feature or PR. burn work burn blame HEAD~3..HEAD
Cache & waste, surfaced
Prompt-cache hit rate per repo, and a burn doctor that flags paying top-tier prices for tiny turns.
Budgets that fail loudly
Set a ceiling and burn exits non-zero when a repo blows past it — a gate a CI job or AgentVault can catch. burn budget --repo X --max 50
Durable, mergeable history
Snapshot the ledger, merge exports from other machines or agents, and project when your spend runs out — with no double-counting by construction.

Never invents a dollar

R1 · R2 · R3

The whole point of a ledger is trust. Every cost event carries a provenance class, and burn will not quietly turn tokens into money.

billed

Actually charged

A price the tool recorded itself — OpenCode's real billed cost. Shown as-is, no estimate layered on top.

estimated

List-price derived

Tokens you have, multiplied by an editable price table. Recomputable — the pricingHash makes it reproducible years later.

unpriced

Tokens only

Models burn can't price honestly are counted in tokens and deliberately left out of dollar totals. No guess.

The rule is absolute: if burn can't price it, it won't say a number. Unpriced events report tokens, never dollars.

The ledger is a protocol, not a file format

github.com/aashish254/ulp

burn grew ULP — the Usage Ledger Protocol: a tiny, privacy-first JSON format any tool can emit and any team can merge across machines, with no server, account, or network. Two independent implementations must pass the same pure-JSON vectors before a version is ratified.

// one ULP 1.0 usage event — dollars only where they're real
{
  "agent": "claude-code",
  "sessionId": "a9c0…",
  "index": 7,
  "model": "claude-opus-4",
  "repo": "analytics",        // basename, never a path
  "date": "2026-09-13",
  "tokens": { "input": 113431, "output": 111193 },
  "cost": 1.84,
  "costSource": "estimate",   // billed | estimate | unpriced
  "pricingHash": "ad4e736afce6"
}
Example of one ULP 1.0 usage event in JSON.
2
reference impls
Node · stdlib Python
8
conformance vectors
both languages green
1.0
ratified
union identity, no double-count
Read ULP 1.0 Conformance kit

Extensions live under x-<impl>-* namespaces. Core fields are additive-only across 1.x.

Install in one paste

macOS or Linux with Node ≥ 22.5. The script downloads a checksum-verified release, links burn into ~/.local/bin, and touches nothing else. No account, no telemetry, no root.

curl -fsSL https://raw.githubusercontent.com/aashish254/burn/main/install.sh | bash
  1. 01Paste the command above — it installs burn in a few seconds
  2. 02Run burn — it auto-discovers your Claude Code, OpenCode, Codex & Gemini logs on disk
  3. 03Read your ledger: burn · burn work · burn doctor
your terminal
$ burn 🔥 burn local AI usage ledger claude-code, opencode · 118 usage events $40.08 spent 18.28M tokens cache 50% $ burn work main ████████████████████ $40.08 [branch] 105k tok

Prefer to build from source? git clone https://github.com/aashish254/burn && cd burn && npm link — or just run node src/cli.js from the checkout. An npm package is on the roadmap; until then these are the two official routes.