Beads Viewer

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.

Quick Reference

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

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

Robot Output Structure

All robot JSON output includes these standard fields:

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

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

Graph Metrics

The 9 Graph Metrics

BV computes these metrics to surface hidden project dynamics:

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 the status field in output. For large graphs (>500 nodes), some metrics may be approx or skipped.

Status Field Values

Performance Characteristics

• Phase 1 metrics (degree, topo, density): instant for any graph size
• Phase 2 metrics (PageRank, betweenness, etc.): 500ms timeout budget
• Results cached by data_hash fingerprint of beads.jsonl
• Prefer --robot-plan over --robot-insights when speed matters

Interpreting Metrics

Finding Bottlenecks

High betweenness centrality indicates beads that sit on many shortest paths between other beads. Completing these first maximizes unblocking impact.

bv --robot-insights | jq '.bottlenecks[:5]'

Finding Foundational Work

High PageRank scores indicate beads with deep recursive dependency chains. These are the foundational pieces many other tasks ultimately depend on.

bv --recipe high-impact --robot-triage

Detecting Structural Problems

Cycles are circular dependencies that make execution order impossible to determine. These must be resolved before planning work.

bv --robot-insights | jq '.cycles'

Understanding Project Coupling

Cluster density measures the edge-to-node ratio. High density suggests tight coupling; low density suggests independent work streams.

bv --robot-insights | jq '.clusterDensity'

Hub vs Authority Analysis

HITS distinguishes between hubs (epics that depend on many tasks) and authorities (utility tasks that many items depend on). Use this to identify strategic epics and critical shared work.

bv --robot-insights | jq '{ hubs: .hubs[:3], authorities: .authorities[:3] }'

Label Health Assessment

Per-label health scoring identifies which project areas need attention:

bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'
bv --robot-label-attention | jq '.results[:5]'

Robot Commands

Triage and 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 and 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 and 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

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=bd-123 --graph-depth=3  # Subgraph
bv --export-graph report.html                 # Interactive HTML

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": "bd-123",
      "score": 0.85,
      "reason": "Unblocks 5 tasks",
      "unblock_info": {}
    }
  ],
  "quick_wins": ["..."],
  "blockers_to_clear": ["..."],
  "project_health": { "distributions": {}, "graph_metrics": {} },
  "commands": { "claim": "bd claim bd-123", "view": "bv --bead bd-123" }
}

--robot-insights Output

{
  "bottlenecks": [{ "id": "bd-123", "value": 0.45 }],
  "keystones": [{ "id": "bd-456", "value": 12.0 }],
  "influencers": ["..."],
  "hubs": ["..."],
  "authorities": ["..."],
  "cycles": [["bd-A", "bd-B", "bd-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")'

Workflows

Agent Workflow Pattern

The standard agent workflow for using BV to find and claim work:

# 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
bd claim "$NEXT_TASK"

# 4. Work on it...

# 5. Close when done
bd close "$NEXT_TASK"

Focused Workflow with Recipes

# Only show actionable (unblocked) work
bv --recipe actionable --robot-triage | jq '.recommendations[:3]'

# Find quick wins for momentum
bv --recipe quick-wins --robot-triage | jq '.quick_wins'

# Find and resolve bottlenecks first
bv --recipe bottlenecks --robot-triage | jq '.blockers_to_clear'

Parallel Execution Planning

# Get parallel tracks for team coordination
bv --robot-plan | jq '.plan.tracks'

# Find the single highest-impact unblock
bv --robot-plan | jq '.plan.summary.highest_impact'

Integration with bd CLI

BV reads from .beads/beads.jsonl created by the bd CLI:

bd init                    # Initialize beads in project
bd create "Task title"     # Create a bead
bd list                    # List beads
bd ready                   # Show actionable beads
bd claim bd-123            # Claim a bead
bd close bd-123            # Close a bead

BV provides the analytical layer on top of the data bd manages. Use bd for CRUD operations and bv for graph-aware analysis and triage.

Integration with Agent Mail

Use bead IDs as thread IDs for multi-agent coordination:

file_reservation_paths(..., reason="bd-123")
send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")

This creates a traceable link between task tracking and agent communication.

Time Travel

Compare current project state against historical snapshots:

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

Time travel applies to all robot commands. Combine with --robot-insights to track metric trends over time.

TUI Views (for Humans)

When running bv interactively (not for agents):

Agents must never launch the TUI. These views are documented here for completeness when human users reference them.