CodeBurn: a local ledger for AI coding spend across 41 tools

The bill tells you the total, CodeBurn tries to tell you the split

Provider dashboards answer one question well: how much did this cost. They are much worse at the question engineers actually ask, which is why this month cost that much. CodeBurn's premise, stated in the README, is that the bill never tells you that half of your spend went to conversation instead of code, or that an expensive model burned budget on work a cheaper one would have handled in one shot.

The tool is aimed at developers who pay for more than one AI coding product at once. The README lists 41 supported tools and agents, with Claude Code, Cursor, Codex and Gemini named as examples, and the package keywords mention Claude Code, Cursor, Codex, Kimi, Devin, IBM Bob, OpenCode, Pi, Codebuff, CodeWhale and DSH. That list is the audience definition: people whose spend is spread across several vendors and whose only current view is a set of unrelated invoices.

The breakdown dimensions are task, model, tool and project. Project-level attribution is the part provider dashboards structurally cannot do, because they see an API key, not a working directory.

It reads session files instead of intercepting traffic

The design decision that matters is the absence of a proxy. The README states that CodeBurn runs locally with no wrapper, no proxy and no API keys, and that everything reads the session files the tools already write to disk. The four surfaces it ships, desktop, web, terminal and menubar, are described as one source of truth over those same files.

That has a direct consequence for accuracy. Because CodeBurn reconstructs usage after the fact, it can only see what a tool decided to persist. If a tool writes a session record without a model identifier, or rotates its logs, or keeps state in a remote service, CodeBurn has nothing to read. The README does not document a fallback for that case. It also means the tool cannot attribute spend from a tool that never writes local session data at all.

Pricing is the other half of the mechanism. The README says pricing comes from LiteLLM and is refreshed daily. A daily refresh is a reasonable middle ground between a hardcoded table and a live lookup, but it does mean a newly released model can be priced at whatever LiteLLM last published, and a local cache refresh is a network operation even though the analysis itself is not.

Installing CodeBurn and reading your first month

The fastest path requires no installation. The README gives this as the 30-second version: it opens an interactive dashboard, defaulting to today, or to the last 7 days when today has no usage yet, with arrow keys to switch periods and `q` to quit.

npx codeburn

For a permanent command, the README documents a global npm install, and notes that `bunx codeburn` and `pnpm dlx codeburn` also work, with `brew install codeburn` on macOS.

npm install -g codeburn

The stated requirement is Node.js 22.13+ and at least one supported tool with session data on disk. For Cursor and OpenCode, the README says `better-sqlite3` installs automatically, which is worth knowing if your environment blocks native module builds.

The first genuinely useful command is not the dashboard but the overview, because it produces text you can paste somewhere. The README shows a range form and a plain-text flag, and notes that color drops automatically when output is not a terminal.

codeburn overview --from 2026-06-01 --to 2026-06-15
codeburn overview --no-color

What you should see is a summary block with totals for cost, tokens, calls and sessions, a cache hit figure, a by-tool table with cost, tokens and share, then top models, highest-value days, top projects, a per-day table, activity and tool usage. The README's own sample output shows a month at $2,795.10 across 3.49B tokens, with claude at 95% share and codex at 4%. Treat that as a formatting example, not a benchmark.

optimize scans for waste, and its scope is narrower than the headline

The `optimize` command is where CodeBurn stops reporting and starts diagnosing. The README shows a default 30-day scan with period and provider filters, plus a JSON output mode.

codeburn optimize
codeburn optimize -p week
codeburn optimize --provider claude
codeburn optimize --format json

According to the README, the command scans sessions and the `~/.claude/` directory for waste patterns, and it explicitly restricts part of that analysis: for Claude Code, the optimize session count, per-session findings, coaching and model-default recommendations use user-started main sessions, and subagent sidechain transcripts are excluded. That exclusion is a real analytical boundary. If a large share of your Claude Code spend happens inside subagents, the optimize findings will not account for it, even though the overview totals may.

The `--format json` flag is the integration point worth noting. It returns setup health and findings as JSON, which is what you would feed into a script or a CI check rather than read by eye.

Where CodeBurn is the wrong tool

The local-first design is also the main limitation. There is no server component described in the README, so there is no way to aggregate spend across a team from one place. If you need to answer what the department spent on AI this quarter, you are collecting per-machine output yourself.

Coverage is the second boundary. A 41-tool list sounds broad until you check it against your own stack. The README names the tools it integrates; anything outside that list contributes nothing, and the tool gives no indication that spend is missing rather than zero. A quiet month in CodeBurn can mean a cheap month or an unparsed tool, and the documentation does not describe a warning for the second case.

Third, the numbers are reconstructed, not metered. They are derived from session files and priced from a third-party catalogue. That is good enough for finding that 95% of spend sits in one tool, and not good enough to be the number you forward to finance without a reconciliation step.

Finally, if you only use one AI coding tool and your provider already breaks spend down by model, CodeBurn adds a second view of the same data. The project breakdown is the part that would still be new.

CodeBurn against a gateway proxy like LiteLLM

The obvious alternative is a proxy or gateway that sits between your tools and the model APIs and meters every request. LiteLLM is the concrete comparison here, because CodeBurn already depends on it for pricing: the README states pricing comes from LiteLLM and is refreshed daily, so the two projects are adjacent rather than unrelated.

The difference in approach is where the data comes from. A gateway sees traffic it routes, which means complete per-request accounting, real-time budget enforcement and cross-user aggregation, at the cost of changing how your tools authenticate and where requests go. CodeBurn sees files it reads, which means no configuration change to any tool and no traffic leaving the machine, at the cost of depending on each tool's log format and having no way to block a request.

If your requirement is to stop overspend as it happens, a gateway is the right shape and CodeBurn is not. If your requirement is to understand last month's spend without touching how any tool is configured, reading local files is the lower-friction route.

Licence, upgrade cost and what the repository shows

CodeBurn is MIT licensed, with the LICENSE file at the repository root and a THIRD_PARTY_NOTICES.md shipped in the published package. The README also notes that pricing data is sourced from LiteLLM, which carries its own licence, so redistributing or embedding CodeBurn means checking that dependency's terms separately. This is a description of what the files say, not legal advice.

Upgrade cost looks low by construction. The CLI is distributed through npm and runs from `npx`, so there is no migration step for the terminal path. The desktop and menubar builds are separate release artifacts under their own tags, which the release list shows as `desktop-v0.9.23`, `mac-v0.9.23` and `windows-v0.9.23`, all dated 2026-08-29. That means the CLI, the desktop app and the platform tray apps can version independently, and a fix in one does not automatically reach the others.

On maintenance: the repository is not archived, and the last push was on 2026-08-29. The release list shows v0.9.23 on the same date, while package.json declares version 0.9.24, so the published manifest is one patch ahead of the newest tagged release in the list. The repository also carries a RELEASING.md runbook and a `.release-0.9.21-runbook.md` at the root, plus an `npm run verify:upgrade` script, which suggests upgrade paths are tested deliberately rather than assumed.

Editorial conclusion

Adopt CodeBurn if you already run several AI coding tools and want a per-project, per-model cost breakdown without routing traffic through a proxy; the CLI path needs only Node.js 22.13+ and existing session data. Skip it if your tools store sessions in a format the repository does not parse, or if you need hosted, multi-user reporting, since everything here is single-machine and file-based. Before trusting a number, run `codeburn overview --no-color` for one month and reconcile the totals against a provider invoice; if they diverge, check whether that tool's session files are actually on disk and whether the LiteLLM pricing entry for the model you used is the one you were billed against.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes