원클릭으로
bv
// Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents.
// Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents.
| name | bv |
| description | Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents. |
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.
| 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.
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
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 |
BV uses async computation with timeouts:
Always check status field in output. For large graphs (>500 nodes), some metrics may be approx or skipped.
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
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
bv --robot-history # Bead-to-commit correlations
bv --robot-diff --diff-since <ref> # Changes since ref
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
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
| 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 |
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{
"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" }
}
{
"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", ... }
}
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")'
# 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"
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) |
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
Use bead IDs as thread IDs for coordination:
file_reservation_paths(..., reason="br-123")
send_message(..., thread_id="br-123", subject="[br-123] Starting...")
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
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
| 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 |
data_hash--robot-plan over --robot-insights when speed mattersMCP Agent Mail - Mail-like coordination layer for multi-agent workflows. Identities, inbox/outbox, file reservations, contact policies, threaded messaging, pre-commit guard, Human Overseer, static exports, disaster recovery. Git+SQLite backed. Python/FastMCP.
Jeffrey Emanuel's multi-agent implementation workflow using NTM, Agent Mail, Beads, and BV. The execution phase that follows planning and bead creation. Includes exact prompts used.
Converting markdown plans into beads (tasks with dependencies) and polishing them until they're implementation-ready. The bridge between planning and agent swarm execution. Includes exact prompts used.
Remove telltale signs of AI-generated 'slop' writing from README files and documentation. Make your docs sound authentically human.
Named Tmux Manager - Multi-agent orchestration for Claude Code, Codex, and Gemini in tiled tmux panes. Visual dashboards, command palette, context rotation, robot mode API, work assignment, safety system. Go CLI.
Find opportunities to improve web application code using TanStack libraries (Query, Table, Form, Router, etc.). Avoid man-with-hammer syndrome by applying TanStack after vanilla implementation works.