{
  "markdown": "<div align=\"center\">\n\n<img src=\"assets/wordmark.svg\" alt=\"agentburn — where does your AI agent burn money, while you sleep?\" width=\"420\">\n\n<br>\n\n<a href=\"https://pypi.org/project/agentburn/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/agentburn?color=f7775a\"></a>\n<img alt=\"Python\" src=\"https://img.shields.io/badge/python-3.9%2B-5ab0f7\">\n<img alt=\"zero deps\" src=\"https://img.shields.io/badge/dependencies-0-7df0a8\">\n<a href=\"../../actions/workflows/tests.yml\"><img alt=\"tests\" src=\"../../actions/workflows/tests.yml/badge.svg\"></a>\n<a href=\"LICENSE\"><img alt=\"MIT\" src=\"https://img.shields.io/badge/license-MIT-8a949e\"></a>\n\n<br><br>\n\n<img src=\"assets/demo.svg\" alt=\"uvx agentburn — animated demo: the verdict, the peak usage window, why it burns, what to change\" width=\"760\">\n\n<br>\n\n**[Claude Code](#supported-agents) · [Codex CLI](#supported-agents) · [Gemini CLI](#supported-agents) · [opencode](#supported-agents) · [OpenClaw](#supported-agents) · [Hermes Agent](#supported-agents)** — one normalized core, local, read-only, zero dependencies\n\n```\nuvx agentburn\n```\n\n**[▶ &nbsp;Try it in your browser — no install](https://socialpranker.github.io/agentburn/)**\n\n</div>\n\n---\n\n## You didn't run out on your average day\n\nYou ran out inside **one window**. On this machine that window was **5.4× the median one** — same person, same week, same subscription.\n\nYour assistant's own logs already know which window it was and what filled it. Nothing else on your machine does: the built-in counter shows a total, your invoice shows a total, and neither says *which five hours took you out.*\n\n```\n⏳ agentburn limits — claude-code · rolling 5-hour windows\n\n   PEAK WINDOW        Aug 04 12:45–17:45 · 555M weighted\n                      opus 91% · sonnet 9%   ·   cli 93% · subagent 7%\n   TYPICAL WINDOW     104M    median of 83 active 5h slots\n   PEAK / TYPICAL     5.4×    a wall is hit by the peak, not by the median\n\n   WHAT FILLS THE WINDOW\n   cache reads     64%   ·   cache writes 25%   ·   output 11%\n```\n\nOne command, no account, nothing leaves your computer:\n\n```bash\nuvx agentburn            # where it burns, and what to change\nuvx agentburn limits     # how fast you fill a usage window, and how long until the wall\nuvx agentburn context    # what long contexts cost — and what a /clear at 150k would have saved\n```\n\n## Two ways agents cost you, two questions\n\n| If you pay… | what actually runs out | ask |\n|---|---|---|\n| **a subscription** (Claude Code Pro/Max) | the rolling usage **window** — the invoice is fixed, the wall is not | `agentburn limits` |\n| **per token** (API keys, OpenClaw, Hermes) | **money**, mostly while you're asleep | `agentburn` |\n\nBoth read the same local logs. Neither invents a number the data doesn't contain.\n\n<img src=\"assets/demo-limits.svg\" alt=\"agentburn limits — peak window, typical window, what fills it\" width=\"760\">\n\n### `agentburn limits` — the subscription view\n\nOptimizing a subscription doesn't change your bill. It changes how far you get before you're cut off. That is a *window* problem, and windows need intra-session resolution — a single session routinely spans several of them.\n\n- **Peak vs typical.** Your worst rolling 5-hour window against the median of your own active ones. The ratio is the finding: a wall is hit by the peak.\n- **What filled it** — by model, by source (you / subagents / scheduled work), and by kind (cache reads vs cache writes vs output).\n- **Measured against your own wall — automatically.** Anthropic doesn't publish the formula behind those allowances, so agentburn refuses to invent a threshold. But Claude Code writes the cut-off into the transcript itself (*\"You've hit your session limit · resets 8:30pm\"*), and every one of those moments is a measured ceiling. With several, the ceiling is their median:\n\n  ```text\n  YOUR MEASURED CEILING\n  median of 35 cut-offs Claude Code recorded itself\n  ceiling                146M   weighted tokens\n  peak window            137%   of your ceiling\n  last 5h                 16%   of your ceiling\n  TIME TO WALL          2.7 h   at the pace of the last 30 min\n  ```\n\n  No cut-off in your logs yet? `--hit \"2026-08-20 14:30\"` names one by hand. A measured ceiling is remembered in `~/.agentburn/ceiling.json`, so the status line below knows it too.\n- **Codex: the provider's own reading.** Codex CLI writes `rate_limits.used_percent` next to every request. agentburn pairs each reading with your weighted usage of the same window and takes the median — a ceiling from the provider's arithmetic, not from a cut-off. Treat it as an estimate: that percentage counts every device and app on the account, while your local rollouts are only part of it — and when Codex stops reporting a window (plan or client change), a later peak is flagged as measured on earlier windows, not sold as an overrun.\n- **Time to wall.** Ceiling minus the current window, divided by the pace of the last half hour. The number you actually want while working.\n- **The week, too.** The heaviest rolling 7-day span, how much of it this week already is, and a weekly ceiling when Claude Code recorded a weekly cut-off.\n- **By project.** Sessions record their working directory; the peak window is split by it.\n\n### `agentburn statusline` — the wall, live, inside Claude Code\n\nOne line, no colour, built for Claude Code's `statusLine`:\n\n```text\n⏳ 5h 63% · wall in 47 min · week 71%\n```\n\n```json\n{ \"statusLine\": { \"type\": \"command\", \"command\": \"uvx agentburn statusline\" } }\n```\n\nReads only the last three days of logs (the ceiling comes from the state file), so it stays cheap enough to run on every turn.\n\n### `agentburn context` — what a long context costs\n\nEvery call re-reads its whole context, and on a subscription that re-reading *is* the window: a turn at 300k costs what three turns at 100k cost. Claude Code records the exact context size of every call, so this is measured, not modelled:\n\n```text\n📏 agentburn context — claude-code · what a long context costs\n\n   CALLS                        156,226   median context 143K · p90 316K · max 704K\n\n   WHERE THE WINDOW GOES, BY CONTEXT SIZE\n   100–200k     ██████············   35%    59,780 calls\n   200–400k     ████████··········   43%    42,420 calls\n   >400k        ██················   11%     7,257 calls\n\n   IF YOU HAD RESTARTED AT…\n   /clear at 100K     →   41% of the window not spent   (108,573 calls were past it)\n   /clear at 150K     →   26% of the window not spent   (73,600 calls were past it)\n\n   WHAT A SKILL COSTS\n   handoff                                 7.96K per load ×  226 =     1.8M\n   claude-api                              33.6K per load ×   14 =     470K\n```\n\n- **The `/clear` arithmetic** — the part of every call's context above a threshold, at the cache-read rate: the honest saving of a restart habit, assuming the same work in shorter sessions.\n- **Skill costs, measured** — the context growth right after a lone `Skill` call, median of recent loads. Bundled skills never touch the disk; the transcript sees all of them.\n- **By effort level** — how much of the window each `effort` setting took.\n- Findings with a lever land in `agentburn fix`: the restart threshold, and the heavy skills.\n\n### `agentburn commits` — what a commit cost you\n\nSessions record their working directory and branch; your repositories record when each commit landed. The usage between two consecutive commits is what the second one cost — read-only `git log`, nothing written:\n\n```text\n   COSTLIEST COMMITS\n       124M   33_Thoforge        1f7a31a1  Aug 30  fix(ui): правки UX-аудита — раскладка, навигация\n      81.2M   33_Thoforge        ad19bff7  Aug 28  feat(ui): цель над деревом и развилка в карточке\n\n   BY REPOSITORY\n   33_Thoforge                 1.95M median ·  287 commits ·    1.52B total\n```\n\nWeighted tokens = tokens × *published* price ratios (cache read 0.1×, cache write 1.25×, output per model), normalized to one input token of the reference model. Every ratio is public; none of them is a guess about how the provider counts.\n\n### `agentburn` — the money view\n\n- **Where it burns** — by source: `cron` / `subagent` / `gateway:telegram|discord|whatsapp` / `cli`. Always-on ≠ free.\n- **🌙 While you slept** — the overnight bill, isolated and named (`--night 23-7`).\n- **Fixed overhead** — uncached input tokens per API call, per source, calibrated against a public benchmark.\n- **Subagent rollups** — delegation cost chained back to the session that spawned it.\n- **`agentburn why`** — behavioral forensics: re-read loops, retry storms, idle heartbeats, per-cron receipts, context thrash.\n- **`agentburn fix`** — ready-to-paste config patches, dry-run by design.\n\n## `agentburn fix` — findings become config, not advice\n\nNot \"consider a cheaper model\" but the exact file and the exact lines. Patch generators exist **only** for levers verified against the agent's own source or documented configuration:\n\n```text\n🔧 agentburn fix — claude-code · DRY-RUN (nothing was changed)\n\n   1. Drop 2 MCP server(s) you never called\n      why    : registered but not called once in the last 30d: blender-mcp, pixellab.\n               Every registered server ships its tool definitions with the context\n               of every session that loads it.\n      proposed:\n        claude mcp remove blender-mcp\n\n   2. Trim the always-loaded memory files (2,254 tokens)\n      why    : loaded into every session's context and re-sent whenever the prompt\n               cache expires or the context is compacted — at least 3,565× this window.\n```\n\n| Agent | Verified levers |\n|---|---|\n| Claude Code | registered MCP servers (`~/.claude.json`, `.mcp.json`), always-loaded `CLAUDE.md` memory files, the session-restart threshold (measured), heavy skills (measured per load) |\n| Hermes | per-job `model` / `enabled_toolsets` (`cron/jobs.py`), per-platform toolsets (`gateway/run.py`) |\n| OpenClaw | `heartbeat.{every, activeHours, model, lightContext}` (`config/types.agent-defaults.ts`) |\n\nThere is no `--apply` on purpose: it's your agent's config. Paste it yourself, then prove the saving with `--save-baseline` → `--compare`.\n\n## Why trust these numbers\n\nToken trackers quietly disagree with each other (2–91× in public issue threads). agentburn takes the opposite stance:\n\n- Numbers come from **the agent's own accounting**, read-only. No scraping, no proxies, no guessing.\n- **One reply is counted once.** Claude Code writes one transcript line per content block, each carrying the same `usage`; summing lines inflates calls and tokens ~1.8×. agentburn deduplicates by `requestId` (found and fixed in 0.14.0 — earlier absolute totals from this tool were inflated by that factor; ratios were not).\n- Provider-billed costs are shown as-is; estimates are marked `~`; mixed data is labeled mixed.\n- **Where a price doesn't exist, none is invented.** Claude Code records no costs and subscription usage has no honest per-token price — so that adapter reports tokens and windows, never dollars.\n- Sessions with messages but **zero recorded tokens** (known accounting gaps, e.g. [hermes-agent #12023](https://github.com/NousResearch/hermes-agent/issues/12023)) are detected: totals become an explicit **lower bound**, and fixing the accounting becomes recommendation #1.\n- Result weights on agents that don't record them are labeled *estimates*, and only ever used to rank findings against each other.\n\n## Speed\n\nTranscripts are append-only, so they are parsed once. Each file's parse is cached under its size and mtime in `~/.agentburn/cache`, and a run reuses every file that hasn't changed:\n\n| 30 days over 3.1 GB of Claude Code logs | |\n|---|---|\n| first run (parses everything, writes the cache) | ~190 s |\n| every run after that | **~3 s** |\n| cache size | 29 MB (0.9% of the logs) |\n\nA file that grew is re-parsed and re-cached; nothing else is touched. `--no-cache` (or `AGENTBURN_NO_CACHE=1`) forces a full re-parse, `--clear-cache` deletes it. The cache is derived data — deleting it costs time, nothing else.\n\n## Privacy\n\nEverything runs locally and reads your logs **read-only**. No network calls, no telemetry, no accounts. The report is yours. The only commands that touch the network say so: `drift` GETs a public trends file, `--submit` opens a prefilled issue *you* review and send.\n\nThe parse cache in `~/.agentburn/cache` (mode 0700) holds the same tool names and truncated argument keys the reports show, derived from logs already on this machine — never message content. `--clear-cache` removes it.\n\n## Why this exists\n\nAlways-on agents bill you around the clock — and their built-in counters only show totals:\n\n> *\"73% of every API call is fixed overhead — ~13.9K tokens of tool definitions and system prompt, resent every time.\"* — [hermes-agent #4379](https://github.com/NousResearch/hermes-agent/issues/4379)\n\n> *\"One entrant wrote about waking up to a **$47 surprise bill** from an overnight run — that's not an exotic failure, it's the default behavior of an unsupervised loop.\"* — [dev.to](https://dev.to/chintanonweb/hermes-agent-gets-smarter-every-day-so-does-the-bill-4i8o)\n\n## How it compares\n\n|  | **agentburn** | ccusage | codeburn | built-in `/usage` |\n|---|---|---|---|---|\n| Usage **windows** (peak vs typical, what filled them) | ✅ | — | — | current window only |\n| Ceiling measured from your own recorded cut-offs · time to wall · status line | ✅ | — | — | current window % |\n| The price of long contexts · what a `/clear` would have saved · skill cost per load | ✅ | — | — | — |\n| Cost per git commit | ✅ | — | — | — |\n| Burn by *source* (cron · heartbeat · gateways · subagents) | ✅ | — | — | % only, 7 days |\n| 🌙 the overnight bill, isolated | ✅ | — | — | — |\n| Behavioral forensics (`why`: loops, retry storms, failed-run cost) | ✅ | — | — | — |\n| Ready config patches (`fix`, verified levers) | ✅ | — | — | — |\n| MCP server (the agent answers for its own bill) | ✅ | — | — | — |\n| Totals / live blocks / many CLIs | basic | ✅ best-in-class | ✅ TUI, 25 providers | totals |\n\n*ccusage and codeburn are excellent at what they do — agentburn deliberately starts where they stop ([ccusage scoped per-tool analysis out](https://github.com/ryoppippi/ccusage/issues/688)).*\n\n## Supported agents\n\nOne normalized model, one adapter per agent. Run `agentburn` and every agent found on the machine gets its own report.\n\n| Agent | Status | Data source | Notes |\n|---|---|---|---|\n| **Claude Code** | ✅ | `~/.claude/projects/**.jsonl` | tokens and **windows**, by design: no local costs, no honest per-token price for a subscription |\n| **OpenClaw** | ✅ | `~/.openclaw/agents/*/sessions/sessions.json` | **heartbeat is its own category** — the famous one |\n| **Hermes Agent** | ✅ | `~/.hermes/state.db` (+ optional request dumps) | costs from the agent's own accounting |\n| **Codex CLI** | ✅ | `~/.codex/sessions/**/rollout-*.jsonl` | tokens and windows; the only agent that records the **provider's own usage %** with every request |\n| **Gemini CLI** | ✅ | `~/.gemini/tmp/*/chats/session-*.json` | per-turn tokens incl. thoughts; working directory via `projects.json` |\n| **opencode** | ✅ | `~/.local/share/opencode/opencode.db` | costs from the agent's own price list; free/self-hosted providers show tokens only |\n\nAdapters are ~150 lines over a shared model — PRs for the next one welcome.\n\n<div align=\"center\"><img src=\"assets/architecture.svg\" alt=\"architecture: agent data → adapters → normalized model → report/limits/why/fix/explain/doctor/mcp\" width=\"780\"></div>\n\n## Everything else\n\n<details>\n<summary><b>🔌 <code>agentburn mcp</code> — your agent answers for its own bill</b></summary>\n\nA zero-dependency MCP stdio server exposing `burn_report` / `burn_limits` / `burn_context` / `burn_commits` / `burn_why` / `burn_card`. Register it and ask *\"where do you burn my money?\"* — it profiles its own database and explains.\n\n```bash\nclaude mcp add agentburn -- agentburn mcp\n# Hermes / OpenClaw: add an stdio MCP server with command `agentburn mcp`\n```\n\nPrefer skills? There's a ready [`SKILL.md`](skill/README.md) for `~/.claude/skills/agentburn/` (or the Hermes/OpenClaw equivalents).\n</details>\n\n<details>\n<summary><b>📤 <code>--share</code> — an anonymized card, safe to post</b></summary>\n\nCategories, models and totals only; session titles, paths and content are excluded *by construction*. `--svg card.svg` renders the same card as an image.\n\n```text\n🔥 my claude-code agent · last 30d\n3.01B tokens · 19,255 API calls\nwhere it burns: cli 77% · subagent 23%\n⏳ my peak 5h window: 555M weighted tokens — 5.4× my own median window\n🌙 while I slept (00–08): 75.3M tokens — 3% of everything\n— agentburn · local & private\n```\n\n![sample burn card](assets/card-sample.svg)\n</details>\n\n<details>\n<summary><b>📐 <code>--save-baseline</code> / <code>--compare</code> — prove the saving</b></summary>\n\nSnapshot your pace, change the config, then `agentburn --compare` shows the delta — pace-normalized, so a 7-day baseline compares honestly with a 30-day window. Every recommendation becomes a testable promise.\n</details>\n\n<details>\n<summary><b>🧭 <code>agentburn drift</code> — your spend × the world's direction</b></summary>\n\nAre you paying for a model the world is leaving? Your side is computed locally; the world side is one read-only GET of [token-history](https://github.com/Socialpranker/token-history)'s public trend JSON (archived daily from OpenRouter's rankings). Nothing about you is sent anywhere; `--trends FILE` works fully offline.\n</details>\n\n<details>\n<summary><b>🧠 <code>agentburn explain</code> — LLM interpretation, local-first</b></summary>\n\n```bash\nagentburn explain --model llama3.1          # local ollama — nothing leaves the machine\nagentburn explain --llm https://openrouter.ai/api/v1 \\\n  --model deepseek/deepseek-chat --yes-remote --lang ru\n```\n\nThe default endpoint is localhost; a remote one requires `--yes-remote` and receives a **redacted** summary (titles → `session-N`, paths → basenames, content never present to begin with).\n</details>\n\n<details>\n<summary><b>🩺 <code>agentburn doctor</code> + 🚨 sentinel mode</b></summary>\n\n`doctor` names the broken combinations (provider × model × source) behind zero-usage and unpriced sessions, and generates a ready-to-paste upstream bug report — counters only.\n\nSentinel mode is a budget guard for server agents:\n\n```bash\nagentburn --agent openclaw --budget-night 5 --fail-over --no-color \\\n  || notify-send \"🚨 agent is burning money at night\"\n```\n</details>\n\n<details>\n<summary><b>📊 <code>agentburn rank</code> — the Burn Index (community percentiles)</b></summary>\n\nAnonymous percentiles of *efficiency* — the benchmark volume-leaderboards can't be: nothing here rewards burning more. Joining is consent-by-click: `agentburn --submit` prints the exact anonymized payload (ratios and a coarse spend band — never raw volumes, titles or paths), then a prefilled GitHub-issue link that **you** open and submit. Percentiles need 5+ setups per metric before they mean anything.\n</details>\n\n## Related\n\n[token-history](https://github.com/Socialpranker/token-history) — the macro view: daily archive of *which agents the world uses*. agentburn is the micro view: *where yours burns*.\n\n## License\n\nMIT\n\n<sub>mcp-name: io.github.Socialpranker/agentburn</sub>\n\n---\n\n<div align=\"center\">\n\n**the token-\\* family** · [token-history](https://github.com/Socialpranker/token-history) — which agents the world runs · **agentburn** — where yours burns\n\n*if this saved you a window's worth of work, a ⭐ helps the next person find it*\n\n</div>\n",
  "bytes": 19513,
  "sha": "d1ac38aab070d4de76587356479d77d7925fa532027fb423fdec317b0a72eabd",
  "repo_slug": "socialpranker/agentburn",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_socialpranker_agentburn_56ade535/readme"
}