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).