bead-metrics

name	bead-metrics
model	sonnet
description	Query per-bead token cost metrics from the local agent metrics database. Shows cost table, impl:review ratios, most expensive beads, cost trend over time. Triggers on: bead metrics, token cost report, bead costs, /bead-metrics.
requires_standards	["english-only"]

Bead Metrics Report

Query the local agent metrics database and output a formatted cost report.

Arguments

• (empty) — Full report (all beads)
• --top=N — Show only top N most expensive beads (default: all)
• --bead=<id> — Show single bead details
• --wave=<id> — Show wave-aggregated report (Phase 2 findings, model attribution)
• --adhoc — Show per-subagent ad-hoc breakdown (phase_label='adhoc', grouped by agent_label)

Workflow

Parse arguments from {ARGS}:

• If --top=N present, extract N as integer and pass as top=N
• If --bead=<id> present, extract id and pass as bead_id="<id>"
• If --wave=<id> present, extract id and use query_wave_report(wave_id="<id>")
• If --adhoc present, use query_adhoc_report()
• Otherwise pass no arguments (full report)

Run the query script, passing the parsed arguments:

scripts/run-query.sh [--top=N | --bead=ID | --wave=ID | --adhoc]

Argument Examples

Full report:

uv run python -c "
import os, sys; sys.path.insert(0, os.path.join(os.environ['CLAUDE_PLUGIN_ROOT'], 'lib'))
from orchestrator.metrics import query_report
print(query_report())
"

Top 5 most expensive:

uv run python -c "
import os, sys; sys.path.insert(0, os.path.join(os.environ['CLAUDE_PLUGIN_ROOT'], 'lib'))
from orchestrator.metrics import query_report
print(query_report(top=5))
"

Single bead detail:

uv run python -c "
import os, sys; sys.path.insert(0, os.path.join(os.environ['CLAUDE_PLUGIN_ROOT'], 'lib'))
from orchestrator.metrics import query_report
print(query_report(bead_id='claude-i7it'))
"

Wave report:

uv run python -c "
import os, sys; sys.path.insert(0, os.path.join(os.environ['CLAUDE_PLUGIN_ROOT'], 'lib'))
from orchestrator.metrics import query_wave_report
print(query_wave_report(wave_id='wave-20260412-140000'))
"

Ad-hoc agent breakdown:

uv run python -c "
import os, sys; sys.path.insert(0, os.path.join(os.environ['CLAUDE_PLUGIN_ROOT'], 'lib'))
from orchestrator.metrics import query_adhoc_report
print(query_adhoc_report())
"

Output Format

Empty DB

No data yet — implement some beads first.

Ad-hoc Agent Breakdown (--adhoc)

## Ad-hoc Agent Usage

| Agent | Calls | Tokens | Model |
|-------|-------|--------|-------|
| impl-sonnet | 12 | 245,000 | claude-sonnet-4-6 |
| review-opus | 4 | 98,000 | claude-opus-4-5 |

Normal Report

## Bead Token Cost Report

### Summary
Total beads tracked: 12
Total tokens consumed: 4,231,088
Avg tokens per bead: 352,590
Avg impl:review ratio: 2.8:1

### Most Expensive Beads
| Bead | Date | Impl | Review (N iter) | Verify | Total | Ratio |
|------|------|------|----------------|--------|-------|-------|
| claude-i7it | 2026-04-05 | 81,079 | 92,007 (3x) | 30,517 | 235,244 | 0.9:1 |

### Impl:Review Ratio Distribution
< 1:1  (review-heavy): 2 beads — impl was messy
1-3:1  (balanced):     7 beads
> 3:1  (clean impl):   3 beads

### Weekly Trend
| Week | Beads | Avg Tokens |
|------|-------|-----------|
| 2026-W14 | 3 | 287,000 |

Error Handling

If the script fails (import error, DB locked), report the error message. Common causes:

• CLAUDE_PLUGIN_ROOT env var not set — the beads-workflow plugin is not active
• The local agent metrics database does not exist — no bead has been tracked yet
• orchestrator.metrics import fails — the lib/ directory inside the plugin is missing or corrupt