codeburn

CodeBurn is a free, open-source, local-first tool that tracks AI coding token usage and cost across 32 tools and agents (Claude Code, Cursor, Codex, Gemini, Grok and more), broken down by model, project, and task.

You pay for Claude, Codex, Cursor, and a stack of other AI tools. The bill tells you the total. It never tells you that half of it went to conversation instead of code, or that an expensive model burned your budget on work a cheaper one would have one-shot.

CodeBurn does. It reads the session files your tools already write to disk and breaks down every token and dollar by task, model, tool, and project, across 32 AI tools.

Everything runs locally. No wrapper, no proxy, no API keys, nothing leaves your machine. Pricing comes from LiteLLM, refreshed daily.

Quick start

Run it instantly, no install needed:

npx codeburn

That opens the interactive dashboard (last 7 days by default). Arrow keys switch periods, q quits. That is the 30-second version. You now know where your AI budget goes.

Install it for a permanent codeburn command:

npm install -g codeburn

Also runs via bunx codeburn or dx codeburn, or brew install codeburn on macOS.

Menu bar app for macOS, with your spend always in the menu bar:

codeburn menubar

On Linux, a GNOME Shell extension gives the same panel view; see Linux (GNOME).

Requires Node.js 22.13+ and at least one supported tool with session data on disk. For Cursor and OpenCode, better-sqlite3 installs automatically.

Your month at a glance

codeburn overview                                    # this month, clean tables
codeburn overview --no-color                         # plain text, ready to paste
codeburn overview --from 2026-06-01 --to 2026-06-15  # any date range
codeburn overview -p all                             # all time
codeburn overview --provider claude                  # one tool only

codeburn overview prints a copy-pasteable summary of where your AI spend went: totals (cost, tokens, cache hit), a breakdown by tool and by top model, your highest-value days, top projects, a per-day table, and activity and tool usage. Pipe it anywhere (into pbcopy, a PR, Slack, or a tweet); color drops automatically when the output is not a terminal, or pass --no-color.

CodeBurn  June 2026

Totals
  Cost       $2,795.10
  Tokens     3.49B   in 23.9M / out 20.2M / cache-w 72.5M / cache-r 3.38B
  Calls      14,755   sessions 753
  Cache hit  99.3%

By tool
┌──────────┬───────────┬────────┬───────┐
│ Tool     │      Cost │ Tokens │ Share │
├──────────┼───────────┼────────┼───────┤
│ claude   │ $2,662.37 │  3.34B │   95% │
│ codex    │   $119.12 │ 128.1M │    4% │
└──────────┴───────────┴────────┴───────┘

(plus Top models, Highest-value days, Top projects, a per-day table, By activity, and Tools)

Find and fix waste

codeburn optimize                       # scan the last 30 days
codeburn optimize -p today              # today only
codeburn optimize -p week               # last 7 days
codeburn optimize --provider claude     # restrict to one provider
codeburn optimize --format json         # setup health + findings as JSON

codeburn optimize scans your sessions and your ~/.claude/ setup for waste patterns:

• Files Claude re-reads across sessions (same content, same context, over and over)
• Low Read:Edit ratio (editing without reading leads to retries and wasted tokens)
• Wasted bash output (uncapped BASH_MAX_OUTPUT_LENGTH, trailing noise)
• Unused MCP servers still paying their tool-schema overhead every session
• Ghost agents, skills, and slash commands defined in ~/.claude/ but never invoked
• Bloated CLAUDE.md files (with @-import expansion counted)
• Cache creation overhead and junk directory reads
• Context-heavy sessions where effective input/cache tokens swamp output
• Possibly low-worth expensive sessions with no edit turns or repeated retries when no git/gh delivery command is observed

Each finding shows the estimated token and dollar savings plus a ready-to-paste fix: a CLAUDE.md line, an environment variable, or a mv command to archive unused items. Findings are ranked by urgency (impact weighted against observed waste) and rolled up into an A to F setup health grade. Repeat runs classify each finding as new, improving, or resolved against a 48-hour recent window.

You can also open it inline from the dashboard: press o when a finding count appears in the status bar, b to return.

Apply fixes, undo anytime

codeburn optimize --apply             # review and apply fixes interactively
codeburn optimize --apply --dry-run   # print the plan, change nothing
codeburn optimize --apply --yes       # apply every appliable fix without prompting
codeburn act list                     # every change CodeBurn has made
codeburn act undo --last              # roll the most recent change back
codeburn act report                   # realized vs estimated savings

codeburn optimize finds the waste; --apply fixes the config-class findings for you: settings values, environment variables, archiving unused agents and skills. Every change is backed up and journaled before it lands. codeburn act list shows the history and codeburn act undo <id> restores the original files (it refuses if the files changed since being applied, unless you pass --force).

The loop closes on honesty: once an applied fix is at least 3 days old, codeburn act report compares its estimated savings against what your sessions actually did, and later codeburn optimize runs show that realized figure in the header. Estimates get checked against reality, not just claimed.

Guard your budget

codeburn guard install            # hooks into this project's .claude/settings.json
codeburn guard install --global   # or into ~/.claude/settings.json
codeburn guard status             # caps, install locations, flagged projects
codeburn guard uninstall          # removes cleanly, leaves your own hooks alone

Guard installs opt-in hooks into Claude Code that watch session cost while you work:

• Soft cap (default $5): a one-time in-session warning when a session passes it.
• Hard cap (default $15): stops the session; codeburn guard allow lifts it for that session only.
• Checkpoint (default $3): if a session ends past this with no edits and no commits, a nudge suggests starting fresh with a named deliverable.
• Session openers: projects where optimize found waste get a one-line flag at session start.

Caps are edited in ~/.config/codeburn/guard.json (set a value to null to disable it). Add --statusline to show session cost in the Claude Code status line. Installs go through the same journal as everything else, so codeburn act undo removes them too. Hooks fail open: a broken guard never blocks a session.

Compare models

codeburn compare                        # interactive model picker (default: last 6 months)
codeburn compare -p week                # last 7 days
codeburn compare -p today               # today only
codeburn compare --provider claude      # Claude Code sessions only

Which model is actually better for your work? Press c in the dashboard, or run codeburn compare. Arrow keys switch periods, b to return.