Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents.
Instrucciones de origen · Vista previa de solo lectura
name
bv
description
Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents.
BV - Beads Viewer
A graph-aware triage engine for Beads projects (.beads/beads.jsonl). Computes 9 graph metrics, generates execution plans, and provides deterministic recommendations. Human TUI for browsing; robot flags for AI agents.
Why BV vs Raw Beads
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
Use BV instead of parsing beads.jsonl directly. It computes graph metrics deterministically.
CRITICAL: Robot Mode for Agents
Never run bare bv. It launches an interactive TUI that blocks your session.
Always use --robot-* flags:
bv --robot-triage # THE MEGA-COMMAND: start here
bv --robot-next # Minimal: just the single top pick
bv --robot-plan # Parallel execution tracks
bv --robot-insights # Full graph metrics
The 9 Graph Metrics
BV computes these metrics to surface hidden project dynamics:
# 1. Start with triage
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo"$TRIAGE" | jq -r '.recommendations[0].id')
# 2. Check for cycles first (structural errors)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; thenecho"Fix cycles first: $CYCLES"fi# 3. Claim the task
br claim "$NEXT_TASK"# 4. Work on it...# 5. Close when done
br close "$NEXT_TASK"
TUI Views (for Humans)
When running bv interactively (not for agents):
Key
View
l
List view (default)
b
Kanban board
g
Graph view (dependency DAG)
E
Tree view (parent-child hierarchy)
i
Insights dashboard (6-panel metrics)
h
History view (bead-to-commit correlation)
a
Actionable plan (parallel tracks)
f
Flow matrix (cross-label dependencies)
]
Attention view (label priority ranking)
Integration with br CLI
BV reads from .beads/beads.jsonl created by the br CLI:
br init # Initialize beads in project
br create "Task title"# Create a bead
br list # List beads
br ready # Show actionable beads
br claim br-123 # Claim a bead
br close br-123 # Close a bead
bv --as-of HEAD~10 # 10 commits ago
bv --as-of v1.0.0 # At tag
bv --as-of "2024-01-15"# At date
bv --robot-diff --diff-since HEAD~30 # Changes in last 30 commits
