burn CLI
A local CLI that totals tokens and dollars per repo, branch and model from Claude Code, Codex and OpenCode transcripts
- 91 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The CLI reads local agent transcripts that may contain code and prompt fragments and writes history to `~/.burn`, using no network.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/aashish254/burn/main/install.sh | bashThe first README command: the installer verifies the release checksum and installs the CLI into `~/.burn-cli`.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The CLI reads local agent transcripts that may contain code and prompt fragments and writes history to `~/.burn`, using no network.
This is third-party code. Review the repository files before installing.
What it does
burn reads the transcripts agents already keep on disk and adds up the spend. `burn` shows spend per repo, model and day, `burn work` prices a feature by branch, `burn blame feature/pay` costs a single branch and `burn doctor` looks for wasted money. There is a `burn forecast`, a `burn budget` limit that exits with code 3 when exceeded, and a `burn report` in Markdown. Claude Code, OpenCode, Codex CLI and Gemini CLI are supported. No network, account or telemetry is needed. Prices come from the `~/.burn/pricing.json` table, and when a model is missing, burn shows tokens and a dash in place of cost. Teams get export and merge of data, and the ledger format is open as the ULP 1.0 protocol.
Who it is for. Developers and teams who want to know what agent work costs per repo and branch without sending data to a cloud.
Good fit when
- The token bill grew and you need the repo or branch that took the money
- CI checks that a pull request stayed within budget using exit code 3
- A team gathers spend per person with no server through `burn export`, `merge` and `team`
- You want a forecast of next month spend at the current pace
Not a fit when
- The agent leaves no local transcripts, such as a cloud service with no files on disk
- You need the exact amount from a provider invoice, while burn shows an estimate from your price table
- You want to cap spend on the fly, as burn measures and checks budgets but blocks nothing
Example request
Run `burn work` and show what the feature/payments-refactor branch cost over the last weekLimitations
Node.js 22.5 or newer with built-in `node:sqlite` is required, and macOS and Linux are supported. Installation is through `curl ... | bash`: the script verifies the release checksum, but read it before running. There is no npm package yet. Cost is mostly an estimate from the price table, and the actual billed amount comes only from OpenCode. Cursor is listed as planned and OpenClaw is held until its format is confirmed.
How to disable. Delete the `~/.burn-cli` directory and the `burn` link in `~/.local/bin`. Accumulated history in `~/.burn` is removed separately.
FAQ
How do I install burn?
Run `curl -fsSL https://raw.githubusercontent.com/aashish254/burn/main/install.sh | bash`. The alternative is `git clone https://github.com/aashish254/burn && cd burn && npm link`.
Where does burn get its data?
From local agent files: Claude Code keeps JSONL in `~/.claude/projects`, OpenCode a SQLite database, and Codex and Gemini CLI their own logs. `burn sources` shows what was found.
Does any data leave the machine?
No, there are no network calls, account or telemetry. A shareable export is a file made with `burn export -o me.burn.json`.
How does burn differ from ccusage?
burn ties spend to branches and work, and supports budgets with CI exit codes and team data merging. ccusage focuses on usage reports.
How do I cap spend in CI?
Run `burn budget --repo app --max 25`: when the limit is exceeded the exit code is 3, so CI can tell a budget breach from a tool crash. burn itself blocks nothing.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI and MCP server that tally token spend across 41 tools and agents, break it down by project and model, and help cut wasted tokens
Token and cost reports for Claude Code, Codex, Gemini CLI and other agents from local logs, by day, month and session
TokenTracker counts tokens and spend across Claude Code, Codex, Cursor, Gemini CLI and other agents from local logs and shows them on a local dashboard
A local CLI that shows where tokens go in Claude Code, Codex and opencode and holds back expensive messages
A limits and token spend monitor for Claude Code, Codex, Antigravity and Grok CLI: macOS menu bar, Windows tray, HTML reports
Tokdash shows token usage and session cost for Claude Code, Codex, Gemini CLI and a dozen more agents locally
README in short
The README explains why to track agent spend by branch, gives installation, the cost rules with three kinds of amounts (billed, estimated, unpriced), speed benchmarks and the lists of commands and supported agents.