bv

Q: How do I install bv?

Run npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill bv in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/bv/ (personal) or .claude/skills/bv/ (project).

by dicklesworthstoneAI & Agents

Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot- flags for AI agents.

Installs: 74
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill bv

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads bv automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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|skipped
as_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-plan over --robot-insights when speed matters

FAQ

What does the bv skill do?

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 bv?

Run npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill bv in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/bv/ (personal) or .claude/skills/bv/ (project).

Which AI agents can use bv?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is bv safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains bv?

It is published by dicklesworthstone in dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations. It has 74 recorded installs.