| name | beads-viewer |
| description | Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use when triaging beads tasks, analyzing dependency graphs, finding bottlenecks, detecting circular dependencies, planning parallel execution tracks, or generating sprint burndown data. |
| license | MIT |
| metadata | {"author":"oakoss","version":"1.0"} |
Beads Viewer
Overview
Beads Viewer (BV) is a graph-aware triage engine for Beads projects. 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: Simple bead CRUD operations (use bd CLI instead), projects without .beads/.
IMPORTANT — JSONL prerequisite: BV reads from .beads/issues.jsonl, NOT from the SQLite database directly. If the JSONL file is empty or stale, BV will return zero issues with data_hash: "empty". Before running BV, ensure the JSONL is populated:
bd export -o .beads/issues.jsonl
Re-export after any bd CRUD operations to keep BV data current.
| 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 | Default JSON; use -graph-format mermaid|dot |
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:
triage.quick_ref, triage.recommendations, triage.quick_wins, triage.blockers_to_clear, triage.project_health, triage.commands
- --robot-insights:
Bottlenecks, Keystones, Influencers, Hubs, Authorities, Cycles (note: PascalCase keys)
- --robot-plan:
plan.tracks (parallel work streams), plan.summary.highest_impact
- --robot-priority:
summary, recommendations (priority misalignment findings)
- --robot-alerts:
alerts, summary (stale issues, blocking cascades)
- --robot-suggest:
suggestions (hygiene recommendations)
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 |
BV returns 0 issues / data_hash: "empty" | JSONL is empty or stale. Run bd export -o .beads/issues.jsonl before BV commands |
Using --format mermaid for graph export | The correct flag is -graph-format mermaid (separate from --format which controls JSON/toon output) |
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
