codeburn

What It Is (confidence: medium)

codeburn (getagentseal/codeburn) is a free, open-source (MIT), local-first token-usage and cost tracker for AI coding agents. Tracks usage across 36 tools/agents (title says 31 — internal inconsistency) by model, project, and task. No-install via npx codeburn; four surfaces (TUI, web dashboard, desktop app, macOS menubar/GNOME extension); pricing from LiteLLM refreshed daily.

Key Points (confidence: medium)

• Reads existing session files, never intercepts traffic: Claude Code ~/.claude/projects/<path>/<session-id>.jsonl (dedup by API message ID), Codex JSONL (cumulative token cross-check), Cursor state.vscdb (conversation/timestamp), OpenCode SQLite, Gemini CLI chat JSON, Zed zstd threads.db. Paths overridable via env vars.
• Measurement quality is provider-dependent: real counts where provider records them (Claude, Gemini CLI, Zed, OpenCode); Cursor is a “reply-text estimate” that undercounts the admin console for long conversations; Copilot/Kiro estimated from content length; Warp prompt-size weighting. codeburn audit documents where every number comes from; codeburn doctor verifies.
• codeburn optimize: scans sessions + ~/.claude/ for 9 waste patterns (files re-read across sessions, low Read:Edit ratio, uncapped BASH_MAX_OUTPUT_LENGTH, unused MCP servers paying tool-schema overhead, ghost agents/skills/slash-commands, bloated CLAUDE.md with @-import expansion, cache-creation overhead, context-heavy sessions, low-worth sessions with no git/gh delivery). A–F setup health grade; --apply journals changes (act list/act undo); after 3 days act report compares estimated vs realized savings.
• codeburn guard: opt-in Claude Code hooks — soft cap $5,hardcap$15 with guard allow lift, checkpoint $3, session openers; caps in ~/.config/codeburn/guard.json; hooks fail open.
• codeburn compare / yield: model comparison (one-shot rate, retry rate, self-correction, cost/call, cost/edit, cache hit rate) and spend-to-git attribution (productive/reverted/abandoned/ambiguous via explicit timestamp-window heuristic).

Implications (confidence: medium)

codeburn is the vault’s first measurement tool in the paper’s frame: it separates token counts from billed cost (LiteLLM pricing, cache multipliers, price overrides) and concedes estimates where the provider doesn’t record real numbers. Its “estimates get checked against reality, not just claimed” loop mirrors token-optimizer-mcp’s honest-comparison stance. The optimize waste patterns are an operational checklist for token-usage-reduction’s levers.

Open Questions

• Direct internal contradiction: “31 tools and agents” (title/About) vs “36” (README body) — capture-time inconsistency.
• Estimates ≠ billed totals for Cursor/Copilot/Kiro/Warp/CodeWhale; plan prices time-stamped “as of April 2026”; sync preview protocol may change.

Related

token-optimizer-mcp — closest comparable tool; same waste-detection purpose token-usage-reduction — the levers optimize audits token-reduction-is-not-cost-reduction — token-vs-billed-cost separation prompt-caching — cache-hit diagnostics (“Cache hit < 80% → context not stable”) claude-code-sessions — reads the exact transcript artifact that page documents

Sources

• raw/external/github-com-codeburn-99fcb193.md