name	bv
description	Beads Viewer - graph-aware triage engine for Beads issue tracker with 9 graph metrics (PageRank, betweenness, HITS, etc.), dependency-aware planning, and purpose-built robot protocol for AI agents.

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:

Traditional Question	BV's Graph-Aware Answer
"What's highest priority?"	"What unblocks the most work?"
"What should I work on?"	"What's on the critical path with zero slack?"
"Is this issue important?"	"What's its PageRank? Betweenness? Does it bridge clusters?"
"Are we making progress?"	"Did we resolve cycles? Is density improving?"

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:

#	Metric	What It Measures	Actionable Insight
1	PageRank	Recursive dependency importance	Foundational blockers
2	Betweenness	Shortest-path traffic	Bottlenecks & bridges
3	HITS Hubs	Dependency aggregators	Epics/milestones
4	HITS Authorities	Depended-on utilities	Core infrastructure
5	Critical Path	Longest dependency chain	Zero-slack keystones
6	Eigenvector	Influence via neighbors	Strategic dependencies
7	Degree	Direct connection counts	Immediate blockers/blocked
8	Density	Edge-to-node ratio	Project coupling health
9	Cycles	Circular dependencies	Structural bugs (must fix!)

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

Field	Purpose
`data_hash`	Fingerprint of beads.jsonl (verify consistency across calls)
`status`	Per-metric state: `computed\|approx\|timeout\|skipped` + elapsed_ms
`as_of` / `as_of_commit`	Present when using `--as-of`; contains ref and resolved SHA

Two-Phase Analysis

BV uses async computation with intelligent timeouts:

Phase	Metrics	Latency	Notes
Phase 1	Degree, topo sort, density	Instant	Always available
Phase 2	PageRank, betweenness, HITS, eigenvector, cycles	500ms timeout	Check `status` flags

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:

Recipe	Purpose
`default`	All open issues sorted by priority
`actionable`	Ready to work (no blockers)
`recent`	Updated in last 7 days
`blocked`	Waiting on dependencies
`high-impact`	Top PageRank scores
`stale`	Open but untouched for 30+ days
`triage`	Sorted by computed triage score
`closed`	Recently closed issues
`release-cut`	Closed in last 14 days (for changelogs)
`quick-wins`	Easy P2/P3 items with no blockers
`bottlenecks`	High betweenness nodes

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:

Strategy	Weight	How It Works
Explicit Mentions	0.5	Commit message contains bead ID
Temporal Proximity	0.25	Commit during bead's active lifecycle
Co-Commit Analysis	0.15	Files frequently modified together
Path Matching	0.10	File paths match bead's label scope

# 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

Key	View	Description
(default)	List	Split-view with list + details
`b`	Kanban Board	Columnar workflow view
`g`	Graph	ASCII/Unicode dependency visualization
`i`	Insights	6-panel metrics dashboard
`h`	History	Git correlation timeline

Navigation

Key	Action
`j/k`	Navigate up/down
`h/l`	Navigate left/right (in board/graph)
`Enter`	Open in $EDITOR
`Space`	Full-screen detail
`/`	Search
`Tab`	Cycle panels
`?`	Help
`q`	Quit

Filtering

Key	Filter
`o`	Open only
`c`	Closed only
`r`	Ready (unblocked)
`F3`	By label
`F5/F6`	By time

Actions

Key	Action
`E`	Export to Markdown
`C`	Copy issue as Markdown
`t`	Time-travel (compare to git ref)
`p`	Toggle priority hints overlay
`s`	Cycle sort mode

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

Operation	Latency
Phase 1 metrics	Instant
Phase 2 metrics (<500 nodes)	<500ms
Phase 2 metrics (large graphs)	May timeout/approx
Cached repeat calls	Instant (by data_hash)

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

Install Skill

SKILL.md