CodeBurn — see where your AI coding spend goes
CodeBurn is a free, open-source, local-first tool that tracks AI coding token
usage and cost across 40 tools and agents (Claude Code, Cursor, Codex, Gemini,
Grok, OpenCode, and more), broken down by model, project, and task. It reads
the session files those tools already write to disk — no wrapper, no proxy,
no API keys — and prices every call from LiteLLM's daily-refreshed pricing
data. Four surfaces (terminal TUI, browser dashboard, macOS menu bar / GNOME
panel, and an MCP server) all read the same on-disk source of truth.
When to use this skill
- Getting a quick answer to "where did my AI budget go this week/month?"
(
codeburn, codeburn overview, codeburn report)
- Finding concrete token/dollar waste in a Claude Code setup — re-read files,
bloated
CLAUDE.md, unused MCP servers, ghost agents/skills — and applying
the fix (codeburn optimize, codeburn optimize --apply)
- Capping runaway session spend before it happens, or flagging projects with
known waste at session start (
codeburn guard install)
- Deciding which model is actually worth its price for a given kind of work
(
codeburn compare)
- Checking whether AI-assisted work actually shipped, or was reverted /
abandoned (
codeburn yield)
- Exposing live usage/savings data to an agent mid-conversation
(
codeburn mcp)
- Diagnosing why a tool shows $0 or no data (
codeburn doctor)
When not to use this skill
- The user wants to change how much a model costs per call (pricing
policy, rate limits) — CodeBurn only measures and reports spend, it does
not set prices or throttle API calls itself (guard's caps stop a session,
they don't change billing)
- The user wants cloud/team-wide spend analytics with a hosted backend as the
primary need — CodeBurn's
sync feature is a preview push-to-your-own-URL
telemetry channel, not a hosted SaaS dashboard
- The task is about the AI tools' own behavior/config unrelated to cost
(e.g., writing a new Claude Code skill, debugging an MCP server's logic)
and no spend/waste/token question is actually in play
Instructions
Step 1: Run it instantly, no install
npx codeburn
For a permanent command: npm install -g codeburn (or bunx/pnpm dlx/
brew install codeburn on macOS). Requires Node.js 22.13+.
Step 2: Get the month at a glance, as text you can paste
codeburn overview
codeburn overview --no-color
codeburn overview -p all
codeburn overview -p lifetime
codeburn overview --provider claude
codeburn status
codeburn report --format json
Most commands accept --provider, --project/--exclude, and a period flag
(-p today|week|30days|month|all|lifetime) or --from/--to.
Step 3: Find waste before fixing anything
codeburn optimize
codeburn optimize -p week
codeburn optimize --format json
Scans sessions and the ~/.claude/ setup for re-read files, low Read:Edit
ratio, uncapped bash output, unused MCP servers, ghost agents/skills, bloated
CLAUDE.md, and low-value expensive sessions. Each finding carries an
estimated token/dollar saving, a ready-to-paste fix, and an urgency ranking
rolled into an A–F setup-health grade.
Step 4: Apply fixes safely, and be able to undo them
codeburn optimize --apply --dry-run
codeburn optimize --apply --yes
codeburn act list
codeburn act undo --last
codeburn act report
Every applied change is backed up and journaled before it lands; always
preview with --dry-run before --apply --yes in an automated flow.
Step 5: Guard the budget going forward
codeburn guard install
codeburn guard install --global
codeburn guard status
codeburn guard allow
Soft cap (default $5) warns once; hard cap (default $15) stops the session;
a checkpoint nudge fires on sessions that end with no edits/commits past a
threshold. Caps live in ~/.config/codeburn/guard.json; hooks fail open and
never block a session on their own error.
Step 6: Compare models and verify spend shipped
codeburn compare --provider claude
codeburn yield -p 30days --format json
yield correlates sessions with git commits by timestamp and requires being
run from a git repository.
Step 7: Wire usage/savings into an agent (MCP)
claude mcp add codeburn -- npx -y codeburn mcp
Exposes get_usage (fast breakdowns by tool/model/project/task) and
get_savings (waste findings, retry tax, routing waste) over stdio, reading
the same local data as the CLI. Project names are pseudonymized unless the
caller asks with include_project_names: true.
Step 8: Diagnose a tool showing $0 or no data
codeburn doctor
codeburn doctor --provider opencode
codeburn doctor --json
Fully offline and read-only: shows the exact paths probed (with any env
override such as CLAUDE_CONFIG_DIR/CODEX_HOME), how many sessions parsed,
and a one-line verdict per provider.
Best practices
- Always
--dry-run before --apply --yes — codeburn optimize --apply writes to real config files; preview the plan first, especially
in a non-interactive/automated flow.
- Run
codeburn doctor before trusting a zero — a $0/empty report
usually means a path/env-var mismatch, not zero spend; doctor is
read-only and safe to run anytime.
codeburn act undo before hand-editing — undo refuses (unless
--force) if the target file changed since the fix was applied, which is
the signal to inspect manually rather than force it.- Guard caps are soft by default — the hard cap ($15 default) is what
actually stops a session; confirm both
guard status caps before relying
on it for a hard budget limit.
yield needs a git repo — run it from the project directory, not a
scratch/temp directory, or attribution will be empty.- Prefer
--format json for scripting — report, today, month,
status, optimize, export -f json, and yield all support structured
JSON output; don't scrape the colored TUI/table output.
sync is preview — treat codeburn sync (team telemetry push) as an
evolving protocol, not a stable integration surface, when scripting
against it.
References
Examples
Example 1: Find and fix waste in a Claude Code setup this week
codeburn optimize -p week
codeburn optimize --apply --dry-run
codeburn optimize --apply --yes
codeburn act report
Example 2: Cap a runaway session and check what shipped
codeburn guard install --statusline
codeburn yield -p 30days
