Toolburn
Toolburn is a local token burn profiler for coding agents.
Think of it as ncdu for token usage: it scans the session evidence already on
your machine, groups spend by actor, tool, session, and source, then points at
the burn paths worth fixing.
Toolburn is read-only. It does not call models, intercept prompts, or upload anything. Phase 1 is an offline CLI for answering a very practical question:
What used the tokens, and was it a human session, a background job, or a tool loop?
Install
Install or update the command:
curl -fsSL https://raw.githubusercontent.com/CodePager/ToolBurn/main/install.sh | sh
toolburn --help
From a local checkout:
cd /srv/pager/repos/toolburn
./scripts/install-local.sh
toolburn --help
Start Here
toolburn recent --hours 24
That scans the default local session roots and prints the top actors and tools for the lookback window.
See supported evidence sources:
toolburn sources
Commands Humans Actually Use
Recent Burn
toolburn recent --hours 24 --limit 20
toolburn recent --hours 6 --limit 15
toolburn recent --hours 1 --limit 20
toolburn recent --hours 24 --no-scan
Human vs Background Spend
toolburn recent --hours 24 --actor-type background
toolburn recent --hours 24 --actor-type human
toolburn recent --hours 1 --actor-type background --limit 20
Scan Explicit Sources
toolburn scan --db /tmp/toolburn.sqlite --openclaw /root/.openclaw/agents/main/agent/codex-home/sessions --codex /root/.codex/sessions --copilot /root/.copilot/session-state
toolburn scan --db /tmp/toolburn.sqlite --codex /root/.codex/sessions
toolburn scan --db /tmp/toolburn.sqlite --openclaw /root/.openclaw/agents/main/agent/codex-home/sessions
toolburn scan --db /tmp/toolburn.sqlite --copilot /root/.copilot/session-state
toolburn scan --db /tmp/toolburn.sqlite --source codex=/path/to/rollout.jsonl
Rank Burn By Actor, Tool, Session, Or Source
toolburn top --db /tmp/toolburn.sqlite --by actor --since 2026-06-02T10:00:00.000Z
toolburn top --db /tmp/toolburn.sqlite --by tool --since 2026-06-02T10:00:00.000Z
toolburn top --db /tmp/toolburn.sqlite --by actor --actor-type background
toolburn top --db /tmp/toolburn.sqlite --by session --limit 30
toolburn top --db /tmp/toolburn.sqlite --by source --limit 30
toolburn du --db /tmp/toolburn.sqlite --by tool --actor-type human
Explain A Suspicious Actor Or Session
toolburn explain --db /tmp/toolburn.sqlite <actor-or-session-id> --for-agent
toolburn tree --db /tmp/toolburn.sqlite <actor-or-session-id>
toolburn export --db /tmp/toolburn.sqlite --target <actor-or-session-id>
Useful Investigation Patterns
Find background jobs burning tokens in the last hour:
toolburn recent --hours 1 --actor-type background --limit 20
Check whether a suspected fix actually stopped new burn after a timestamp:
toolburn top --db /tmp/toolburn-recent.sqlite --by actor --since 2026-06-03T11:29:40.000Z --actor-type background
Separate human coding work from agent automation:
toolburn recent --hours 24 --actor-type human
toolburn recent --hours 24 --actor-type background
Inspect one source file without scanning everything:
toolburn scan --db /tmp/one-session.sqlite --source codex=/path/to/rollout-2026-06-03.jsonl
toolburn top --db /tmp/one-session.sqlite --by tool
Run toolburn <command> --help for command-specific options. From this repo’s
checkout, ./toolburn also works without installation.
Source Support
| Source | Status | Default path | Notes |
|---|---|---|---|
| Codex | Supported | /root/.codex/sessions |
Reads rollout-*.jsonl token events. |
| OpenClaw | Supported | /root/.openclaw/agents/main/agent/codex-home/sessions |
Reads OpenClaw-owned Codex transcripts and labels known background actors. |
| GitHub Copilot CLI | Experimental | /root/.copilot/session-state |
Local Copilot installs keep session event logs at ~/.copilot/session-state/*/events.jsonl. Toolburn reads assistant.usage rows when present and session.shutdown.modelMetrics cumulative usage when that is the only token evidence. |
| Claude Code | Untested | ~/.claude |
Claude Code support is not confirmed yet. Anthropic documents settings under ~/.claude/settings.json, project settings under .claude/settings.json, and session-history controls such as cleanupPeriodDays, but Toolburn still needs a real Claude Code transcript sample before claiming support. |
Claude Code also uses CLAUDE.md instruction files, but those are context inputs,
not usage logs. Anthropic documents project/user locations such as ./CLAUDE.md,
./.claude/CLAUDE.md, and ~/.claude/CLAUDE.md.
References:
Current Status
Toolburn currently ships the Phase 1 offline profiler spine. It can scan local Codex/OpenClaw JSONL evidence into SQLite and report recent token burn by actor, session, source, or tool. GitHub Copilot CLI session-state parsing is experimental. Claude Code is listed as untested until a real local transcript is confirmed.
The active build plan is: