BV - Beads Viewer

BV - Beads Viewer

A high-performance TUI and graph-aware triage engine for the Beads issue tracker. Treats your project as a Directed Acyclic Graph (DAG), computing 9 graph-theoretic metrics to surface hidden dependencies, bottlenecks, and optimal work ordering.

CRITICAL: Robot Mode Required for AI Agents

NEVER run bare bv - it launches an interactive TUI that blocks your session!

# WRONG - blocks terminal with TUI
bv

# CORRECT - JSON output for agents
bv --robot-triage
bv --robot-plan
bv --robot-insights

Always use --robot-* flags for machine-readable output.

---

Quick Reference for AI Agents

The Mega-Command: Start Here

# THE SINGLE ENTRY POINT - returns everything you need
bv --robot-triage

Returns:

• quick_ref: at-a-glance counts + top 3 picks
• recommendations: ranked actionable items with scores, reasons, unblock info
• quick_wins: low-effort high-impact items
• blockers_to_clear: items that unblock the most downstream work
• project_health: status/​type/​priority distributions, graph metrics
• commands: copy-paste shell commands for next steps

Minimal Alternative

# Just the single top pick + claim command
bv --robot-next

---

Why Use BV

Graph Intelligence vs. List Thinking

Traditional trackers treat issues as a flat list sorted by priority. BV sees your project as a dependency graph and answers questions like:

Use Cases

# "What should I work on next?"
bv --robot-triage | jq '.recommendations[0]'

# "What's blocking the most progress?"
bv --robot-triage | jq '.blockers_to_clear'

# "Can multiple agents work in parallel?"
bv --robot-plan | jq '.tracks'

# "Are there circular dependencies?" (structural bugs!)
bv --robot-insights | jq '.Cycles'

# "What changed since last release?"
bv --robot-diff --diff-since v1.0.0

---

The 9 Graph Metrics

BV computes these metrics to surface hidden project dynamics:

Understanding the Metrics

PageRank (Foundational Blocks) High PageRank = bedrock of your project. Rarely user-facing features; usually schemas, core libraries, or architectural decisions. Breaking them breaks the graph.

Betweenness (Gatekeepers) High betweenness = choke point. Might be an API contract both mobile and server teams wait on. Delay here doesn't just block one thread—it prevents sub-teams from synchronizing.

HITS (Epics vs. Utilities)

• High Hub Score: Epics/​Product Features that aggregate many dependencies
• High Authority Score: Utilities that provide value to many consumers

Critical Path (Keystones) Any delay on keystone tasks translates 1:1 into project delivery delay. These have zero "slack."

Cycles (Structural Bugs) Circular dependencies are logical impossibilities. They indicate:

• Misclassified dependencies
• Missing intermediate tasks
• Scope confusion (should be merged)

---

Command Reference

Triage & Planning

# THE MEGA-COMMAND: comprehensive triage
bv --robot-triage

# Minimal: just the top pick
bv --robot-next

# Parallel execution tracks (for multi-agent work)
bv --robot-plan

# Priority misalignment detection
bv --robot-priority

Graph Analysis

# Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles
bv --robot-insights

# Label-based analysis
bv --robot-label-health           # Per-label health (healthy|warning|critical)
bv --robot-label-flow             # Cross-label dependencies, bottleneck labels
bv --robot-label-attention        # Attention-ranked labels
bv --robot-label-attention --attention-limit=5

History & Change Tracking

# Bead-to-commit correlations
bv --robot-history
bv --robot-history --bead-history BV-123   # Single bead focus
bv --robot-history --min-confidence 0.7     # High-confidence only

# Changes since a reference point
bv --robot-diff --diff-since HEAD~10
bv --robot-diff --diff-since v1.0.0
bv --robot-diff --diff-since "2024-01-01"

Sprint & Forecasting

# Sprint burndown
bv --robot-burndown "Sprint 42"

# ETA predictions with dependency-aware scheduling
bv --robot-forecast all
bv --robot-forecast BV-123

# Alerts: stale issues, blocking cascades, priority mismatches
bv --robot-alerts

# Hygiene suggestions: duplicates, missing deps, cycle breaks
bv --robot-suggest

Graph Export

# JSON (default)
bv --robot-graph

# Graphviz DOT (for rendering)
bv --robot-graph --graph-format=dot

# Mermaid (for docs)
bv --robot-graph --graph-format=mermaid

# Focused subgraph
bv --robot-graph --graph-root=BV-123 --graph-depth=3

# Interactive HTML visualization
bv --export-graph graph.html
bv --export-graph sprint.html --graph-title "Sprint 42"

Scoping & Filtering

# Scope to label's subgraph
bv --robot-plan --label backend

# Historical point-in-time analysis
bv --robot-insights --as-of HEAD~30
bv --robot-insights --as-of v1.0.0
bv --robot-insights --as-of "2024-01-15"

# Pre-filter with recipes
bv --recipe actionable --robot-plan    # Ready to work (no blockers)
bv --recipe high-impact --robot-triage # Top PageRank scores
bv --recipe bottlenecks --robot-plan   # High betweenness nodes

# Group triage output
bv --robot-triage --robot-triage-by-track  # By parallel work streams
bv --robot-triage --robot-triage-by-label  # By domain

Export & Reporting

# Markdown report with Mermaid diagrams
bv --export-md report.md

# Static site for stakeholder sharing
bv --pages                              # Interactive wizard
bv --export-pages ./​dashboard           # Local export
bv --export-pages ./​bv-pages --pages-title "Sprint 42 Status"
bv --preview-pages ./​dir                # Preview locally

---

Understanding Robot Output

All Robot JSON Includes

Two-Phase Analysis

BV uses async computation with intelligent timeouts:

For large graphs (>500 nodes): Some Phase 2 metrics may be approx or skipped. Always check the status field.

Caching

Results are cached by data_hash. Repeat calls with unchanged beads.jsonl return instantly.

---

jq Quick Reference

# At-a-glance summary
bv --robot-triage | jq '.quick_ref'

# Top recommendation
bv --robot-triage | jq '.recommendations[0]'

# Best unblock target
bv --robot-plan | jq '.plan.summary.highest_impact'

# Check metric readiness
bv --robot-insights | jq '.status'

# Find circular dependencies (MUST FIX!)
bv --robot-insights | jq '.Cycles'

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

# All bottleneck issues
bv --robot-insights | jq '.bottlenecks'

---

Response Shapes

Triage Response

{
  "quick_ref": {
    "total_open": 42,
    "actionable": 15,
    "blocked": 12,
    "top_picks": ["BV-123", "BV-456", "BV-789"]
  },
  "recommendations": [
    {
      "id": "BV-123",
      "title": "Refactor auth module",
      "score": 0.85,
      "reasons": ["High PageRank", "Unblocks 5 tasks"],
      "unblocks": ["BV-200", "BV-201", "BV-202", "BV-203", "BV-204"]
    }
  ],
  "quick_wins": [...],
  "blockers_to_clear": [...],
  "project_health": {
    "status_distribution": {...},
    "priority_distribution": {...},
    "graph_density": 0.045,
    "cycle_count": 0
  },
  "commands": {
    "claim_top": "bd update BV-123 --status in_progress"
  },
  "data_hash": "abc123...",
  "status": {...}
}

Plan Response

{
  "plan": {
    "tracks": [
      {
        "track_id": "track-A",
        "reason": "Auth system dependency chain",
        "items": [
          { "id": "AUTH-001", "priority": 1, "unblocks": ["AUTH-002", "AUTH-003"] }
        ]
      }
    ],
    "summary": {
      "total_actionable": 8,
      "total_blocked": 12,
      "highest_impact": "AUTH-001",
      "impact_reason": "Unblocks 3 tasks"
    }
  },
  "data_hash": "...",
  "status": {...}
}

Insights Response

{
  "bottlenecks": [{ "id": "CORE-123", "value": 0.45 }],
  "keystones": [{ "id": "API-001", "value": 12.0 }],
  "influencers": [{ "id": "AUTH-007", "value": 0.82 }],
  "hubs": [{ "id": "EPIC-100", "value": 0.67 }],
  "authorities": [{ "id": "UTIL-050", "value": 0.91 }],
  "cycles": [["TASK-A", "TASK-B", "TASK-A"]],
  "clusterDensity": 0.045,
  "stats": {
    "pageRank": {...},
    "betweenness": {...},
    "eigenvector": {...},
    "hubs": {...},
    "authorities": {...},
    "inDegree": {...},
    "outDegree": {...},
    "criticalPathScore": {...},
    "topologicalOrder": [...]
  },
  "status": {
    "pageRank": { "state": "computed", "elapsed_ms": 12 },
    "betweenness": { "state": "computed", "elapsed_ms": 45 },
    "cycles": { "state": "computed", "elapsed_ms": 8 }
  }
}

---

Recipe System

BV ships with 11 pre-configured recipes for common workflows:

bv --recipe actionable --robot-plan
bv --recipe high-impact --robot-triage
bv --recipe bottlenecks --robot-insights

---

Hybrid Semantic Search

BV supports text + graph metric hybrid search:

# Default text-only search
bv --search "login oauth"

# Hybrid mode with preset
bv --search "login oauth" --search-mode hybrid --search-preset impact-first

# Custom weights
bv --search "login oauth" --search-mode hybrid \
  --search-weights '{"text":0.4,"pagerank":0.2,"status":0.15,"impact":0.1,"priority":0.1,"recency":0.05}'

# Robot JSON output
bv --search "login oauth" --search-mode hybrid --robot-search

Presets: default, bug-hunting, sprint-planning, impact-first, text-only

Environment defaults:

• BV_SEARCH_MODE (text|hybrid)
• BV_SEARCH_PRESET
• BV_SEARCH_WEIGHTS (JSON string)

---

Time-Travel: Snapshot Diffing

Compare project state across git history:

# View state at any git reference
bv --as-of HEAD~10
bv --as-of v1.0.0
bv --as-of "2024-01-15"
bv --as-of abc1234  # commit SHA

# Diff changes
bv --robot-diff --diff-since HEAD~10
bv --robot-diff --diff-since v1.0.0

What gets tracked:

• Issues: New, Closed, Reopened, Removed, Modified
• Fields: Title, Status, Priority, Tags, Dependencies
• Graph: New Cycles, Resolved Cycles
• Metrics: Δ PageRank, Δ Betweenness, Δ Density

---

History View: Git Correlation

BV correlates beads with commits using multiple strategies:

# Full history report
bv --robot-history

# Single bead focus
bv --robot-history --bead-history BV-123

# Filter by confidence
bv --robot-history --min-confidence 0.7

# Time range
bv --robot-history --history-since "30 days ago"

---

Interactive HTML Graph

Generate self-contained HTML visualizations:

bv --export-graph graph.html
bv --export-graph --graph-title "Q4 Sprint"
bv --export-graph --graph-include-closed

Features:

• Force-directed layout (pan, zoom, filter)
• Node size by PageRank/​betweenness/​critical-path
• Color by status (Open=green, Blocked=red, etc.)
• Full-text search
• Path finder (click two nodes to find shortest path)
• Docked/​floating detail panel
• Light/​dark mode
• Works offline, no server required

Keyboard shortcuts: ? help, F fit all, R reset, L toggle light/​dark, P path finder

---

TUI Features (for Humans)

Launch with bare bv:

Views

Navigation

Filtering

Actions

---

Composite Impact Scoring

BV computes multi-factor impact scores:

Impact = 0.30×PageRank + 0.30×Betweenness + 0.20×BlockerRatio + 0.10×Staleness + 0.10×PriorityBoost

When computed impact diverges from human-assigned priority, BV flags misalignment:

⚠️ CORE-123 has Impact Score 0.85 but Priority P3. Reason: High PageRank (foundational dependency) + High Betweenness (bottleneck) Recommendation: Consider escalating to P1.

---

Baseline & Drift Detection

# Check drift from baseline
bv --check-drift
# Exit codes: 0=OK, 1=critical, 2=warning

# Get baseline info
bv --baseline-info

Use --check-drift in CI/​CD to catch quality regressions.

---

Automation Hooks

Configure pre/​post-export hooks in .bv/​hooks.yaml:

pre_export:
  - command: "validate-issues.sh"
    on_error: fail
post_export:
  - command: "notify-slack.sh"
    on_error: continue
    env:
      CHANNEL: "#dev"

Hook environment includes: BV_EXPORT_PATH, BV_EXPORT_FORMAT, BV_ISSUE_COUNT, BV_TIMESTAMP

---

Performance Characteristics

Use bv --profile-startup for diagnostics.

---

Integration with bd (Beads CLI)

BV reads from .beads/​beads.jsonl created by bd:

# Initialize beads
bd init

# Create issues
bd create "Implement login" -t feature -p 1

# Update status
bd update BV-123 --status in_progress

# Close
bd close BV-123 --reason "Completed"

Important: .beads/ is authoritative state. Always commit it with code changes.

---

Ready-to-Paste AGENTS.md Blurb

## bv - Beads Viewer (Graph-Aware Triage Engine)

bv is a graph-aware triage engine for Beads projects (.beads/​beads.jsonl). Instead of parsing JSONL or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core).

**⚠️ CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**

### The Workflow: Start With Triage
bv --robot-triage        # THE MEGA-COMMAND: start here
bv --robot-next          # Minimal: just the single top pick

### Key Commands
| Command | Returns |
|---------|---------|
| `--robot-triage` | Ranked recommendations, quick wins, blockers to clear |
| `--robot-plan` | Parallel execution tracks with unblocks lists |
| `--robot-insights` | Full metrics: PageRank, betweenness, cycles |
| `--robot-label-health` | Per-label health (healthy\|warning\|critical) |

### jq Quick Reference
bv --robot-triage | jq '.recommendations[0]'   # Top pick
bv --robot-plan | jq '.plan.summary'           # Best unblock target
bv --robot-insights | jq '.Cycles'             # Circular deps (MUST FIX!)

**Performance:** Phase 1 instant, Phase 2 async (500ms timeout). Results cached by data_hash.

---

Installation

curl -fsSL "https://raw.githubusercontent.com/​Dicklesworthstone/​beads_viewer/​main/​install.sh?$(date +%s)" | bash