bv
Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents.
How do I install this agent skill?
npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill bvIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive instructions for using the 'bv' (Beads Viewer) CLI tool to perform graph-based analysis on project tasks. It introduces a structured 'Robot Mode' for AI agents. A potential security risk is identified in the suggested agent workflow, which involves executing shell commands using data parsed directly from project files without explicit sanitization, creating a surface for indirect prompt injection.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
BV - Beads Viewer
A graph-aware triage engine for Beads projects (.beads/beads.jsonl). Computes 9 graph metrics, generates execution plans, and provides deterministic recommendations. Human TUI for browsing; robot flags for AI agents.
Why BV vs Raw Beads
| 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 |
Use BV instead of parsing beads.jsonl directly. It computes graph metrics deterministically.
CRITICAL: Robot Mode for Agents
Never run bare bv. It launches an interactive TUI that blocks your session.
Always use --robot-* flags:
bv --robot-triage # THE MEGA-COMMAND: start here
bv --robot-next # Minimal: just the single top pick
bv --robot-plan # Parallel execution tracks
bv --robot-insights # Full graph metrics
The 9 Graph Metrics
BV computes these metrics to surface hidden project dynamics:
| 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 |
Two-Phase Analysis
BV uses async computation with timeouts:
- Phase 1 (instant): degree, topo sort, density
- Phase 2 (500ms timeout): PageRank, betweenness, HITS, eigenvector, cycles
Always check status field in output. For large graphs (>500 nodes), some metrics may be approx or skipped.
Robot Commands Reference
Triage & Planning
bv --robot-triage # Full triage: recommendations, quick_wins, blockers_to_clear
bv --robot-next # Single top pick with claim command
bv --robot-plan # Parallel execution tracks with unblocks lists
bv --robot-priority # Priority misalignment detection
Graph Analysis
bv --robot-insights # Full metrics: PageRank, betweenness, HITS, cycles, etc.
bv --robot-label-health # Per-label health: healthy|warning|critical
bv --robot-label-flow # Cross-label dependency flow matrix
bv --robot-label-attention # Attention-ranked labels
History & Changes
bv --robot-history # Bead-to-commit correlations
bv --robot-diff --diff-since <ref> # Changes since ref
Other Commands
bv --robot-burndown <sprint> # Sprint burndown, scope changes
bv --robot-forecast <id|all> # ETA predictions
bv --robot-alerts # Stale issues, blocking cascades
bv --robot-suggest # Hygiene: duplicates, missing deps, cycle breaks
bv --robot-graph # Dependency graph export (JSON, DOT, Mermaid)
bv --export-graph <file.html> # Self-contained interactive HTML visualization
Scoping & Filtering
bv --robot-plan --label backend # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30 # Historical point-in-time
bv --recipe actionable --robot-plan # Pre-filter: ready to work
bv --recipe high-impact --robot-triage # Pre-filter: top PageRank
bv --robot-triage --robot-triage-by-track # Group by parallel work streams
bv --robot-triage --robot-triage-by-label # Group by domain
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 includes:
data_hash- Fingerprint of beads.jsonl (verify consistency)status- Per-metric state:computed|approx|timeout|skippedas_of/as_of_commit- Present when using--as-of
--robot-triage Output
{
"quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] },
"recommendations": [
{ "id": "br-123", "score": 0.85, "reason": "Unblocks 5 tasks", "unblock_info": {...} }
],
"quick_wins": [...],
"blockers_to_clear": [...],
"project_health": { "distributions": {...}, "graph_metrics": {...} },
"commands": { "claim": "br claim br-123", "view": "bv --bead br-123" }
}
--robot-insights Output
{
"bottlenecks": [{ "id": "br-123", "value": 0.45 }],
"keystones": [{ "id": "br-456", "value": 12.0 }],
"influencers": [...],
"hubs": [...],
"authorities": [...],
"cycles": [["br-A", "br-B", "br-A"]],
"clusterDensity": 0.045,
"status": { "pagerank": "computed", "betweenness": "computed", ... }
}
jq Quick Reference
bv --robot-triage | jq '.quick_ref' # At-a-glance summary
bv --robot-triage | jq '.recommendations[0]' # Top recommendation
bv --robot-plan | jq '.plan.summary.highest_impact' # Best unblock target
bv --robot-insights | jq '.status' # Check metric readiness
bv --robot-insights | jq '.cycles' # Circular deps (must fix!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'
Agent Workflow Pattern
# 1. Start with triage
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo "$TRIAGE" | jq -r '.recommendations[0].id')
# 2. Check for cycles first (structural errors)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; then
echo "Fix cycles first: $CYCLES"
fi
# 3. Claim the task
br claim "$NEXT_TASK"
# 4. Work on it...
# 5. Close when done
br close "$NEXT_TASK"
TUI Views (for Humans)
When running bv interactively (not for agents):
| Key | View |
|---|---|
l | List view (default) |
b | Kanban board |
g | Graph view (dependency DAG) |
E | Tree view (parent-child hierarchy) |
i | Insights dashboard (6-panel metrics) |
h | History view (bead-to-commit correlation) |
a | Actionable plan (parallel tracks) |
f | Flow matrix (cross-label dependencies) |
] | Attention view (label priority ranking) |
Integration with br CLI
BV reads from .beads/beads.jsonl created by the br CLI:
br init # Initialize beads in project
br create "Task title" # Create a bead
br list # List beads
br ready # Show actionable beads
br claim br-123 # Claim a bead
br close br-123 # Close a bead
Integration with Agent Mail
Use bead IDs as thread IDs for coordination:
file_reservation_paths(..., reason="br-123")
send_message(..., thread_id="br-123", subject="[br-123] Starting...")
Graph Export Formats
bv --robot-graph # JSON (default)
bv --robot-graph --graph-format=dot # Graphviz DOT
bv --robot-graph --graph-format=mermaid # Mermaid diagram
bv --robot-graph --graph-root=br-123 --graph-depth=3 # Subgraph
bv --export-graph report.html # Interactive HTML
Time Travel
Compare against historical states:
bv --as-of HEAD~10 # 10 commits ago
bv --as-of v1.0.0 # At tag
bv --as-of "2024-01-15" # At date
bv --robot-diff --diff-since HEAD~30 # Changes in last 30 commits
Common Pitfalls
| Issue | Fix |
|---|---|
| TUI blocks agent | Use --robot-* flags only |
| Stale metrics | Check status field, results cached by data_hash |
| Missing cycles | Run --robot-insights, check .cycles |
| Wrong recommendations | Use --recipe actionable to filter to ready work |
Performance Notes
- Phase 1 metrics (degree, topo, density): instant
- Phase 2 metrics (PageRank, betweenness, etc.): 500ms timeout
- Results cached by
data_hash - Prefer
--robot-planover--robot-insightswhen speed matters
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations/bv">View bv on skillZs</a>