Where the tokens went

npx @agentguard-run/burn why

Reads usage metadata your host already saved. Analysis runs locally. No session data is sent to AgentGuard.

Real local session output, re-rendered for readability. Across eight assistant responses the instruction stack plus system bucket totals 113,030 tokens, 86.0% of the recorded usage.

The session explains the split

That example was prefix-heavy. A long conversation can be history-heavy instead. Burn uses the recorded usage in the selected session and leaves missing evidence in an unattributed row.

Bucket	Tokens	List USD	Session share	Last turn share
Instruction stack + system	113,030	$0.08	86.0%	78.6%
History re-sent	14,000	$0.00	10.7%	20.2%
Re-read files	1,632	$0.01	1.2%	0.7%
Subagent fan-out	0	$0.00	0.0%	0.0%
Tool output	1,575	$0.01	1.2%	0.0%
Conversation	150	$0.00	0.1%	0.0%
Full-prefix rewrites	0	$0.00	0.0%	0.0%
Output	496	$0.00	0.4%	0.1%
Unattributed	487	$0.00	0.4%	0.4%

Eight assistant responses, 131,370 recorded tokens, $0.10 API list equivalent. Token shares are shares of usage, not shares of dollars. Usage deltas supply the measured totals; recorded event byte sizes only split those totals between events. Every report includes a Method footer.

Install in five lines

1. Install and print the host configuration to review.

   npm i -g @agentguard-run/burn
   agentguard-burn init claude
   agentguard-burn init codex

2. Merge the printed snippet for your host into its configuration. The init commands do not write settings. In Codex, review and trust the hook through /hooks.
3. Run the first report.

   agentguard-burn why

Without a session argument, Burn uses an available session environment variable, then the most recently modified local transcript. A session argument can also be a transcript path.

Claude Code status line

Set the statusLine command to agentguard-burn statusline. Burn reads the host JSON on stdin and shows pace, last-turn context, rewrite dollars today and a limit forecast when the supplied percentages support one.

settings.json

{
  "statusLine": {
    "type": "command",
    "command": "agentguard-burn statusline"
  }
}

Codex companion line

Codex 0.154 has no external status command slot. Run agentguard-burn statusline SESSION_ID in a companion terminal and use the host’s native limit indicators.

The commands

why

agentguard-burn why SESSION_ID shows tokens, API list dollars, share of the session and share of the last turn. It covers repeated file reads, child transcripts and the residual it cannot attribute.

pace

agentguard-burn pace SESSION_ID separates cached and uncached tokens per minute over a ten-minute window, then projects the next hour. Minutes to a limit appear only when fresh host usage percentages support a forecast.

rewrites

agentguard-burn rewrites all groups large cache writes by the surrounding evidence: idle beyond the cache lifetime, compaction, a subagent start or a prefix change. A rewrite means more than 150,000 cache-creation tokens and more than half of that turn’s context.

blocks

agentguard-burn blocks all prints every STOP and WARN with the measured economics of that session’s own spawns: count, median and max tokens, list-price dollars, forks versus fresh agents.

The circuit breaker

Replay first: npx @agentguard-run/burn replay evaluates your own history and shows where the breaker would have stopped. Hooks start in shadow mode. When you turn on enforce, three detectors decide.

flowchart TD
  E[Tool event from the host] --> F{Lifetime fan-out}
  F -->|over the ceiling| W1[WARN only]
  E --> S{Spawn rate: 8 warn, 16 stop per 15 active minutes}
  S -->|over 16| STOP1[STOP card, spawn blocked]
  E --> D{Depth over 2}
  D -->|yes| STOP2[STOP]
  E --> T{Sustained burn over the STOP ceiling in 120 active minutes}
  T -->|yes| STOP3[STOP]
  STOP1 --> O[override once: agentguard-burn resume --once --reason]
  STOP2 --> O
  STOP3 --> O

A real STOP on Sep 19 2026: sixteen spawns in fifteen active minutes.

Crossing 500,000 context tokens produces an advisory about processing time and compaction. The rewrite-dollar and heavy-turn thresholds are configurable in burn-policy.json. Advisories never block a tool call; only the breaker does, and only in enforce mode.

What the numbers mean

• Burn cannot see your real subscription quota. A forecast follows explicit host percentage samples when available; it never invents an allowance.
• Dollar columns use the recorded model’s API list rate. They are not your subscription bill. Run agentguard-burn pricing for each rate’s source and date.
• The instruction stack plus system row is a fixed-prefix baseline including initial user content, not a direct token count of instruction files.
• Single machine. No prompts, responses or file contents are stored or rendered. No telemetry.