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
1---2name: beads-viewer3description: 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.4license: MIT5---6
7# Beads Viewer
8
9## Overview
10
11Beads 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.
12
13**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.
14
15**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`.
16
17| Capability | Raw beads.jsonl | BV Robot Mode |
18| ------------ | ------------------------------ | ------------------------------------------------- |
19| Query | "List all issues" | "List the top 5 bottlenecks blocking the release" |
20| Context Cost | High (linear with issue count) | Low (fixed summary struct) |
21| Graph Logic | Agent must compute | Pre-computed (PageRank, betweenness, cycles) |
22| Safety | Agent might miss cycles | Cycles explicitly flagged |
23
24## Quick Reference
25
26| Command | Purpose | Key Points |
27| ---------------------------------- | ----------------------------------- | --------------------------------------------- |
28| `bv --robot-triage` | Full triage with recommendations | Start here; includes quick_wins and blockers |
29| `bv --robot-next` | Single top pick with claim command | Minimal context cost |
30| `bv --robot-plan` | Parallel execution tracks | Faster than `--robot-insights` |
31| `bv --robot-insights` | Full graph metrics (all 9) | Check `status` field; expensive |
32| `bv --robot-priority` | Priority misalignment detection | Flags misprioritzed items |
33| `bv --robot-alerts` | Stale issues, blocking cascades | Proactive health checks |
34| `bv --robot-suggest` | Hygiene: duplicates, missing deps | Includes cycle break suggestions |
35| `bv --robot-graph` | Dependency graph export | JSON, DOT, or Mermaid format |
36| `bv --recipe <name> --robot-<cmd>` | Pre-filter before any robot command | Recipes: actionable, high-impact, bottlenecks |
37| `bv --robot-triage --label <name>` | Scope to label subgraph | Reduces noise for focused analysis |
38
39**CRITICAL:** Never run bare `bv` from an agent session. It launches an interactive TUI that blocks the session. Always use `--robot-*` flags.
40
41## The 9 Graph Metrics
42
43| Metric | What It Measures | Key Insight |
44| ----------------- | ------------------------------- | ----------------------------- |
45| **PageRank** | Recursive dependency importance | Foundational blockers |
46| **Betweenness** | Shortest-path traffic | Bottlenecks and bridges |
47| **HITS** | Hub/Authority duality | Epics vs utilities |
48| **Critical Path** | Longest dependency chain | Keystones with zero slack |
49| **Eigenvector** | Influence via neighbors | Strategic dependencies |
50| **Degree** | Direct connection counts | Immediate blockers/blocked |
51| **Density** | Edge-to-node ratio | Project coupling health |
52| **Cycles** | Circular dependencies | Structural errors (must fix!) |
53| **Topo Sort** | Valid execution order | Work queue foundation |
54
55Metrics 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.
56
57## Built-in Recipes
58
59| Recipe | Purpose |
60| ------------- | ---------------------------------- |
61| `default` | All open issues sorted by priority |
62| `actionable` | Ready to work (no blockers) |
63| `high-impact` | Top PageRank scores |
64| `blocked` | Waiting on dependencies |
65| `stale` | Open but untouched for 30+ days |
66| `triage` | Sorted by computed triage score |
67| `quick-wins` | Easy P2/P3 items with no blockers |
68| `bottlenecks` | High betweenness nodes |
69
70## Robot Output Structure
71
72All robot JSON output includes these standard fields:
73
74| Field | Purpose |
75| ------------------------ | --------------------------------------------------------------- |
76| `data_hash` | Fingerprint of beads.jsonl for verifying consistency |
77| `status` | Per-metric state: `computed`, `approx`, `timeout`, or `skipped` |
78| `as_of` / `as_of_commit` | Present when using `--as-of` for time travel queries |
79
80Key output sections by command:
81
82- **--robot-triage**: `quick_ref`, `recommendations`, `quick_wins`, `blockers_to_clear`, `project_health`, `commands`
83- **--robot-insights**: `bottlenecks`, `keystones`, `influencers`, `hubs`, `authorities`, `cycles`, `clusterDensity`
84- **--robot-plan**: `plan.tracks` (parallel work streams), `plan.summary.highest_impact`
85
86## Common Mistakes
87
88| Mistake | Correct Pattern |
89| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
90| Running bare `bv` from an agent session | Always use `--robot-*` flags; bare `bv` launches an interactive TUI that blocks the agent |
91| Ignoring the `status` field in robot output | Always check per-metric status; large graphs may have `approx` or `skipped` metrics due to 500ms timeout |
92| 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 |
93| Not checking for cycles before starting implementation | Run `bv --robot-insights` and check `.cycles` first; circular dependencies are structural errors that must be resolved |
94| Parsing stderr as JSON data | Only stdout contains JSON; diagnostics and warnings go to stderr |
95| Stale metrics after bead changes | Check `data_hash` field; results are cached by beads.jsonl fingerprint |
96| Wrong recommendations for current work | Use `--recipe actionable` to filter to only unblocked, ready-to-work items |
97
98## Delegation
99
100- **Analyze project dependency health and bottlenecks**: Use `Task` agent to run BV robot commands and summarize graph metrics
101- **Plan sprint work from triage output**: Use `Plan` agent to interpret triage recommendations and build execution tracks
102- **Search for related beads context**: Use `Explore` agent to investigate bead descriptions and find implementation patterns
103
104## References
105
106- [Robot commands, output structures, and jq patterns](references/robot-commands.md)
107- [Graph metrics, two-phase analysis, and metric recipes](references/graph-metrics.md)
108- [Agent workflows, TUI views, integrations, and time travel](references/workflows.md)
oakoss