codeburn

By task type, tool, model, MCP server, and project. Supports Claude Code, Codex (OpenAI), Cursor, OpenCode, Pi, and GitHub Copilot with a provider plugin system. Tracks one-shot success rate per activity type so you can see where the AI nails it first try vs. burns tokens on edit/test/fix retries. Interactive TUI dashboard with gradient charts, responsive panels, and keyboard navigation. Native macOS menubar app in mac/. CSV/JSON export.

Works by reading session data directly from disk. No wrapper, no proxy, no API keys. Pricing from LiteLLM (auto-cached, all models supported).

Install

npm install -g codeburn

Or run without installing:

npx codeburn

Requirements

• Node.js 20+
• Claude Code (~/.claude/projects/), Codex (~/.codex/sessions/), Cursor, OpenCode, Pi (~/.pi/agent/sessions/), and/or GitHub Copilot (~/.copilot/session-state/)
• For Cursor/OpenCode support: better-sqlite3 is installed automatically as an optional dependency

Usage

codeburn                        # interactive dashboard (default: 7 days)
codeburn today                  # today's usage
codeburn month                  # this month's usage
codeburn report -p 30days       # rolling 30-day window
codeburn report -p all          # every recorded session
codeburn report --format json   # full dashboard data as JSON
codeburn report --refresh 60    # auto-refresh every 60 seconds
codeburn status                 # compact one-liner (today + month)
codeburn status --format json
codeburn export                 # CSV with today, 7 days, 30 days
codeburn export -f json         # JSON export
codeburn optimize               # find waste, get copy-paste fixes
codeburn optimize -p week       # scope the scan to last 7 days

Arrow keys switch between Today / 7 Days / 30 Days / Month / All Time. Press q to quit, 1 2 3 4 5 as shortcuts. The dashboard also shows average cost per session and the five most expensive sessions across all projects.

JSON output

report, today, and month support --format json to output the full dashboard data as structured JSON to stdout:

codeburn report --format json             # 7-day JSON report
codeburn today --format json              # today's data as JSON
codeburn month --format json              # this month as JSON
codeburn report -p 30days --format json   # 30-day window

The JSON includes all dashboard panels: overview (cost, calls, sessions, cache hit %), daily breakdown, projects, models with token counts, activities with one-shot rates, core tools, MCP servers, and shell commands. Pipe to jq for filtering:

codeburn report --format json | jq '.projects'
codeburn today --format json | jq '.overview.cost'

For the lighter status --format json (today + month totals only) or file-based exports (export -f json), see above.

Providers

CodeBurn auto-detects which AI coding tools you use. If multiple providers have session data on disk, press p in the dashboard to toggle between them.

codeburn report                      # all providers combined (default)
codeburn report --provider claude    # Claude Code only
codeburn report --provider codex     # Codex only
codeburn report --provider cursor    # Cursor only
codeburn report --provider opencode  # OpenCode only
codeburn report --provider pi        # Pi only
codeburn report --provider copilot   # GitHub Copilot only
codeburn today --provider codex      # Codex today
codeburn export --provider claude    # export Claude data only

The --provider flag works on all commands: report, today, month, status, export.

Project filtering

Filter results by project name (case-insensitive substring match). Both flags are repeatable:

codeburn report --project myapp                  # show only projects matching "myapp"
codeburn report --exclude myapp                  # show everything except "myapp"
codeburn report --exclude myapp --exclude tests  # exclude multiple projects
codeburn month --project api --project web       # include multiple projects
codeburn export --project inventory              # export only "inventory" project data

The --project and --exclude flags work on all commands and can be combined with --provider.

Supported providers

Codex tool names are normalized to match Claude's conventions (exec_command shows as Bash, read_file as Read, etc.) so the activity classifier and tool breakdown work across providers.

Cursor reads token usage from its local SQLite database. Since Cursor's "Auto" mode hides the actual model used, costs are estimated using Sonnet pricing (labeled "Auto (Sonnet est.)" in the dashboard). The Cursor view shows a Languages panel (extracted from code blocks) instead of Core Tools/Shell/MCP panels, since Cursor does not log individual tool calls. First run on a large Cursor database may take up to a minute; results are cached and subsequent runs are instant.

GitHub Copilot only logs output tokens in its session state, so Copilot cost rows sit below actual API cost. The model is tracked via session.model_change events; messages before the first model change are skipped to avoid silent misattribution.

Adding a provider

The provider plugin system makes adding a new provider a single file. Each provider implements session discovery, JSONL parsing, tool normalization, and model display names. See src/providers/codex.ts for an example.

Currency

By default, costs are shown in USD. To display in a different currency:

codeburn currency GBP          # set to British Pounds
codeburn currency AUD          # set to Australian Dollars
codeburn currency JPY          # set to Japanese Yen
codeburn currency              # show current setting
codeburn currency --reset      # back to USD

Any ISO 4217 currency code is supported (162 currencies). Exchange rates are fetched from Frankfurter (European Central Bank data, free, no API key) and cached for 24 hours at ~/.cache/codeburn/. Config is stored at ~/.config/codeburn/config.json.

The currency setting applies everywhere: dashboard, status bar, menu bar widget, CSV/JSON exports, and JSON API output.

The menu bar widget includes a currency picker with 17 common currencies. For any currency not listed, use the CLI command above.

Menu Bar

npx codeburn menubar

One command: downloads the latest .app, installs into ~/Applications, and launches it. Re-run with --force to reinstall. Native Swift + SwiftUI app lives in mac/ (see mac/README.md for build details). Shows today's cost with a flame icon, opens a popover with agent tabs, period switcher (Today / 7 Days / 30 Days / Month / All), Trend / Forecast / Pulse / Stats / Plan insights, activity and model breakdowns, optimize findings, and CSV/JSON export. Refreshes live via FSEvents plus a 60-second poll.

What it tracks

13 task 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), per-activity with one-shot rate, core tools, shell commands, MCP servers.

**One-