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