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)