agentburn CLI
agentburn reads local logs of Claude Code, Codex and other agents and shows which windows and tasks consume tokens and money.
- 113 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads local session logs that contain task titles and paths.
- The `explain` mode with `--yes-remote` sends a redacted summary to a remote model.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/agentburnDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads local session logs that contain task titles and paths.
- The `explain` mode with `--yes-remote` sends a redacted summary to a remote model.
This is third-party code. Review the repository files before installing.
What it does
agentburn runs as `uvx agentburn` and builds a report from the logs an agent already keeps on disk: which five hours filled the limit window, which models and sources (you, subagents, scheduled jobs) filled it, where spend runs at night. There are no services or accounts, and data stays on the computer. Subcommands answer narrower questions. `limits` compares the peak five-hour window with your median and estimates the time to the limit wall. `context` shows the cost of a long context and what a `/clear` would have saved. `statusline` prints a status line for Claude Code, and `mcp` starts an MCP server through which the agent reports on its own spend.
Who it is for. Claude Code subscribers and per-token API users who hit a limit unexpectedly or watch the bill grow overnight.
Good fit when
- A Claude Code subscription hits its limit and you need to see which window caused it.
- A server agent spends money overnight and needs a budget guard.
- You want the cost of a long context and the right moment for `/clear`.
- You want a Claude Code status line with the window percentage and time to the limit.
- An agent should answer for itself where its tokens go.
Not a fit when
- You need a vendor invoice: the tool estimates spend from local logs and does not read billing data.
- Your agent writes no local logs in a supported format.
- You want agent settings changed automatically: the report only advises.
Example request
Show which five-hour window used up my Claude Code limit and what filled it.Limitations
Python 3.9 or newer is required, with no dependencies. All figures come from local logs, so accuracy depends on what the agent recorded; the author does not invent Anthropic limit formulas and takes boundaries from limit messages in transcripts. `drift` makes one read-only request for a public trend JSON, and `explain` with `--yes-remote` sends a redacted summary to a remote model. Logs contain your sessions, so review a `--share` card before posting it.
How to disable. Remove the `statusLine` setting from Claude Code settings and, if you added MCP, run `claude mcp remove agentburn`. A run through `uvx` leaves nothing on the system but a cache.
FAQ
Does agentburn send data anywhere?
No, everything runs locally by default. Exceptions: `drift` reads a public trend JSON, `explain` with `--yes-remote` sends a redacted summary, and `--submit` prints the data and a link that you open yourself.
How does `agentburn limits` differ from the plain report?
`limits` looks at a subscription: it compares the peak five-hour window with a typical one and shows what filled it. Plain `agentburn` looks at money when you pay per token.
How do I add a status line to Claude Code?
Add `{ "statusLine": { "type": "command", "command": "uvx agentburn statusline" } }` to settings. The command reads only the last three days of logs.
Which agents does it support?
Claude Code, Codex CLI, Gemini CLI, opencode, OpenClaw and Hermes Agent, through one normalized layer.
How do I install the ready Skill instead of MCP?
The repository has a `SKILL.md` in the `skill` folder. Copy it to `~/.claude/skills/agentburn/` or the equivalent Hermes and OpenClaw folder.
Discussion
No questions or reviews yet.
Related
CLI toolsReads local logs of Claude Code, Codex, Cursor and other agents and shows token spend, time and failures in a TUI
agentplay turns local Claude Code, Codex and Cursor sessions into a file map and a replayable step timeline.
Claude Code mod that holds subagent fan-out, heavy context and retry loops before they eat your usage window.
Session monitor for Claude Code, Cursor, Codex and six more agents in a terminal, window or HTTP API, with chat cleanup and search
A CLI records coding agent sessions locally, replays what happened and shows what the trace could not prove.
One desktop window for Claude Code, Codex, Gemini CLI and OpenCode: terminals, pull requests, diffs and approvals
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| agentburn (this card) | no | 113 | ||
| ccusage | no | 19,425 | counts token spend from logs; agentburn adds the peak limit window, causes of spend and a check of what a change saves | |
| CodeBurn | yes | not required | 11,782 | builds spend reports; agentburn answers the subscription-window and overnight questions |
README in short
A local profiler with no dependencies. The report, `limits`, `context`, `why`, `fix`, `explain`, `doctor` and `mcp` read the same logs, and `--compare` shows results before and after a configuration change.