Skip to content
Get packs

Guide · Open source

How to use CodeBurn: track AI coding token costs locally

Updated · written with AI from the project's own documentation and checked against our catalogue data

CodeBurn is a free, local command-line and desktop tool that reads the session files AI coding tools write to your disk, prices every token, and shows where the money went. This guide is for developers who use one or more AI coding tools and want to see their spend by tool, model, project and task. By the end you will be able to run it, read its tables, find config waste with optimize, and track a subscription plan.

CodeBurngetagentseal/codeburn · ★ 11.7k · MIT

Quick start

  1. 1Run it once. Run npx codeburn in your terminal to see today's cost without installing anything.
  2. 2Install it if you want to keep it. Use npm install -g codeburn or brew install codeburn. Node.js 22.13 or newer is required.
  3. 3Read the tables. Look at cost by tool, model, project and task, then use the arrow keys to move between periods.
  4. 4Set your plan. If you pay a subscription, run codeburn plan set claude-max and check codeburn quota for remaining limits.
  5. 5Run optimize. Run codeburn optimize to get graded findings with estimated savings for config that costs tokens without helping.
  6. 6Apply or undo changes. Use codeburn optimize --apply to make changes, which are backed up first, and codeburn act undo --last to reverse them.

Install CodeBurn with npx, npm or Homebrew

CodeBurn needs Node.js 22.13 or newer. You can run it without installing anything, or install it so the command stays available.

The README lists three ways to run it. Use npx to try it once, npm to install it globally, or Homebrew if you prefer that package manager.

  • Run without installing: npx codeburn
  • Install globally with npm: npm install -g codeburn
  • Install with Homebrew: brew install codeburn
npx codeburn

Read the terminal dashboard

Running codeburn with no arguments prints today's total cost and tables for cost by tool, by model, by project and by task. Task is the kind of work the agent was doing, such as coding, debugging or planning, worked out from the session itself.

CodeBurn needs no account or sign-up. It looks in the folders your tools already write to, so there is nothing to configure before the first run.

  • Arrow keys move the period, from today out to your whole history.
  • Press p to switch between tools.
  • Press q to quit.
  • Run codeburn web to see the same numbers in your browser.

Find wasted tokens with codeburn optimize

Optimize reads your sessions and your config, then lists what costs tokens without earning them. The README gives three examples: a file the agent re-reads on every turn, an MCP server you installed and never call, and a CLAUDE.md file long enough to be sent with every request.

Each finding comes with a grade, the fix, and the estimated saving over the period it scanned. CodeBurn can apply config changes for you. Files are backed up before they are changed, and you can undo the last change.

  • Review findings: codeburn optimize
  • Review and apply changes: codeburn optimize --apply
  • Undo the last change: codeburn act undo --last
  • Check later whether fixes worked: codeburn act report
codeburn optimize --apply # review and apply codeburn act undo --last # put it back

Track a subscription plan and quota

If you pay a flat subscription, set your plan so CodeBurn shows how much of it you have used and whether the month is on pace to run past it, instead of only showing what you spent.

codeburn quota reads live limits from the tools you are signed in to, including the five-hour and weekly windows. Check it before a long run.

  • Set your plan: codeburn plan set claude-max
  • See remaining quota: codeburn quota
codeburn plan set claude-max # the plan you pay for codeburn quota # how much of it is left

Compare spend before and after a change

Use the desktop app's Compare periods view to put two date ranges side by side. After you change a model, a workflow or a prompt, this shows whether the change actually cost less.

Every number in the desktop app is clickable. Opening a total takes you to sessions, one row per session with project, model, tokens and cost, and clicking a row shows the turns inside it.

  • Spend page: cut by project, git branch, model and task.
  • The branch view totals every session run while on that branch, which approximates the cost of a feature.

Set optional spending caps for Claude Code

Guard is opt-in and local. It adds Claude Code hooks that warn a session once it passes a set amount and stop it at a higher one. The README example uses $5 for the warning and $15 for the stop. You can change both numbers.

Use the status command to see where the hooks live, and uninstall to remove them.

  • Install hooks: codeburn guard install
  • Show hook locations: codeburn guard status
  • Remove hooks: codeburn guard uninstall
codeburn guard install codeburn guard status codeburn guard uninstall

What people use it for

  • Seeing which project or model drives most of a monthly AI coding bill.
  • Checking whether a switch of model or workflow actually lowered cost by comparing two periods.
  • Finding an MCP server or a long CLAUDE.md file that adds tokens to every request.
  • Tracking how much of a Claude subscription has been used before a heavy week.

Frequently asked questions

Is CodeBurn free?

CodeBurn is free and open source under the MIT licence. The README describes it as a free, local tool that needs no account or sign-up.

What do I need to run CodeBurn?

The README says it needs Node.js 22.13 or newer. You can run it with npx codeburn or install it with npm or Homebrew.

Does CodeBurn send my data to a server?

The README describes CodeBurn as local. It reads session files already on your disk and does not require an account. Check the project's documentation for the full details of how it works.

Are CodeBurn's numbers exact billing figures?

No. The README presents the figures as estimates calculated from session data. It does not claim they match your invoices, so do not use them for exact billing reconciliation.

Which AI coding tools does CodeBurn support?

The source names Claude Code, Cursor, Codex and Gemini among the supported tools. It only reads session files from tools it integrates with, so a tool outside the supported list will not be tracked.

Are there alternatives to CodeBurn?

Our source lists no comparable projects, so we cannot recommend specific alternatives from it. If you need a hosted team dashboard, note that the README describes CodeBurn as local rather than cloud-based.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

CodeBurn suits developers who use several AI coding tools and want one local view of spending, or who are on a Claude subscription and want to see how much of their plan they have used. It is a poor fit for teams that want a hosted cloud dashboard, for tools outside its supported list, or for anyone who needs figures that match invoices exactly.

Install options & downloads