Beads Viewer (bv)

Beads Viewer (bv)

Graph analysis layer for the Beads task graph. Precomputes metrics like PageRank and critical path.

When This Applies

---

CRITICAL RULE

Always use --robot-* flags. Never run bare bv.

Bare bv launches a TUI that will hang AI agents.

---

Session Kickoff

# Default (fast)
bv --robot-next                    # Single best next task

# Full triage bundle
bv --robot-triage                  # Blockers, quick wins, commands

---

Multi-Agent Partitioning

# Split work by parallel tracks
bv --robot-triage --robot-triage-by-track

# Track details + what each task unblocks
bv --robot-plan

---

Risk & Hygiene

Use before starting "big" work:

bv --robot-alerts                  # Stale issues, blocking cascades, drift
bv --robot-suggest                 # Duplicates, missing deps, cycle breaks

---

Debugging & Analysis

# What changed recently?
bv --robot-diff --diff-since HEAD~5

# Historical state
bv --as-of HEAD~10 --robot-triage

# Blocker analysis
bv --robot-blocker-chain bd-123

# Impact analysis before refactor
bv --robot-impact path/​to/​file1,path/​to/​file2
bv --robot-file-relations path/​to/​core_file

---

Handoff / Audit Trail

bv --robot-history --bead-history bd-123

---

Semantic Search

bv --search "your query" --robot-search

---

Graph Metrics Explained

---

Keeping bv Current

bv --check-update && bv --update --yes

---

Quick Reference

bv --robot-next              # Single best task (fast)
bv --robot-triage            # Full recommendations
bv --robot-triage --robot-triage-by-track   # Multi-agent
bv --robot-plan              # Execution order
bv --robot-alerts            # Risk signals
bv --robot-suggest           # Hygiene suggestions
bv --robot-blocker-chain ID  # Why is this blocked?

---

Anti-Patterns

---

See Also

• beads-cli/ — Task management with bd
• advance/ — Full bead lifecycle (claiming, working, closing)