@agentguard-run/burn weekly downloads statistics

@agentguard-run/burn

npx agentguard-burn why

See where a coding session's tokens went and what the next heavy turn could cost in time and limits. Burn explains recorded usage, warns about large cache rewrites and keeps its existing runaway-session circuit breaker. Runtime observation and enforcement stay on this machine. The developer review command below has an explicit external-ranking option.

Start here

npx agentguard-burn why         # your last session
npx agentguard-burn calendar    # every day
npx agentguard-burn card        # an image to share

Press y if npm asks to install Burn. Plain npx agentguard-burn shows these three starting points. Use npx agentguard-burn --help all for every command and option.

Burn prints its installed version on the first line of every why and calendar text report, including the empty message. JSON reports include a version field. npx agentguard-burn --version (or -v) prints only the installed version.

Simple and detailed views

statusline, why and live default to simple; compact-replay defaults to detailed so its table shows. Save a preference with agentguard-burn mode simple or agentguard-burn mode detailed. It lives in AGENTGUARD_HOME/burn-config.json, normally under ~/.agentguard. AGENTGUARD_BURN_MODE overrides it. Per-command simple and detailed flags, prefixed by two hyphens, override both. Detailed output and JSON stay unchanged.

Subscriptions show real host percentages, reset times and time left at the observed pace, or "limit not available". They never show dollars. Explicit API or usage-credit sessions show today's host-reported dollars and the recent pace per hour, never a projected day total. Missing evidence stays unavailable. There is at most one next step, in English, Spanish or Portuguese.

Existing users see this once on stderr: "Showing the simple view. For tokens and cache detail: agentguard-burn mode detailed". See evidence, projections and verification for the supported metadata and limitations.

No sessions yet

With no sessions, why, calendar and card print the same guidance to stdout and exit 0. This is a normal first run. No card image is created. Burn lists the actual folders it checked, then prints:

No Claude Code or Codex sessions found on this computer yet.
Burn looked in <the actual folders it checked>.
Next: if you use Claude Code on another computer, run this there.
If Claude Code is new here, use it for a few minutes, then run npx agentguard-burn why again.

By default Burn checks ~/.claude/projects and ~/.codex/sessions. When CLAUDE_CONFIG_DIR is set, it checks CLAUDE_CONFIG_DIR/projects instead of the Claude default. When CODEX_HOME is set, it checks CODEX_HOME/sessions instead of the Codex default. Unset or empty variables keep the home-folder defaults.

npx agentguard-burn why --json always writes JSON to stdout. No sessions gives found: false, looked_in, message, next and version, with exit 0. A successful session report includes found: true and version. Invalid arguments exit 64; a missing requested session or a read failure exits 4. Both errors include an error field in JSON mode. calendar also returns the empty JSON object when asked for JSON on a machine with no sessions.

week

agentguard-burn week
agentguard-burn week --week 2026-09-28 json
agentguard-burn week --lang es

See your own machine's last completed week first: useful work, waste causes, unattributed usage, the largest cause that stands out and one concrete fix. Weeks start Monday at 00:00 UTC and end the next Monday at 00:00 UTC. An explicit date must be a Monday. English, Spanish and Portuguese are supported. With no transcripts, week uses the same first-run guidance as why.

Shares lead with API list price, not a bill. Cache reads usually cost about a tenth of fresh input. If any response has no list price, every dollar field is null and shares use tokens instead. Useful work is instruction stack, tool output, conversation and output. Waste causes are re-sent history, re-read files, sub-agent fan-out and full reloads. Unattributed tokens remain separate. Sub-agents on the main model are an overlapping subset, never another partition bucket. The only counterfactual reprices that subset on claude-haiku-5-5. The headline describes what was spent on waste causes and promises no savings.

Burn uses the midpoint of each dollar range and rounds each leaf bucket once to integer micro-dollars. Useful, waste, reload and overall totals sum the rounded buckets. Reload leaves are idle, model switch and other. Fan-out stands out at 20% of tokens, reloads at 15% of known spend, re-sent history at 30% of tokens and re-read files at 10%. The largest at list price wins, or tokens when unpriced, with ties in that order. Fan-out becomes the main-model cause when at least half of sub-agent tokens belong to that subset. Reload ties prefer idle, then model switch, then other.

After displaying the figures, Burn atomically saves AGENTGUARD_HOME/week/YYYY-MM-DD.json (default ~/.agentguard/week/), with directory mode 0700 and file mode 0600. Only complete, nonempty weeks started within the last 28 days are saved, since Claude Code normally keeps transcripts for 30 days. Older or partial weeks can be viewed locally. The saved file has exactly schema, weekStart, viewedAt and figures; see the v1 fixture. Local diagnostics, including excluded forks, undated tokens and unpriced model ids, never enter it. week json prints those diagnostics under local, and saved reports whether the file was written.

Five hard lines apply to weekly sharing:…