Beads Viewer
Overview
Beads Viewer (BV) is a graph-aware triage engine for Beads projects. It computes 9 graph metrics, generates execution plans, and provides deterministic recommendations.
When to use: Triaging beads tasks, analyzing dependency graphs, finding bottlenecks, detecting circular dependencies, planning parallel execution tracks, generating sprint burndown data, comparing historical project states.
When NOT to use: Simple bead CRUD operations (use bd CLI instead), projects without .beads/.
IMPORTANT — JSONL prerequisite: BV reads from .beads/issues.jsonl, NOT from the SQLite database directly. If the JSONL file is empty or stale, BV will return zero issues with data_hash: "empty". Before running BV, ensure the JSONL is populated:
bd export -o .beads/issues.jsonl
Re-export after any bd CRUD operations to keep BV data current.
| Capability | Raw beads.jsonl | BV Robot Mode |
|---|---|---|
| Query | "List all issues" | "List the top 5 bottlenecks blocking the release" |
| Context Cost | High (linear with issue count) | Low (fixed summary struct) |
| Graph Logic | Agent must compute | Pre-computed (PageRank, betweenness, cycles) |
| Safety | Agent might miss cycles | Cycles explicitly flagged |
Quick Reference
| Command | Purpose | Key Points |
|---|---|---|
bv --robot-triage | Full triage with recommendations | Start here; includes quick_wins and blockers |
bv --robot-next | Single top pick with claim command | Minimal context cost |
bv --robot-plan | Parallel execution tracks | Faster than --robot-insights |
bv --robot-insights | Full graph metrics (all 9) | Check status field; expensive |
bv --robot-priority | Priority misalignment detection | Flags misprioritzed items |
bv --robot-alerts | Stale issues, blocking cascades | Proactive health checks |
bv --robot-suggest | Hygiene: duplicates, missing deps | Includes cycle break suggestions |
bv --robot-graph | Dependency graph export | Default JSON; use -graph-format mermaid|dot |
bv --recipe <name> --robot-<cmd> | Pre-filter before any robot command | Recipes: actionable, high-impact, bottlenecks |
bv --robot-triage --label <name> | Scope to label subgraph | Reduces noise for focused analysis |
CRITICAL: Never run bare bv from an agent session. It launches an interactive TUI that blocks the session. Always use --robot-* flags.
The 9 Graph Metrics
| Metric | What It Measures | Key Insight |
|---|---|---|
| PageRank | Recursive dependency importance | Foundational blockers |
| Betweenness | Shortest-path traffic | Bottlenecks and bridges |
| HITS | Hub/Authority duality | Epics vs utilities |
| Critical Path | Longest dependency chain | Keystones with zero slack |
| Eigenvector | Influence via neighbors | Strategic dependencies |
| Degree | Direct connection counts | Immediate blockers/blocked |
| Density | Edge-to-node ratio | Project coupling health |
| Cycles | Circular dependencies | Structural errors (must fix!) |
| Topo Sort | Valid execution order | Work queue foundation |
Metrics compute in two phases: Phase 1 (degree, topo sort, density) is instant; Phase 2 (PageRank, betweenness, HITS, eigenvector, cycles) has a 500ms timeout. Always check the status field in output.
Built-in Recipes
| Recipe | Purpose |
|---|---|
default | All open issues sorted by priority |
actionable | Ready to work (no blockers) |
high-impact | Top PageRank scores |
blocked | Waiting on dependencies |
stale | Open but untouched for 30+ days |
triage | Sorted by computed triage score |
quick-wins | Easy P2/P3 items with no blockers |
bottlenecks | High betweenness nodes |
Robot Output Structure
All robot JSON output includes these standard fields:
| Field | Purpose |
|---|---|
data_hash | Fingerprint of beads.jsonl for verifying consistency |
status | Per-metric state: computed, approx, timeout, or skipped |
as_of / as_of_commit | Present when using --as-of for time travel queries |
Key output sections by command:
- •--robot-triage:
triage.quick_ref,triage.recommendations,triage.quick_wins,triage.blockers_to_clear,triage.project_health,triage.commands - •--robot-insights:
Bottlenecks,Keystones,Influencers,Hubs,Authorities,Cycles(note: PascalCase keys) - •--robot-plan:
plan.tracks(parallel work streams),plan.summary.highest_impact - •--robot-priority:
summary,recommendations(priority misalignment findings) - •--robot-alerts:
alerts,summary(stale issues, blocking cascades) - •--robot-suggest:
suggestions(hygiene recommendations)
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Running bare bv from an agent session | Always use --robot-* flags; bare bv launches an interactive TUI that blocks the agent |
Ignoring the status field in robot output | Always check per-metric status; large graphs may have approx or skipped metrics due to 500ms timeout |
Using --robot-insights when only the next task is needed | Use --robot-next for a single top pick or --robot-triage for quick recommendations; insights is expensive |
| Not checking for cycles before starting implementation | Run bv --robot-insights and check .cycles first; circular dependencies are structural errors that must be resolved |
| Parsing stderr as JSON data | Only stdout contains JSON; diagnostics and warnings go to stderr |
| Stale metrics after bead changes | Check data_hash field; results are cached by beads.jsonl fingerprint |
| Wrong recommendations for current work | Use --recipe actionable to filter to only unblocked, ready-to-work items |
BV returns 0 issues / data_hash: "empty" | JSONL is empty or stale. Run bd export -o .beads/issues.jsonl before BV commands |
Using --format mermaid for graph export | The correct flag is -graph-format mermaid (separate from --format which controls JSON/toon output) |
Delegation
- •Analyze project dependency health and bottlenecks: Use
Taskagent to run BV robot commands and summarize graph metrics - •Plan sprint work from triage output: Use
Planagent to interpret triage recommendations and build execution tracks - •Search for related beads context: Use
Exploreagent to investigate bead descriptions and find implementation patterns