Codeburn

CodeBurn is a free, open-source, local-first tool that tracks AI coding token usage and cost across 41 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 41 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 (today by default, or the last 7 days when today has no usage yet). 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 pnpm dlx codeburn, or brew install codeburn on macOS.

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

codeburn menubar

The same command installs the tray app on Windows; see Windows. On Linux, a GNOME Shell extension gives it in the top panel; 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                             # last 6 months
codeburn overview -p lifetime                        # full history (uncapped)
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:

For Claude Code, the optimize session count, the per-session findings, coaching, and model-default recommendations use user-started (main) sessions. Subagent sidechain transcripts are excluded from that population because their delegated context and delivery behavior are structurally different, and so is the re-read finding, since a subagent starts on a fresh context. Findings about how Claude uses tools (junk reads, read:edit ratio) and every spend, MCP, and configuration-overhead finding keep counting them.

• 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

Findings are grouped into three classes: Fix now (CodeBurn can apply it for you), Habits (you change how you drive the next session), and FYI (informational, the cost may be justified). Each one says whether its savings number is measured from provider-counted usage or estimated from a model. See docs/optimize.md for what is scanned, what --apply may write, and how to read the health grade.

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 --auto-revert       # undo the applied fixes that measured no reduction

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 every later codeburn optimize run lists it under Applied fixes with a plain verdict — worked, under its estimate, or did not help, with the undo command for that last case. --auto-revert undoes the ones that did nothing (never CLAUDE.md rules). 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.

Also compares per-category one-shot rates, delegation rate, planning rate, average tools per turn, and fast mode usage.

Track what shipped

codeburn yield                  # last 7 days (default)
codeburn yield -p today         # today only
codeburn yield -p 30days        # last 30 days
codeburn yield -p month         # this calendar month
codeburn yield --format json    # productive/reverted/abandoned/ambiguous spend as JSON

Did the spend actually ship? codeburn yield correlates AI sessions with git commits by timestamp:

Attribution is timestamp-window based (heuristic): each commit is credited to at most one session, the tightest window containing it. The JSON report carries methodology: "timestamp-window".

Requires a git repository. Run from your project directory.

Browser dashboard

codeburn web                    # opens http://localhost:4747 in your browser
codeburn web -p 30days          # start on a different period
codeburn web --port 8080        # pick a port (falls back to a free one if taken)
codeburn web --no-open          # start the server without opening a browser

A local web dashboard with the same task, model, tool, and project breakdowns as the TUI, rendered with charts. The usage graph follows the selected period with 15-minute, hourly, or daily buckets and can switch between per-session and per-model lines. Everything is read from disk on your machine and the server binds to localhost; nothing is uploaded.

Combine usage across your devices

See one total across your laptop, desktop, and work machine on the same network. On each other device, share its usage:

codeburn share --pair           # opens a pairing window and prints a PIN

Then add it once from your main device (the PIN authorizes the pairing):

codeburn devices add            # find nearby devices and pair, or: add <host> --pin <pin>
codeburn devices                # combined totals by machine
codeburn devices rm <name>      # forget a device

Pairing is PIN-authorized and stays on your local network. You can also discover and pair devices straight from the browser dashboard.

Menu bar

macOS

codeburn menubar

One command: downloads the latest .app, installs into ~/Applications, and launches it. Re-run with --force to reinstall. The native Swift and SwiftUI app lives in mac/ (see mac/README.md for build details).

The menubar icon shows the spend period selected in Settings (Today by default; Week, Month, and 6 Months are also available). Non-today periods add a short suffix such as $42 / mo so the menu bar value stays clear. Click to open a popover with agent tabs, period switcher (Today, 7 Days, 30 Days, Month, All), Trend, Forecast, Pulse, Stats, and Plan insights, activity and model breakdowns, optimize findings, and CSV/JSON export. Refreshes every 30 seconds.

You can also set the menubar status period from Terminal:

defaults write org.agentseal.codeburn-menubar CodeBurnMenubarPeriod -string month

Allowed values are today, week, month, and sixMonths. Relaunch the app to apply external defaults changes.

Compact mode shrinks the menubar item to fit the text, dropping decimals (e.g. $110 instead of $110.20):

defaults write org.agentseal.codeburn-menubar CodeBurnMenubarCompact -bool true

Relaunch the app to apply. To revert: defaults delete org.agentseal.codeburn-menubar CodeBurnMenubarCompact.

Refresh cadence is set in Settings under Usage Refresh. Auto (the default) refreshes every 30 seconds on AC power and backs off on battery, in Low Power Mode, and while the display sleeps; fixed 1, 5, or 15 minute cadences and a Manual mode (refresh only when you open the popover or click Refresh Now) are also available. From Terminal:

defaults write org.agentseal.codeburn-menubar CodeBurnMenubarRefreshSeconds -int 300

Seconds between refreshes: 60, 300, or 900; 0 is Manual and -1 is Auto. Takes effect on the next refresh tick, no relaunch needed.

Preferred terminal decides where Full Report and Optimize open. Set it in Settings → General → Terminal, or from Terminal:

defaults write org.agentseal.codeburn-menubar CodeBurnPreferredTerminal -string iterm2

Allowed values are terminal (macOS Terminal.app, the default) and iterm2. Anything else falls back to terminal. Only terminals that can script a command into a live window are offered; if the chosen app is missing or fails to accept the command, CodeBurn tries Terminal.app and then runs the command in the background, logging each step to Console.app. Takes effect on the next launch of a command, no relaunch needed.

Windows

Windows gets the same ambient view from the system tray, from the same one command:

codeburn menubar

It downloads the .msi for your CLI version, verifies its sha256, runs it through msiexec /passive, and launches the tray app. Re-run with --force to reinstall; an already-installed matching version is just launched. You can also download the .msi yourself from the latest Windows Menubar release.

Today's spend sits in the tray as a number beside the flame icon (turn it off in Settings, and the tooltip always carries it). Click for the same popover the macOS app shows: agent tabs, period switcher, Trend, Forecast, Pulse, Stats and Plan insights, activity and model breakdowns, optimize findings, and CSV/JSON export. Settings covers launch at login, the tray number, theme, and currency. It refreshes every 60 seconds while the popover is open and every 2 minutes while it is closed.

The tray app reads everything through the CLI, so install that first (npm install -g codeburn) — it needs codeburn 0.9.9 or newer, and shows a setup screen with the install command until it finds one. Source and build instructions are in windows/ (windows/DEVELOPMENT.md). The .msi is unsigned for now, so SmartScreen prompts on first run.

Linux (GNOME)

Linux gets the same ambient view through a GNOME Shell extension (GNOME 45+): spend in the top panel, period switcher, compact mode, and daily budget alerts. It lives in gnome/:

git clone https://github.com/getagentseal/codeburn && cd codeburn/gnome
./install.sh
gnome-extensions enable [email protected]

See gnome/README.md for settings and development notes. The Tauri tray app in windows/ also builds and runs on Linux, but it is experimental and unreleased there — the GNOME extension is the supported Linux surface.

Omarchy

Install the CodeBurn Omarchy plugin to add CodeBurn to Omarchy:

Community-maintained by @erzz — issues and feature requests go to erzz/omarchy-codeburn.

omarchy plugin add https://github.com/erzz/omarchy-codeburn.git --enable

CodeBurn in your agent (MCP)

claude mcp add codeburn -- npx -y codeburn mcp

codeburn mcp runs a local MCP server over stdio, so Claude Code, Cursor, or any MCP client can ask "where did my tokens go this week?" or "how do I spend less?" mid-conversation. It exposes two tools:

Everything is read from local disk, same as the CLI. Project names are pseudonymized by default; the agent only sees real names if it asks with include_project_names: true. For other MCP clients, configure a stdio server with command npx and args -y codeburn mcp.

Supported tools

CodeBurn auto-detects which AI tools you use. Each logo links to its provider doc.

If multiple providers have session data on disk, press p in the dashboard to toggle between them.

Each provider doc lists the exact data location, storage format, and known quirks. Linux and Windows paths are detected automatically. If a path has changed or is wrong, please open an issue.

The --provider flag filters any command to a single provider: codeburn report --provider claude, codeburn today --provider codex, codeburn export --provider cursor. Works on all commands: report, today, month, overview, status, export, web, optimize, compare, yield.

Adding a new provider is a single file. See src/providers/codex.ts for an example.

Commands

Run codeburn for the dashboard, or use a subcommand below. Most commands also accept --provider, --project / --exclude, and a period flag (-p today|week|30days|month|all|lifetime).

Dashboard & reports

Status & export

Sync (team telemetry) preview

Sync sends token counts, costs, models, and projects, never prompts or code. This feature is in preview; the protocol may change between releases. See docs/sync/ for details.

Web & devices

Analysis

Fix & control

Models

Left/right arrow keys switch between Today, 7 Days, 30 Days, Month, 6 Months, and Lifetime (use --from / --to for an exact historical window). Up/down scroll the full dashboard one line, Page Up/Page Down move one screen, and Home/End jump to either end. The main Daily Activity panel shows at least 10 dates from scrollable full history: use j/k to move one day, Shift+Space/Space to page, and g/G to jump to either end. Panels flow in the same order across three columns at maximum width, two at medium width, and one when narrow. In the three-column layout, all panels widen equally by one character for every three additional terminal columns until the dashboard reaches the lesser of 256 characters or the widest renderable source row. Press q to quit, 1 2 3 4 5 6 as period shortcuts, c to open model comparison, or o to open optimize. Today, 7 Days, and concrete-day views refresh in place at most once per minute by default (--refresh 0 to disable) without changing the active view or scroll position. The heavier aggregate views remain static between deliberate navigation changes. The dashboard also shows average cost per session and the five most expensive sessions across all projects.

Features

Pricing

Prices every API call using input, output, cache read, cache write, and web search token counts, with a fast mode multiplier for Claude. Prices are fetched from LiteLLM and cached locally for 24 hours at ~/.cache/codeburn/. Hardcoded fallbacks for all Claude and GPT-5 models prevent fuzzy-matching mispricing. Routing-gateway model ids are priced as the model they wrap: OrcaRouter fusion route ids peel to their current upstream (openai/gpt-oss-120b), orcarouter/auto stays unpriced until a live probe pins the rotating target, and a nested upstream spelling (orcarouter/deepseek/deepseek-v4-pro) prices at that exact row, so a gateway-routed session reports real spend instead of $0.

Task Categories

13 categories classified from tool usage patterns and user message keywords. No LLM calls, fully deterministic.

Breakdowns

Daily cost chart, per-project, per-model (Opus, Sonnet, Haiku, GPT-5, GPT-4o, Gemini, Kiro, and more), per-activity with one-shot rate, core tools, shell commands, and MCP servers.

One-Shot Rate

For categories that involve code edits, CodeBurn tracks file-aware retry cycles. A retry is when the same file is re-edited after a shell command in between (Edit foo.ts, Bash, Edit foo.ts). Editing different files across shell steps is not a retry. The one-shot column shows the percentage of edit turns that succeeded without retries. Coding at 90% means the AI got it right first try 9 out of 10 times. File-level tracking is available for Claude, Codex, and Goose; other providers fall back to tool-name-based detection.

Plans

codeburn plan set claude-max                                  # $200/month
codeburn plan set claude-pro                                  # $20/month
codeburn plan set cursor-pro                                  # $20/month
codeburn plan set copilot-pro                                 # 1500 AI Credits ($15 equivalent)
codeburn plan set custom --monthly-usd 200 --provider codex   # ChatGPT Pro-style custom plan
codeburn plan set custom --credits 20000 --provider copilot   # org Copilot allotment
codeburn plan reset --provider codex                          # remove one provider plan
codeburn plan set none                                        # disable plan view
codeburn plan                                                 # show configured plans
codeburn plan reset                                           # remove plan config

Subscription tracking for Claude Pro, Claude Max, Cursor Pro, Copilot (AI credits), and custom provider plans. Plans are stored per provider, so you can track Claude and Codex/Cursor subscriptions at the same time; the dashboard shows one overage line per active provider plan. A legacy/custom all plan remains a single aggregate plan and is replaced when you add a provider-specific plan, avoiding double-counted overage rows. Existing single-plan config is still read as a fallback. USD presets use publicly stated plan prices (as of April 2026). Copilot presets use official individual AI-credit allotments (Pro 1,500 / Pro+ 7,000 / Max 20,000; fetched 2026-08-23) — not the $10 / $39 / $100 sticker prices — and spend is total_nano_aiu / 1e9, never token-priced USD.

Currency

codeburn currency GBP          # set to British Pounds
codeburn currency AUD          # set to Australian Dollars
codeburn currency JPY          # set to Japanese Yen
codeburn currency CNY          # set to Chinese Yuan
codeburn currency RON          # set to Romanian Leu
codeburn currency