Beads Viewer

Overview

Beads Viewer (BV) is a graph-aware triage engine for Beads projects (.beads/beads.jsonl). It computes 9 graph metrics, generates execution plans, and provides deterministic recommendations.

When to use: Triaging beads tasks, analyzing dependency graphs, finding bottlenecks, detecting circular dependencies, planning parallel execution tracks, generating sprint burndown data, comparing historical project states.

When NOT to use: Parsing raw beads.jsonl directly (BV pre-computes graph metrics), simple bead CRUD operations (use bd CLI instead), projects without .beads/beads.jsonl.

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

Quick Reference

Command	Purpose	Key Points
bv --robot-triage	Full triage with recommendations	Start here; includes quick_wins and blockers
bv --robot-next	Single top pick with claim command	Minimal context cost
bv --robot-plan	Parallel execution tracks	Faster than --robot-insights
bv --robot-insights	Full graph metrics (all 9)	Check status field; expensive
bv --robot-priority	Priority misalignment detection	Flags misprioritzed items
bv --robot-alerts	Stale issues, blocking cascades	Proactive health checks
bv --robot-suggest	Hygiene: duplicates, missing deps	Includes cycle break suggestions
bv --robot-graph	Dependency graph export	JSON, DOT, or Mermaid format
bv --recipe <name> --robot-<cmd>	Pre-filter before any robot command	Recipes: actionable, high-impact, bottlenecks
bv --robot-triage --label <name>	Scope to label subgraph	Reduces noise for focused analysis

CRITICAL: Never run bare bv from an agent session. It launches an interactive TUI that blocks the session. Always use --robot-* flags.

The 9 Graph Metrics

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

Metrics compute in two phases: Phase 1 (degree, topo sort, density) is instant; Phase 2 (PageRank, betweenness, HITS, eigenvector, cycles) has a 500ms timeout. Always check the status field in output.

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 output includes these standard fields:

Field	Purpose
data_hash	Fingerprint of beads.jsonl for verifying consistency
status	Per-metric state: computed, approx, timeout, or skipped
as_of / as_of_commit	Present when using --as-of for time travel queries

Key output sections by command:

• --robot-triage: quick_ref, recommendations, quick_wins, blockers_to_clear, project_health, commands
• --robot-insights: bottlenecks, keystones, influencers, hubs, authorities, cycles, clusterDensity
• --robot-plan: plan.tracks (parallel work streams), plan.summary.highest_impact

Common Mistakes

Mistake	Correct Pattern
Running bare bv from an agent session	Always use --robot-* flags; bare bv launches an interactive TUI that blocks the agent
Ignoring the status field in robot output	Always check per-metric status; large graphs may have approx or skipped metrics due to 500ms timeout
Using --robot-insights when only the next task is needed	Use --robot-next for a single top pick or --robot-triage for quick recommendations; insights is expensive
Not checking for cycles before starting implementation	Run bv --robot-insights and check .cycles first; circular dependencies are structural errors that must be resolved
Parsing stderr as JSON data	Only stdout contains JSON; diagnostics and warnings go to stderr
Stale metrics after bead changes	Check data_hash field; results are cached by beads.jsonl fingerprint
Wrong recommendations for current work	Use --recipe actionable to filter to only unblocked, ready-to-work items

Delegation

• Analyze project dependency health and bottlenecks: Use Task agent to run BV robot commands and summarize graph metrics
• Plan sprint work from triage output: Use Plan agent to interpret triage recommendations and build execution tracks
• Search for related beads context: Use Explore agent to investigate bead descriptions and find implementation patterns

References

• Robot commands, output structures, and jq patterns
• Graph metrics, two-phase analysis, and metric recipes
• Agent workflows, TUI views, integrations, and time travel