CodeBurn: A Local Token and Cost Tracker That Reads Your AI Tools' Session Files

The Problem: Your AI Bill Is a Black Box

If you pay for Claude Code, Cursor, Codex, or any of the dozens of AI coding tools, your monthly invoice shows a single total. It does not break that down by project, by model or by task, and it does not show which part of it was wasted. CodeBurn addresses this by reading the session files those tools already write to disk. It breaks down every token and dollar by project, model, branch, and task, across 31 AI tools and agents. The target user is a developer or team lead who wants to understand where AI spend actually goes, without adding a proxy or wrapper that intercepts traffic. There is no account and no sign-up, and CodeBurn looks in the folders your tools already write to. package.json includes a bundle-litellm script, so pricing data appears to come from LiteLLM.

How CodeBurn Reads Your Data: Session Files, Not Proxies

The core mechanism is straightforward: CodeBurn reads the session files that your AI tools already write to disk. This is a local-first approach, distinct from proxy-based trackers that sit between you and the AI provider. The README says the desktop app, menu bar, Capacity Dock and glance card all read the same files on your disk. That means there is no wrapper or proxy involved. The tool aggregates this data to show totals, breakdowns by tool and model, and per-project or per-task views. One consequence is that tracking is only as current as the last time your tools wrote session files. If a tool buffers writes or stores data in a proprietary format, CodeBurn may not see the latest activity.

Getting Started: Four Surfaces, One Command

The quickest way to try CodeBurn is `npx codeburn`, which opens an interactive terminal dashboard. Arrow keys switch periods, and `q` quits. For a permanent command, install globally with `npm install -g codeburn`. You can also install it with `brew install codeburn`. Beyond the terminal, there are three other surfaces: a web UI launched with `npx codeburn web`, a desktop app with installers for macOS, Windows, and Linux (AppImage, deb, rpm), and a menubar app for macOS and Windows, started with `codeburn menubar`. On Linux, a GNOME Shell extension puts it in the top panel. The requirement is Node.js 22.13+ and at least one supported tool with session data on disk.

Finding Waste: The Optimize Command

The `codeburn optimize` command reads your sessions and your config, then lists what costs tokens without earning them. The README gives examples such as a file the agent re-reads on every turn, an MCP server that is installed but never called, and a `CLAUDE.md` long enough to ride along in every request. Each finding comes with a grade, the fix, and what that fix should save over the period scanned. `codeburn optimize --apply` reviews and applies the changes, backing files up first, and `codeburn act undo --last` puts them back.

Limitations and Wrong Tool Cases

Because CodeBurn reads session files, its token and cost figures only reflect what tools have written to disk. It also depends on the tools it supports; if you use a niche agent that is not supported, it will not track it. The README says 42 integrations while the repository description says 31 tools and agents, so verify the current count. Another limitation is that cost accuracy relies on LiteLLM pricing. If your provider charges custom rates or you have negotiated discounts, the displayed cost may not match your actual bill. The tool also requires Node.js 22.13+, which may be a barrier on older systems.

Alternatives: Proxy-Based Trackers vs. Local Parsing

The main alternative to CodeBurn is a proxy-based tracking tool, such as LiteLLM's proxy or a commercial offering like Helicone. These tools sit between your AI client and the provider, capturing every request in real time. They can provide live dashboards, alerting, and per-request logging, but they require you to change your API endpoint configuration and route traffic through their servers, which introduces latency and a potential single point of failure. CodeBurn's approach is the opposite: it parses local session files after the fact, so there is no runtime overhead. The trade-off is that you lose real-time visibility and you are limited to what the session files contain. CodeBurn also has an opt-in `codeburn guard install` that adds Claude Code hooks to warn a session once it passes $5 and stop it at $15, so spending caps are possible for Claude Code. If you want a zero-config, privacy-preserving retrospective analysis, CodeBurn's local parsing is simpler.

Maintenance, License, and Upgrade Cost

The project is MIT-licensed, which means you can use, modify, and distribute it freely, including in commercial products, with no copyleft obligations. The repository is active, with a recent release 0.9.27 on 2026-10-11 (package.json is at 0.9.27), with separate release tags for desktop, Windows menubar and macOS menubar builds. The last push was on 2026-11-02. Maintenance cost for you is low: the tool is installed via npm, and you can update with `npm update -g codeburn`. The main upgrade consideration is that session file formats may change as AI tools evolve, and CodeBurn must keep pace. The README mentions 42 integrations, and the project asks for sponsorship to 'keep 42 integrations honest,' implying ongoing maintenance is a real burden. You should check the changelog for each release to see if your tools' formats are still supported. The desktop and menubar apps ship as separate releases (desktop, mac and windows tags), so you may need to update those independently.

Editorial conclusion

Adopt CodeBurn if you use Claude Code, Cursor, Codex, or similar tools, need a local, no-proxy way to see token and cost breakdowns by task, model, and project, and are comfortable with Node.js 22.13+ and the fact that it reads session files from disk. Avoid it if you require real-time tracking, as it only reflects what tools have written to disk, or if you rely on unsupported tools. Before adopting, verify that your specific tools are among the supported tools, check that the session file formats are compatible with your versions, and test the `npx codeburn` command to ensure the interactive dashboard works in your terminal. Also, check that the prices CodeBurn applies match your actual billing rates.

Frequently asked questions

Official sources

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