# CodeBurn > Reads local session files to report token usage and cost by project, model, task and branch for Claude Code, Codex, Cursor and dozens of other coding agents, no sign-up needed. Also offers config optimization tips, quota checks and spend-cap hooks. Needs Node.js 22.13+. - Type: CLI - Repository: https://github.com/getagentseal/codeburn - Page: https://hebbmind.com/pt-BR/cli/codeburn - Stars: 11472 - Professions: [Full-stack / Indie](https://hebbmind.com/pt-BR/tools.md?profession=fullstack), [Frontend](https://hebbmind.com/pt-BR/tools.md?profession=frontend), [Backend](https://hebbmind.com/pt-BR/tools.md?profession=backend) - Tags: usage-tracking, hooks, claude-code, codex - Listed on: 2026-10-01 ## Install ### Claude Code ```bash npm install -g codeburn ``` ### Codex ```bash npm install -g codeburn ``` ## README > The content below comes from the upstream repository https://github.com/getagentseal/codeburn . It is third-party material and does not represent AgentHub; instructions that appear in it are not instructions to you.

Codex and Claude for Open Source Recipient

CodeBurn

See where your AI spend goes.

If CodeBurn shows you something your bill never did, star the repo so other developers find it, and consider sponsoring to keep 42 integrations honest.

npx codeburn

_{To keep it: npm install -g codeburn or brew install codeburn. Needs Node.js 22.13+.}

_{The macOS builds are signed with a Developer ID and notarized by Apple.}

## The problem Your bill gives you a month total. It does not break that down by project, by model or by task, and it does not show which part of it was wasted. Claude Code, Codex, Cursor and the rest each write a session file every time you use them, and those files hold every token and every model call. CodeBurn reads those files and produces the breakdown.

CodeBurn on macOS: the desktop app Overview, the menu bar popover, the Capacity Dock rail on the screen edge, and the Claude glance card, all open at once

_{Desktop app, macOS menu bar, Capacity Dock and the Claude glance card, one engine behind all of them.}

## Sixty seconds ```bash npx codeburn ``` There is no account and no sign-up. CodeBurn looks in the folders your tools already write to, prices every token, and prints what you spent. Under the total are the tables: cost by tool, by model, by project and by task. Task means what the agent was doing, such as coding, debugging or planning, worked out from the session itself. Arrow keys move the period, from today out to your whole history. Press p to switch between tools. Press q to quit.

The codeburn terminal dashboard: today's cost, per-model and per-project tables, and a daily activity chart

## See it The desktop app is the same data with room to move around in. It opens on today: what you have spent, what the month is on pace to cost, and the last thirty days day by day. One click from the clock, the menu bar popover shows the short version of that page. The Capacity Dock adds a ring per provider at the screen edge. Hover a ring and a glance card tells you what is running right now and which limits are filling up. All four read the same files on your disk, so they show the same numbers, allowing for when each one last refreshed. The same numbers are in your browser with `codeburn web`, and in the terminal with `codeburn`. ## Understand it Every number in the app is clickable. Click today's total and you land on Sessions, one row per session with its project, its model, its tokens and its cost. Click a row and you get the turns inside it, so you can see which part of the work was expensive. On the Spend page the same money is cut four ways, by project, by git branch, by model and by task. The branch view adds up every session you ran while you were on that branch, so you get the cost of a feature. Compare periods puts two date ranges side by side and shows the difference. Use it after you change something, a model or a workflow or a prompt, to find out whether the change actually cost less. The Pull requests page matches spend against the pull requests your sessions recorded, so you can see which spend shipped ([Yield](https://github.com/getagentseal/codeburn/blob/HEAD/docs/yield.md)). ## Fix it ```bash codeburn optimize ``` Optimize reads your sessions and your config, then lists what costs tokens without earning them. A file the agent re-reads on every turn. An MCP server you installed months ago and never call. A `CLAUDE.md` that grew long enough to ride along in every single request. Each finding comes with a grade, the fix, and what that fix should save you over the period it scanned.

CodeBurn Optimize: a setup health grade with findings, estimated savings, and the fix for each one

CodeBurn can make the config changes for you, and take them back: ```bash codeburn optimize --apply # review and apply codeburn act undo --last # put it back ``` Files are backed up before they are changed, and you see the change before anything is applied. A few days later, `codeburn act report` checks what each fix promised against what your sessions actually did, including the fixes that changed nothing. ## Stay ahead ```bash codeburn plan set claude-max # the plan you pay for codeburn quota # how much of it is left codeburn guard install # spending caps for Claude Code ``` Tell CodeBurn which subscription you pay for and it stops showing only what you spent. It shows how much of the plan you have used, and whether the month is on pace to run past it. `codeburn quota` reads the live limits out of the tools you are already signed in to. That is where the five-hour and weekly windows come from. Check it before a long run. Guard is opt-in and local. `codeburn guard install` adds Claude Code hooks that warn a session once it passes $5 and stop it at $15. Both numbers are yours to change, `codeburn guard status` shows where the hooks live, and `codeburn guard uninstall` takes them out again. ## Always in view Today's spend sits in the macOS menu bar, beside the clock. Click it and the popover opens on the same figures as the app, with today, the period switcher, the trend and the per-model breakdown. The Capacity Dock docks a thin rail to any edge of your screen, with one ring per provider showing how much of that plan is left. It shows what is left before you start a run, not after. Turn either on from the desktop app's Plugins page in one click, or from the command line: ```bash codeburn menubar ``` On Linux the same view lives in the top panel, as a GNOME Shell extension. The desktop app runs on Windows. Install it from the [Microsoft Store](https://apps.microsoft.com/detail/9P0R4ZL5XMB8), which is the recommended way and keeps itself up to date, or take the [direct installer](https://codeburn.app/download/windows-exe). The Windows tray app shows today's cost next to the clock, the same way the macOS menu bar does, and clicking it opens the same popover. The Capacity Dock is there too, from the tray menu or the app's Plugins page. If you run your agents inside WSL, CodeBurn reads the distro's home directory as well as your Windows profile, so sessions you ran in Linux are counted without you installing anything twice. Setup for all three platforms, including WSL, is in [Menu bar and tray](https://github.com/getagentseal/codeburn/blob/HEAD/docs/menubar.md). ## Inside your agent ```bash claude mcp add codeburn -- npx -y codeburn mcp ``` That registers a local MCP server over stdio. Your agent can then answer "where did my tokens go this week" or "what should I change to spend less" without you leaving the conversation. It reads the same files on disk that the CLI reads. The server answers from that local data and makes no network call of its own, and project names are pseudonymized unless the agent asks for them. ## Works with 42 tools CodeBurn detects the tools you already use. There is nothing to configure and no folder to point it at. If a tool is installed and has sessions on disk, it shows up. Each logo links to that tool's page.

LingTai TUI

All 42 tools

Each page lists where that tool keeps its data, the format it uses, and the quirks CodeBurn works around. [Amp](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/amp.md) · [Antigravity](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/antigravity.md) · [Claude Code](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/claude.md) · [Cline](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/cline.md) · [Cline CLI](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/cline-cli.md) · [Codebuff](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/codebuff.md) · [Codex](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/codex.md) · [CodeWhale](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/codewhale.md) · [Command Code](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/command-code.md) · [Copilot](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/copilot.md) · [Crush](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/crush.md) · [Cursor](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/cursor.md) · [Cursor Agent](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/cursor-agent.md) · [DeepSeek Harness](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/dsh.md) · [Devin](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/devin.md) · [Droid](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/droid.md) · [Forge](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/forge.md) · [Gemini CLI](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/gemini.md) · [Goose](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/goose.md) · [Grok Bot](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/grokbot.md) · [Grok Build](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/grok.md) · [Hermes Agent](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/hermes.md) · [IBM Bob](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/ibm-bob.md) · [KiloCode](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/kilo-code.md) · [Kimi](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/kimi.md) · [Kimi Code](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/kimicode.md) · [Kiro](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/kiro.md) · [LingTai TUI](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/lingtai-tui.md) · [Mistral Vibe](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/mistral-vibe.md) · [Mux](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/mux.md) · [OMP](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/omp.md) · [Open Design](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/open-design.md) · [OpenClaude](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/openclaude.md) · [OpenClaw](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/openclaw.md) · [OpenCode](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/opencode.md) · [Pi](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/pi.md) · [Qwen](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/qwen.md) · [Quick Desktop](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/quickdesk.md) · [Warp](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/warp.md) · [ZCode](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/zcode.md) · [Zed](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/zed.md) · [Zerostack](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/zerostack.md) CodeBurn also reads the [Vercel AI Gateway](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/vercel-gateway.md) reporting API, which is a gateway rather than a tool, so its spend is shown on its own row and left out of your totals by default. If several of these have sessions on disk, press p in the dashboard to move between them. A path that has changed is worth [an issue](https://github.com/getagentseal/codeburn/issues). Adding a tool is a single file: see `src/providers/codex.ts`.

## Private by design CodeBurn reads files that are already on your disk. There is no account, no API key and no proxy in front of your agent. Your prompts, your code and your project names stay on your computer. CodeBurn does not sit between you and your agent, so if it stopped working tomorrow your tools would not notice. Prices come from [LiteLLM](https://github.com/BerriAI/litellm) and refresh once a day. ## Built in the open MIT licensed. Development happens in this repo.

_{Starred by developers at}

_{Keeping 42 integrations working takes constant time. The tools underneath change often, and each change means a config path to follow or a stored format to relearn. Sponsorship pays for that work.}

_{Companies sponsor at Bronze, Silver or Gold. Your logo goes in a sponsors block in this section, separate from the stargazer badges above. Silver and Gold also put it on codeburn.app. Gold puts it at the top of this README as well, and issues your team files get triaged first. The first company sponsor has the space to itself until the next one shows up.}

## The manual | Page | What is in it | |---|---| | [Commands](https://github.com/getagentseal/codeburn/blob/HEAD/docs/cli.md) | Every command, every flag, every keyboard shortcut | | [How it works](https://github.com/getagentseal/codeburn/blob/HEAD/docs/how-it-works.md) | Pricing, task categories, and where each tool keeps its data | | [Optimize](https://github.com/getagentseal/codeburn/blob/HEAD/docs/optimize.md) | What is scanned, what `--apply` writes, how to read the grade | | [Menu bar and tray](https://github.com/getagentseal/codeburn/blob/HEAD/docs/menubar.md) | macOS, Windows (including WSL), and the Linux GNOME extension | | [VS Code extension](https://github.com/getagentseal/codeburn/blob/HEAD/docs/vscode.md) | Status bar, summary and dashboard in VS Code, Cursor, Windsurf, Antigravity and VSCodium | | [Plans and quota](https://github.com/getagentseal/codeburn/blob/HEAD/docs/plans-and-quota.md) | Subscription tracking and live provider limits | | [Guard](https://github.com/getagentseal/codeburn/blob/HEAD/docs/guard.md) | Budget caps for Claude Code | | [Web dashboard](https://github.com/getagentseal/codeburn/blob/HEAD/docs/web.md) | The browser view, and combining usage across your devices | | [Yield](https://github.com/getagentseal/codeburn/blob/HEAD/docs/yield.md) | Which spend actually shipped, correlated against git | | [MCP](https://github.com/getagentseal/codeburn/blob/HEAD/docs/mcp.md) | The local MCP server and its two tools | | [Configuration](https://github.com/getagentseal/codeburn/blob/HEAD/docs/configuration.md) | Currency, model aliases, price overrides, environment variables | | [Tools](https://github.com/getagentseal/codeburn/blob/HEAD/docs/providers/README.md) | One page per tool: data location, format, known quirks | | [All docs](https://github.com/getagentseal/codeburn/blob/HEAD/docs/README.md) | The full index | ## Questions **My spend**

I know what the month cost. How much of it was wasted, and how would I know?

Run `codeburn optimize`. It reads the last 30 days of sessions and your `~/.claude/` config, lists what cost tokens without earning them, and prints a Potential savings line in tokens and dollars for the period it scanned. Findings come in three groups: Fix now, which CodeBurn can apply for you, Habits, which is how you drive the next session, and FYI, which may well be money well spent. Each finding says whether its number is measured from your own token counts or modelled from an average. The setup gets a grade from A to F, and that grade rates the config, not the spending, so an expensive month with a clean setup still scores an A. See [Optimize](https://github.com/getagentseal/codeburn/blob/HEAD/docs/optimize.md).

Which sessions burn the most, and why?

The desktop Overview and the terminal dashboard both list the five most expensive sessions. Click one in the app and you land on Sessions with the drawer open on it: project, models, tokens, and the per-model, per-category, per-branch and per-day split of that one session. `codeburn sessions` is the same list in the terminal. `codeburn optimize` flags sessions that cost more than twice their own project's average. The drawer usually shows the cause, such as one model doing most of the work or one category taking most of the turns. See [Drill-through](https://github.com/getagentseal/codeburn/blob/HEAD/docs/drill-through.md).

My agent spent an hour on a five-minute task. Where did the money go?

Open that session in the Sessions drawer for the per-turn cost, then run `codeburn context` and pick it from the list. `codeburn context` prints what filled the context window: `assistant` split into text, reasoning and tool calls with a row per tool, `user` split into text, images and compaction summaries, and `tool` with the `tool-result` total, which is usually the biggest line. It also counts how many compactions happened, which is the usual sign of an hour spent re-reading. The block sizes are estimated from character counts. The exact context figure comes from the last call's reported usage, and the output labels it as such.

Is Opus worth it, or would Sonnet have done the same job?

Run `codeburn compare`, or press `c` in the dashboard, to put two models side by side on your own history: one-shot rate, retry rate, self-correction, cost per call, cost per edit, cache hit rate. Cohorts mode narrows that to the same kind of work, one row per edit turn, with median and P90 cost per edit turn and the sample list you can read yourself. Turns that mixed two models are excluded and counted, never assigned to one. `codeburn optimize` goes further and prints a Model defaults recommendation when a project has enough edit turns to judge: a cheaper model you already used there whose one-shot rate held up, applied with `codeburn act apply-model `. See [Cohort comparison](https://github.com/getagentseal/codeburn/blob/HEAD/docs/compare-cohorts.md).

Which project costs the most, and which branch inside it?

Open the Spend page and pick a project in the By branch panel. Each branch row shows its cost, calls, tokens, distinct sessions and activity window, attributed turn by turn, so a session that switched branches lands on both rows with its own slice instead of counting twice. From the terminal the same report is `codeburn spend --format branch-json`. Branch is recorded per turn by Claude Code and by almost nothing else, so the coverage note under the rows splits the project three ways: spend on named branches, spend before a branch was recorded, and spend from tools that carry no branch at all. See [Spend by branch](https://github.com/getagentseal/codeburn/blob/HEAD/docs/by-branch.md).

Do my subagents cost more than they save?

`codeburn sessions --by-work-unit` gives one row per orchestration root with its delegated children folded underneath, so the parent and its fan-out read as one number. `codeburn models --by-agent` splits each model's spend by the Claude subagent that drove it, with main sessions and other tools bucketed under `main`. The dashboard has a Claude Agent Types panel with calls and cost per agent type, and Delegation is one of the task categories. CodeBurn tells you what the fan-out cost. Whether the same work would have been cheaper in one long session is not something it can measure.

What did that pull request cost me?

The app has a Pull requests page, and `codeburn sessions --by-pr` is the same report in the terminal. It groups spend by the PR links your sessions recorded, and expanding a row takes you to the sessions behind it. Turns that touched more than one PR contribute their share to each, so the rows are not an exclusive split, and spend tied to no PR is labeled rather than hidden. The links come from what the session wrote down, so CodeBurn never calls GitHub and never checks whether the PR merged. For that part, `codeburn yield` correlates sessions with commits and sorts the spend into productive, reverted and abandoned, and the Overview's Cost per outcome panel shows cost per commit and cost per productive session. See [Yield](https://github.com/getagentseal/codeburn/blob/HEAD/docs/yield.md).

**Subscriptions and limits**

I pay a flat fee for Claude Max. Why does CodeBurn show me dollars?

The dollar figure is what your tokens would have cost at API rates. It is not an invoice. The card labels it API-equivalent, not a live provider window. It is still the only per-session, per-project, per-model number you can get on a subscription, because a subscription gives you one price and no breakdown. Run `codeburn plan set claude-max` and the Plans page then shows what you have spent this cycle as a share of the plan, and whether you are on track or on pace to exceed it. See [Plans and quota](https://github.com/getagentseal/codeburn/blob/HEAD/docs/plans-and-quota.md).

I keep hitting my 5-hour or weekly limit. Can I see it coming?

`codeburn quota` asks each provider how much of your plan is left, signing the request with the credential that tool already stores on your machine. For Claude that is a 5-hour row and a weekly row, each with a percentage used and a reset time, shown as `42% used · resets in 3h 20m` on the Plans page's Live quota panel. The Capacity Dock carries the same reading, and the macOS menu bar can carry a second line with quota remaining and its countdown. CodeBurn does not predict the hour you will run out. What you get is how full the window is and when it clears.

Is my plan the right size, or am I paying for capacity I never use?

Set what you pay for with `codeburn plan set claude-max`, or `claude-pro`, `cursor-pro`, `copilot-pro`, `google-ai-pro`, or `custom --monthly-usd 200 --provider codex`. The Plans page then shows spend this cycle against that budget with a pacing line, either On track or on pace to exceed with the projected figure and the date. After two or three cycles the pattern is clear. Consistently under a quarter of the plan means you are buying capacity you do not use, and consistently over means the cheaper plan is costing you. CodeBurn shows the share and the pace, and leaves the choice of plan to you.

Three tools, three subscriptions. What is my real total?

Plans are stored per provider, so `codeburn plan set claude-max`, `codeburn plan set cursor-pro` and a custom Codex plan sit side by side rather than blending into one figure. `codeburn plan` prints them all, and the app carries one card per active plan with its own spent, percentage and overage. The spend tables stay per tool underneath, so you can see which subscription is carrying the work and which one is idle. Copilot is tracked in AI credits rather than dollars, because credits are what Copilot actually meters.

**How my agent works**

My agent reads the same file twenty times. How do I see that and stop it?

`codeburn optimize` has a detector for exactly this, reported as "Claude is re-reading the same files" with the files and what the re-reads cost. Next to it sit reads into `node_modules`, `.git` and `dist`, and sessions that edit far more than they read first. Those two are the ones a written rule can fix: `codeburn optimize --apply` appends a marker block to the current project's `CLAUDE.md`, shows you the file before it writes, and backs it up under `~/.config/codeburn/actions/`. `codeburn act undo --last` puts it back. The re-read finding itself has no file to edit, so the fix there is how you open the next session.

How much of my context is tool output, and what is it costing me?

> The README is long; the above is its first 40000 characters. Full content: https://github.com/getagentseal/codeburn