# Agentburn

> Answer questions about this agent's own token spend, usage limits and burn. Use when the user asks "how much am I spending", "where do my tokens go", "why do I keep hitting my limit", "what ate my 5-hour window", "what did you burn while I slept", "почему так дорого", "сколько я трачу", "почему упёрся в лимит", asks for a cost/usage breakdown, wants to cut the agent's bill, or asks what the agent has been doing (functions, loops, failures). Runs the local agentburn profiler (zero-dependency, read-only, nothing leaves the machine).

- Skill: `socialpranker/agentburn` (Agent Skill)
- Install (CLI): `npx skillmds@latest add socialpranker/agentburn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/socialpranker/agentburn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Socialpranker (https://skillmd.com/u/socialpranker)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/socialpranker/agentburn

---


# agentburn — the agent answers for its own bill

You have access to a local profiler that reads THIS agent's own accounting
database read-only. Use it instead of guessing about costs.

## How to answer a cost question

1. Make sure the CLI exists: run `uvx agentburn --version`
   (fallbacks: `pipx run agentburn --version`, `pip install agentburn`).
2. For "how much / where does it burn":
   run `uvx agentburn --json` and read: `total`, `monthly_projection`,
   `by_source` (cron / heartbeat / gateway:* / subagent / cli), `night`,
   `overhead_per_call`, `recommendations`.
3. For "what have you been doing / why is it expensive":
   run `uvx agentburn why --json` and read: `functions`, `rereads`,
   `storms`, `idle_heartbeats`, `failure_cost`, `observations`.
4. For "why did I hit my limit / what ate my window" (subscriptions —
   Claude Code Pro/Max — where the invoice is fixed and the window is not):
   run `uvx agentburn limits --json` and read: `peak` (the worst rolling
   5-hour window), `typical_window`, `peak_by_model`, `peak_by_source`,
   `mix`, `tips`. Lead with peak ÷ typical: a wall is hit by the peak.
   `ceiling` is measured from cut-offs Claude Code recorded itself
   (`ceiling_source: recorded`, `ceiling_hits`); `minutes_to_wall` is at
   the pace of the last 30 minutes. If there is no ceiling and the user
   remembers when they were cut off, re-run with `--hit "YYYY-MM-DD HH:MM"`.
   Never state an absolute limit: the provider's formula is not public.
   Codex CLI: `ceiling_source: provider` means the ceiling comes from the
   `used_percent` Codex records itself — an estimate, other devices on the
   account count too; `provider_used` is the latest raw reading.
   Gemini CLI and opencode: tokens only (opencode carries its own costs
   when the provider is priced); no cut-offs are recorded, so `ceiling`
   is absent unless `--hit` names one.
4b. For "why is my context so big / should I /clear / what does skill X
   cost": run `uvx agentburn context --json` and read `bands`, `savings`
   (`clear_at` → `share_not_spent`), `longest_sessions`, `by_effort`,
   `skills` (`tokens_per_load`, measured). Recommend the lowest `clear_at`
   that keeps most of the best saving.
4c. For "what did that commit / PR cost": run `uvx agentburn commits --json`
   and read `top` (costliest commits) and `repos` (median per repository).
5. For one channel ("what did you do in telegram?"):
   add `--source telegram` (or cron / heartbeat / subagent / cli).
6. Answer in the user's language, lead with the verdict
   (pace + dominant source), quote at most 3 numbers, then the single
   highest-impact change. Mark estimated costs with "~".

## Fixing things

- Offer `uvx agentburn fix` — it prints ready-to-paste config patches and
  NEVER applies them. Show the patch; apply only if the user explicitly
  confirms, and re-check with `agentburn --compare` afterwards
  (baseline first: `agentburn --save-baseline`).

## Honesty rules (do not skip)

- If the output warns about zero-usage sessions, say the totals are a
  LOWER BOUND and suggest `uvx agentburn doctor`.
- Numbers come from the agent's own accounting; do not invent prices or
  savings beyond what the tool prints.
- Never paste raw session titles or file paths into public channels;
  categories and counters only (the `--share` card is safe by design).