AgentGuard Burn analyzes local Claude Code and Codex transcripts to show where session tokens went and identify the most relevant next step.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agentguard-burn
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install agentguard-burn using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is AgentGuard Burn?
AgentGuard Burn is a free command-line tool for investigating Claude Code and Codex usage limits, high-token sessions, and suspected runaway sub-agents. It reads session transcripts on the user's machine and reports token usage by source, including conversation history, files, tool output, and sub-agent activity. Nothing is uploaded.
As an Openclaw Skills workflow, it helps turn usage data into an actionable explanation without treating API list prices as a subscription bill or promising token savings. The report's optional Next: line provides the one action its measurements identify as most relevant.
AgentGuard Burn Use Cases
- A user reaches a Claude Code or Codex usage limit and wants to understand what consumed tokens.
- A coding session used tokens unusually quickly, and the user wants to identify the largest contributors.
- The user suspects sub-agents fanned out excessively or stopped before completing work.
- The user wants to compare two sessions, review token usage by day, or inspect full-prefix cache rewrites.
- The user asks for a local safeguard that limits sub-agent launches, subject to explicit approval before plugin installation.
How AgentGuard Burn Works
- Run
npx agentguard-burn whyon the user's machine. With no session argument, Burn selects the most recently modified local Claude Code or Codex transcript; Claude Code sub-agent transcripts are included. - Optionally select a specific session by passing its ID, the end of its ID, or its transcript path.
- Read the report header for the session, response count, total tokens, and the API list equivalent. Explain that the dollar figure is not a bill, and that subscription users should focus on token counts against their limits.
- Review the token breakdown and point out the largest rows by token share. Token shares represent tokens, not dollars.
- Explain any
Measured change:line as a measurement after an event such as/compact, a model switch, or/clear, not as a guaranteed saving. - If present, quote the report's single
Next:line exactly. If there is no such line, say that nothing stood out rather than inventing advice. - Offer the optional AgentGuard plugin only when the report's next step points to it or the user asks for sub-agent limits; ask for permission before installation.
AgentGuard Burn Setup
Requirements: Node.js 20 or later, npx, and network access to npm for the first run. Burn reads local Claude Code and Codex transcripts.
Run the report:
npx agentguard-burn why
Choose a particular session by ID, partial ID, or transcript path:
npx agentguard-burn why SESSION_ID
Inside Claude Code, the user can also run:
! npx agentguard-burn why
The first run downloads the package from npm. Installing the optional plugin is a separate action and requires the user's approval.
Claude Code plugin installation:
claude plugin marketplace add MerchantGuard/agentguard-codex-plugin
claude plugin install agentguard@agentguard
Codex or the ChatGPT desktop app for local tasks:
codex plugin marketplace add MerchantGuard/agentguard-codex-plugin
codex plugin add agentguard@agentguard
After Codex reports the installed plugin folder, run npm ci in that folder. The plugin must not be installed without the user's yes.
AgentGuard Burn Data Schema & Taxonomy
Burn analyzes existing local session transcripts; the skill does not specify a separate export format or generated transcript archive. Its report organizes findings into:
| Report element | Information |
|---|---|
| Header | Session, response count, total tokens, and API list equivalent |
| Token breakdown | Instruction stack and system, history re-sent, re-read files, sub-agent fan-out, tool output, conversation, full-prefix rewrites, output, and unattributed tokens |
| Measurement line | Optional Measured change: after events such as /compact, a model switch, or /clear; it reports a measurement, not a saving |
| Recommendation | At most one Next: action selected from the session's numbers |
The local analysis keeps transcript contents on the machine. Do not copy or upload transcript contents. API list equivalent figures are not bills, and token-share percentages are not dollar-share percentages.
AgentGuard Burn Advanced Features
- Includes Claude Code sub-agent transcripts when analyzing a session, making sub-agent fan-out visible in the token breakdown.
- Provides
npx agentguard-burn calendarfor tokens per day across Claude Code and Codex, with sub-agent days marked. - Provides
npx agentguard-burn comparefor a side-by-side review of two sessions. - Provides
npx agentguard-burn rewritesto list full-prefix cache rewrites and their causes. - Supports
npx agentguard-burn quiet onto hide theNext:tip andnpx agentguard-burn quiet offto show it again. - The optional free AgentGuard plugin applies local sub-agent limits: 15 launches in any 15 active minutes, 40 in any 120 active minutes, 5 billion tokens in one session, and a maximum depth of two sub-agent levels.
- In Claude Code's default, accept edits, auto, or plan mode, a launch beyond a limit waits for the user's permission. In Codex and Claude Code bypass-permissions, don't-ask, or print modes, the launch is blocked with a STOP box; Codex does not prompt for approval.
- Users can switch plugin behavior with
npx agentguard-burn shadowfor record-only mode andnpx agentguard-burn enforceto return to enforcement. The agent must not run override, shadow, or calibrate commands on the user's behalf. - Plugin hooks run locally and open no network connection. Free use sends nothing unless the user requests an AgentGuard Score.
SKILL.md
Loading
Related Openclaw Skills
Unusual Whales API
Query verified Unusual Whales market-data endpoints for options flow, dark pool activity, sentiment, financials, and technical indicators.
Podcast Robot
Podcast Robot connects an AI agent to podcast discovery, episode, transcript, live-stream, and feed tools through a public MCP server.
DIN Whitepaper Knowledge Base
A focused Openclaw Skills knowledge base for exploring the Distributed Inference Network (DIN) whitepaper, its architecture, collaboration patterns, and networking technologies.
TCM Medical Record Writing Standard
A searchable reference to China’s trial standard for traditional Chinese medicine and integrative medical record writing, including required contents and completion deadlines.
AgentScope Config Validator
Validate an AgentScope 2.0 project’s key configuration files and catch setup issues before running agents.
AgentScope Dependency Updater
Review an AgentScope project's dependencies and get upgrade candidates and safety notes without changing any files.
Featured*
