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
Taskagent to run BV robot commands and summarize graph metrics - Plan sprint work from triage output: Use
Planagent to interpret triage recommendations and build execution tracks - Search for related beads context: Use
Exploreagent to investigate bead descriptions and find implementation patterns