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:

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 Two-Phase Analysis

BV uses async computation with timeouts:

Phase 1 (instant): degree, topo sort, density Phase 2 (500ms timeout): PageRank, betweenness, HITS, eigenvector, cycles

Always check status field in output. For large graphs (>500 nodes), some metrics may be approx or skipped.

Robot Commands Reference Triage & Planning bv --robot-triage # Full triage: recommendations, quick_wins, blockers_to_clear bv --robot-next # Single top pick with claim command bv --robot-plan # Parallel execution tracks with unblocks lists bv --robot-priority # Priority misalignment detection

Graph Analysis bv --robot-insights # Full metrics: PageRank, betweenness, HITS, cycles, etc. bv --robot-label-health # Per-label health: healthy|warning|critical bv --robot-label-flow # Cross-label dependency flow matrix bv --robot-label-attention # Attention-ranked labels

History & Changes bv --robot-history # Bead-to-commit correlations bv --robot-diff --diff-since # Changes since ref

Other Commands bv --robot-burndown # Sprint burndown, scope changes bv --robot-forecast # ETA predictions bv --robot-alerts # Stale issues, blocking cascades bv --robot-suggest # Hygiene: duplicates, missing deps, cycle breaks bv --robot-graph # Dependency graph export (JSON, DOT, Mermaid) bv --export-graph # Self-contained interactive HTML visualization

Scoping & Filtering bv --robot-plan --label backend # Scope to label's subgraph bv --robot-insights --as-of HEAD~30 # Historical point-in-time bv --recipe actionable --robot-plan # Pre-filter: ready to work bv --recipe high-impact --robot-triage # Pre-filter: top PageRank bv --robot-triage --robot-triage-by-track # Group by parallel work streams bv --robot-triage --robot-triage-by-label # Group by domain

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 includes:

data_hash - Fingerprint of beads.jsonl (verify consistency) status - Per-metric state: computed|approx|timeout|skipped as_of / as_of_commit - Present when using --as-of --robot-triage Output { "quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] }, "recommendations": [ { "id": "bd-123", "score": 0.85, "reason": "Unblocks 5 tasks", "unblock_info": {...} } ], "quick_wins": [...], "blockers_to_clear": [...], "project_health": { "distributions": {...}, "graph_metrics": {...} }, "commands": { "claim": "bd claim bd-123", "view": "bv --bead bd-123" } }

--robot-insights Output { "bottlenecks": [{ "id": "bd-123", "value": 0.45 }], "keystones": [{ "id": "bd-456", "value": 12.0 }], "influencers": [...], "hubs": [...], "authorities": [...], "cycles": [["bd-A", "bd-B", "bd-A"]], "clusterDensity": 0.045, "status": { "pagerank": "computed", "betweenness": "computed", ... } }

jq Quick Reference bv --robot-triage | jq '.quick_ref' # At-a-glance summary bv --robot-triage | jq '.recommendations[0]' # Top recommendation bv --robot-plan | jq '.plan.summary.highest_impact' # Best unblock target bv --robot-insights | jq '.status' # Check metric readiness bv --robot-insights | jq '.cycles' # Circular deps (must fix!) bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'

Agent Workflow Pattern

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" != "[]" ]; then echo "Fix cycles first: $CYCLES" fi

3. Claim the task

bd claim "$NEXT_TASK"

4. Work on it...

5. Close when done

bd 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 bd CLI

BV reads from .beads/beads.jsonl created by the bd CLI:

bd init # Initialize beads in project bd create "Task title" # Create a bead bd list # List beads bd ready # Show actionable beads bd claim bd-123 # Claim a bead bd close bd-123 # Close a bead

Integration with Agent Mail

Use bead IDs as thread IDs for coordination:

file_reservation_paths(..., reason="bd-123") send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")

Graph Export Formats bv --robot-graph # JSON (default) bv --robot-graph --graph-format=dot # Graphviz DOT bv --robot-graph --graph-format=mermaid # Mermaid diagram bv --robot-graph --graph-root=bd-123 --graph-depth=3 # Subgraph bv --export-graph report.html # Interactive HTML

Time Travel

Compare against historical states:

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

Common Pitfalls Issue Fix TUI blocks agent Use --robot-* flags only Stale metrics Check status field, results cached by data_hash Missing cycles Run --robot-insights, check .cycles Wrong recommendations Use --recipe actionable to filter to ready work Performance Notes Phase 1 metrics (degree, topo, density): instant Phase 2 metrics (PageRank, betweenness, etc.): 500ms timeout Results cached by data_hash Prefer --robot-plan over --robot-insights when speed matters