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 tell you that half the spend went to conversation instead of code, or that an expensive model burned budget on a task a cheaper one could have finished in one shot. CodeBurn addresses this by reading the session files those tools already write to disk. It breaks down every token and dollar by task, model, tool, and project, across 41 AI tools. 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. The tool runs entirely locally, with no API keys, and nothing leaves your machine. Pricing data comes from LiteLLM, refreshed daily, which is a practical but external dependency for cost accuracy.

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 states that 'everything reads the session files already on your disk.' That means there is no wrapper, no proxy, and no API keys involved. For Cursor and OpenCode, the tool installs `better-sqlite3` automatically to read their databases. For Claude Code, it scans the `~/.claude/` directory for session data. 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. The documentation does not specify how often it refreshes, so you should expect a slight delay between a session ending and it appearing in the dashboard.

Getting Started: Four Surfaces, One Command

The quickest way to try CodeBurn is `npx codeburn`, which opens an interactive terminal dashboard. It shows today's usage by default, or the last 7 days if today has no usage yet. Arrow keys switch periods, and `q` quits. For a permanent command, install globally with `npm install -g codeburn`. It also runs via `bunx codeburn` or `pnpm dlx codeburn`, and on macOS you can `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. The `overview` command prints a copy-pasteable summary with totals, breakdowns by tool and model, highest-value days, and a per-day table. You can restrict by date range with `--from` and `--to`, or use `-p all` for the last 6 months and `-p lifetime` for full history.

Finding Waste: The Optimize Command

The `codeburn optimize` command scans the last 30 days by default and looks for waste patterns in your sessions and your `~/.claude/` setup. You can restrict it to a period with `-p today` or `-p week`, or to a single provider with `--provider claude`. The output includes setup health and findings, and you can get it as JSON with `--format json`. For Claude Code, the optimize command focuses on user-started (main) sessions, excluding subagent sidechain transcripts. This is a deliberate choice: sidechain activity is often noise. The findings likely include cases where an expensive model was used for a task a cheaper one could handle, or where conversation consumed tokens without producing code. The README suggests you can 'find and fix waste,' implying the tool offers recommendations, but the truncated material does not detail what those fixes are. That is a gap worth checking before relying on it for cost reduction.

Limitations and Wrong Tool Cases

CodeBurn is not a real-time monitor. Because it reads session files, it only reflects what tools have written to disk. If you need live token counting during a session, this is the wrong tool. It also depends on the 41 supported tools; if you use a niche agent not on the list, it will not track it. The README mentions 41 integrations, but the description says 31 in the repository metadata, so verify the current count. Another limitation is that cost accuracy relies on LiteLLM pricing, which is refreshed daily. 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. For Cursor and OpenCode, it installs `better-sqlite3`, a native module that could fail on some platforms without build tools. Finally, the optimize command's recommendations are not fully documented in the provided material, so you may need to run it to see what it actually suggests.

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 and no data leaves your machine. The trade-off is that you lose real-time visibility and you are limited to what the session files contain. If you need to enforce budget caps in real time, a proxy is a better fit. 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 v0.9.23 on 2026-08-29, and separate release tags for Windows and macOS menubar builds. The last push date matches the release date, suggesting regular updates. Maintenance cost for you is low: the tool is installed via npm, and you can update with `npm update -g codeburn` or by rerunning `npx codeburn` (which fetches the latest). The main upgrade consideration is that session file formats may change as AI tools evolve, and CodeBurn must keep pace. The README mentions 41 integrations, and the project asks for sponsorship to 'keep 41 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 web and menubar surfaces are separate binaries, 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 41 supported, 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, review the LiteLLM pricing source to confirm it matches your actual billing rates, since cost accuracy depends on that data.

Official sources

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