getagentseal/codeburn: Local AI Coding Cost Tracker for 32+ Tools

getagentseal/codeburn: Local AI Coding Cost Tracker for 32+ Tools

Meta description: getagentseal/codeburn is a free, local-first tool that tracks AI coding token usage and costs across 32+ developer tools. No API keys, no cloud—just npx codeburn.

Introduction

Developers today pay for multiple AI coding tools—Claude Code, Cursor, Codex, Gemini, and dozens more—yet none of these tools tell you where your money actually goes. Your bill shows a total. It never breaks down whether half your spend went to conversation instead of code, or whether an expensive model burned budget on work a cheaper one would have handled in a single shot. This opacity makes cost optimization nearly impossible.

getagentseal/codeburn solves this by reading the session files your tools already write to disk, then breaking down every token and dollar by task, model, tool, and project. With 8,654 GitHub stars, 680 forks, and an active release cycle (last commit July 14, 2026), it has become a practical standard for developers who want visibility into their AI spend without surrendering data to a third-party cloud service. Everything runs locally—no wrapper, no proxy, no API keys required.

This article explains what getagentseal/codeburn does, how it works, and how to integrate it into your workflow.

What is getagentseal/codeburn?

getagentseal/codeburn is a free, open-source, local-first CLI tool built in TypeScript under the MIT License by AgentSeal. It falls into the category of developer cost observability tools, specifically designed for the emerging problem of distributed AI coding spend.

The tool auto-detects 32 AI coding tools and agents—from mainstream options like Claude Code, Cursor, Codex, and Gemini to newer entrants like Kiro, OpenClaw, Mistral Vibe, and Grok Build. It reads their native session storage formats directly: JSONL files for Claude Code, SQLite databases for Cursor and OpenCode, zstd-compressed JSON for Zed, and various other formats. No instrumentation, no API integration, no code changes to your projects.

Pricing data comes from LiteLLM, refreshed daily and cached locally for 24 hours. Hardcoded fallbacks for Claude and GPT-5 models prevent mispricing when API names don't match exactly. The tool supports 162 currencies via exchange rates from the European Central Bank through Frankfurter.

Relevance is immediate: as teams adopt multiple AI tools simultaneously, spend fragments across vendors. getagentseal/codeburn consolidates this into unified reporting, making it possible to answer questions like "What did Claude Code cost me this month versus Cursor?" or "Which model gives me the best one-shot rate for my actual work?"

Key Features

Cross-tool unified dashboard. The interactive TUI shows the last 7 days by default, with arrow-key navigation between periods (today, week, 30 days, month, 6 months). Press p to toggle between detected providers. Auto-refreshes every 30 seconds.

Granular cost breakdown. Every session is split by tool, model, project, task category, and activity type. Task categories are classified deterministically from tool usage patterns—13 types including Coding, Debugging, Feature Dev, Refactoring, Testing, Exploration, Planning, and Conversation. No LLM calls required for classification.

Waste detection and automated fixes. codeburn optimize scans for patterns like files re-read across sessions, low read:edit ratios, uncapped bash output, unused MCP servers, ghost agents, bloated CLAUDE.md files, and context-heavy sessions with no delivery. Each finding includes estimated token and dollar savings plus a ready-to-paste fix. Config-class fixes can be applied interactively with full journaling and undo support.

Budget guardrails. codeburn guard installs opt-in hooks into Claude Code with soft caps ($5 default), hard caps ($15), and checkpoints ($3). Hooks fail open—a broken guard never blocks a session.

Model comparison. codeburn compare shows side-by-side metrics: one-shot rate, retry rate, self-correction, cost per call, cost per edit, output tokens per call, and cache hit rate. Answer which model is actually better for your work, not benchmark averages.

Yield tracking. codeburn yield correlates AI sessions with git commits to categorize spend as productive (commits reached main), reverted, or abandoned.

Multi-device aggregation. Pair devices on your local network with PIN authorization to see combined totals across laptop, desktop, and work machine.

MCP server. Expose usage and savings data to any MCP client, including Claude Code and Cursor, via npx -y codeburn mcp.

Use Cases

Multi-tool freelancer billing. You use Claude Code for architecture, Cursor for UI polish, and Codex for quick scripts. At month-end, you need to know which client work consumed which tool's budget. getagentseal/codeburn's per-project breakdown with --from/--to date ranges gives you copy-pasteable reports for invoicing.

Team lead cost allocation. Your engineering team has adopted AI tools organically—different developers use different stacks. codeburn sync (preview) pushes anonymized usage to a central endpoint so you can aggregate spend without exposing prompts or code. Project names are pseudonymized by default.

Model selection optimization. You're paying for Claude Max ($200/month) but suspect Sonnet handles most of your work. codeburn compare over 30 days reveals Opus 4.6 dominates cost on small turns—data that justifies routing simple tasks to cheaper models.

Pre-commit waste reduction. Before starting a new project, codeburn optimize --apply --dry-run audits your ~/.claude/ setup for unused skills, bloated context files, and redundant MCP servers. Apply fixes once, realize measured savings over subsequent weeks via codeburn act report.

CI/CD budget monitoring. Run codeburn status --format json in your deployment pipeline to fail builds or notify when monthly AI spend exceeds planned thresholds. JSON output pipes directly to jq for custom alerting logic.

Installation & Setup

Instant run, no install:

npx codeburn

This opens the interactive dashboard for the last 7 days. Arrow keys switch periods. q quits.

Global install for permanent command:

npm install -g codeburn

Also supported: bunx codeburn, dx codeburn, or brew install codeburn on macOS.

macOS menu bar app:

codeburn menubar

Downloads the latest .app, installs to ~/Applications, and launches. Re-run with --force to reinstall. The menubar shows spend for your selected period (today by default), with a popover containing agent tabs, trend, forecast, pulse, stats, plan insights, and export options. Refresh cadence auto-adjusts for battery/power state.

Linux GNOME extension:

git clone https://github.com/getagentseal/codeburn && cd codeburn/gnome
./install.sh
gnome-extensions enable codeburn@codeburn.dev

Requires GNOME 45+. See gnome/README.md for settings.

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

Real Code Examples

Example 1: Monthly overview for reporting

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

The overview command produces a copy-pasteable summary including totals (cost, tokens, cache hit), breakdown by tool and top model, highest-value days, top projects, per-day table, and activity analysis. Color drops automatically for non-terminal output, or force plain text with --no-color. Pipe to pbcopy, Slack, or a PR description.

Example 2: Waste scan with fix application

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

optimize identifies waste patterns and ranks findings by urgency with an A-F setup health grade. Run with --apply to review and apply fixes interactively, --apply --dry-run to preview without changes, or --apply --yes for non-interactive application. Every change is journaled:

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

Example 3: Budget guard installation

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 soft ($5), hard ($15), and checkpoint ($3) caps into Claude Code. Edit caps in ~/.config/codeburn/guard.json. Set any value to null to disable. Add --statusline for session cost display in the Claude Code status line.

Example 4: JSON pipeline integration

codeburn report --format json | jq '.projects'
codeburn today --format json | jq '.overview.cost'
codeburn status --format json       # lighter: today + month totals only

JSON output enables scripting and integration with existing observability stacks. The schema includes overview, daily breakdown, projects with avgCostPerSession, models with token counts, activities with one-shot rates, core tools, MCP servers, and shell commands.

Advanced Usage & Best Practices

Pin your period for the menubar. Set the display period externally when you want consistent context across relaunches:

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

Allowed: today, week, month, sixMonths. Relaunch to apply.

Handle model alias mismatches. Proxies that rewrite model names cause $0.00 pricing. Map them explicitly:

codeburn model-alias "my-proxy-model" "claude-opus-4-6"

Track local model savings. Running llama3.1:8b locally? Count it as savings against your paid baseline:

codeburn model-savings "llama3.1:8b" gpt-4o

Use proxy-path for subscription-covered projects. If Claude Code routes through GitHub Copilot, mark the project so API-rate cost reports as subscription-covered:

codeburn proxy-path ~/work/copilot-repo

Read dashboard signals critically. Cache hit below 80% suggests unstable system prompts or disabled caching. Low one-shot rate (30% coding) indicates retry loops—consider model or prompt changes. Heavy Conversation category means the agent is talking instead of doing. These are starting points, not verdicts; context matters.

For multi-Claude setups, use CLAUDE_CONFIG_DIRS to merge sessions from work and personal configurations:

export CLAUDE_CONFIG_DIRS="~/.claude-work:~/.claude-personal"

Comparison with Alternatives

codeburn's unique position is local, multi-tool, and actionable: it doesn't just report spend, it identifies waste and applies fixes. The trade-off is that it reads what tools write to disk—if a tool doesn't persist session data locally (rare among modern agents), codeburn cannot track it. For cloud-only tools like Vercel AI Gateway, it supports the Custom Reporting API as a fallback.

FAQ

Does getagentseal/codeburn send my data anywhere? No. Everything runs locally. The optional sync feature (preview) sends token counts and costs only—never prompts or code—to an endpoint you configure.

What Node.js version is required? Node.js 22.13+. Zed support requires 22.15+ for built-in zstd decompression.

How accurate is Cursor cost tracking? Cursor's output tokens and cache are server-side only, so figures are marked estimated and may undercount the admin console for long conversations. Input tokens come from Cursor's own context meter.

Can I undo automated fixes? Yes. codeburn act undo <id> restores original files. It refuses if files changed since application unless you pass --force.

Does it work on Windows? Yes, with full path detection for Windows locations. The menubar app is macOS-only; Windows users use codeburn web for an always-on dashboard.

How do I add a new provider? It's a single file. See src/providers/codex.ts as the reference implementation.

Is the MCP server secure? Project names are pseudonymized by default. The agent sees real names only if it requests them with include_project_names: true.

Conclusion

getagentseal/codeburn fills a specific, growing need: observability for distributed AI coding spend. With 8,654 stars and active development, it has proven useful for developers who pay for multiple AI tools and need to understand where that money goes. The local-first architecture respects privacy. The waste detection and automated fixes go beyond reporting into actionable cost reduction. The MCP server and JSON output enable integration with modern agent workflows.

It's best suited for: developers using 2+ AI coding tools, team leads managing organic AI adoption, freelancers billing clients for tool usage, and anyone who suspects they're overpaying for model capacity they don't need.

Start with npx codeburn to see your last 7 days. Install globally when you're ready to make it part of your daily workflow. For the full source, documentation, and contribution guidelines, visit https://github.com/getagentseal/codeburn.

For related approaches to AI infrastructure cost management, see our coverage of [INTERNAL_LINK: LiteLLM proxy configuration for enterprise spend tracking].