AgentGuard Burn · Free · Local · 0.2.5

Where did this session's tokens go?

See the measured split between the fixed prefix, repeated history, tool results and output. Track the pace of a long session and the cache rewrites that change its cost.

npx @agentguard-run/burn why

Reads usage metadata already saved by your host. 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 + system bucket totals 113,030 tokens, or 86.0% of the recorded usage. This is a cumulative fixed-prefix attribution: the first measured context plus the matching cached prefix on later turns. The baseline includes initial user content alongside the system prompt and tool schemas.

The session explains the split.

The example above 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.

Read the measured table from the clip

Eight assistant responses. 131,370 recorded tokens. $0.10 API list equivalent. Token shares are shares of usage, not shares of dollars.

Bucket	Tokens	List USD	Session tokens	Last turn tokens
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%

Usage deltas supply the measured token totals. Recorded event byte sizes only split those totals between events; bytes are never converted into tokens. Every report includes a Method footer that explains each bucket.

Read the cost of a long session.

Why this session

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.

Full-prefix rewrites

agentguard-burn rewrites all groups large cache writes by the surrounding evidence: idle beyond the observed cache lifetime, compaction, a subagent start or a remaining prefix change. It reports counts, tokens and API list dollars.

A rewrite means more than 150,000 cache-creation tokens and more than half of that turn's context. The default advisory warns when rewrite cost in the last hour exceeds $5.

Pace and the next hour

agentguard-burn pace SESSION_ID separates cached and uncached tokens per minute over a ten-minute window, then projects the next hour at that pace. Hooks update the local pace record on tool events.

Minutes to a limit appear only when fresh host usage percentages support a forecast. Missing or stale evidence stays unknown.

A heavy turn, before the next one

Crossing 500,000 context tokens produces an advisory about processing time and compaction. It estimates a cache rewrite and suggests a fresh session with a handoff note. Cache reads are cheap; a large context is also a question of time and limits.

The rewrite-dollar and heavy-turn thresholds are configurable in burn-policy.json. These warnings do not block a tool call.

Install in five lines.

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

The init commands print configuration for review. Merge the snippet for your host into its configuration. They do not write settings. In Codex, review and trust the hook through /hooks.

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.

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

Combine it with your existing status script if you already use one.

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.

For tool policy, signed decisions and paid enforcement in Codex and ChatGPT Work, see the AgentGuard plugin.

What the numbers mean.

It cannot see your real subscription quota. A forecast follows explicit host percentage samples when available; it does not invent a token allowance or a cache-read weighting.
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; unknown models show tokens only. A local pricing override can supply your verified rates.
The instruction stack + system row is a fixed-prefix baseline, including initial user content. It is not a direct token count of instruction files. Prefix-change rewrites reset the baseline and the footer reports those resets.
Cache-rewrite causes reflect surrounding metadata. An unknown cache lifetime remains unknown, and pricing uses a range when the lifetime cannot be established.
Single machine. Other devices do not share this local state.
No prompts, responses, or file contents are stored or rendered. No telemetry.

Replay first when considering the existing runaway-session circuit breaker: npx @agentguard-run/burn replay evaluates your own history. Hooks start in shadow mode. Replay's post-STOP tail is an upper bound, and its legacy counters can differ from the response-reconciled why report.

Burn package and README Read the docs Install the Codex plugin