Beads Viewer (bv)

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

When This Applies

| Signal | Action | |--------|--------| | "What should I work on?" | bv --robot-triage | | Need single best task | bv --robot-next | | Multi-agent partitioning | bv --robot-triage --robot-triage-by-track | | Risk/hygiene check | bv --robot-alerts | | Finding blockers | bv --robot-blocker-chain |

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

| Metric | Meaning | Use For | |--------|---------|---------| | PageRank | Foundational blockers | Tasks that enable many others | | Betweenness | Bottlenecks | Must pass through these | | Critical Path | Longest dependency chain | Overall timeline |

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

| Don't | Why | |-------|-----| | Run bare bv | Launches TUI, hangs agent | | Ignore --robot-alerts | Miss stale/risky work | | Skip before big work | Miss blocking cascades |

beads-viewer