Beads Viewer (bv)

The elegant, keyboard-driven terminal interface for the Beads issue tracker.

Main split view: fast list + rich details	Kanban board (`b`) for flow at a glance
Insights panel: PageRank, critical path, cycles	Graph view (`g`): navigate the dependency DAG

Installation

Recommended: Homebrew (macOS/Linux)

brew install dicklesworthstone/tap/bv

This method provides: - Automatic updates via brew upgrade - Dependency management - Easy uninstall via brew uninstall

Windows: Scoop

scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket
scoop install dicklesworthstone/bv

Alternative: Direct Download

Download the latest release archive for your platform: - Linux x86_64 - Linux ARM64 - macOS Intel - macOS ARM - Windows

These links target the moving latest release aliases.

Alternative: Install Script

Linux/macOS:

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

Windows (PowerShell):

irm "https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/main/install.ps1" | iex

Note: Windows requires Go 1.21+ (download). For best display, use Windows Terminal with a Nerd Font.

Generating the JSONL File (br and bd)

bv reads from .beads/beads.jsonl. Both the Rust-based br and the original Go-based bd can generate this file.

Rust (br) users — br writes .beads/beads.jsonl by default; no extra steps needed.

Go (bd) users — run:

bd export --no-memories -o .beads/beads.jsonl

Once the file exists, bv works identically regardless of which tool produced it.

🤖 Agent Quickstart (Robot Mode)

⚠️ Never run bare bv in an agent context — it launches the interactive TUI. Always use --robot-*.

# 1) Start with triage (single-call mega-command)
bv --robot-triage

# 2) Minimal mode: just the top pick + claim command
bv --robot-next

# 3) Token-optimized output (TOON)
bv --robot-triage --format toon
export BV_OUTPUT_FORMAT=toon

# 4) Full robot help
bv --robot-help

Output conventions - stdout = JSON/TOON data only - stderr = diagnostics - exit 0 = success

💡 TL;DR

bv is a high-performance Terminal User Interface (TUI) for browsing and managing tasks in projects that use the Beads issue tracking system.

Why you'd care: * Speed: Browse thousands of issues instantly with zero network latency. * Focus: Stay in your terminal and use Vim-style keys (j/k) to navigate. * Intelligence: It visualizes your project as a dependency graph, automatically highlighting bottlenecks, cycles, and critical paths that traditional list-based trackers miss. * AI-Ready: It provides structured, pre-computed insights for AI coding agents, acting as a "brain" for your project's task management.

📖 The Core Experience

At its heart, bv is about viewing your work nicely.

⚡ Fast, Fluid Browsing

No web page loads, no heavy clients. bv starts instantly and lets you fly through your issue backlog using standard Vim keys (j/k). * Split-View Dashboard: On wider screens, see your list on the left and full details on the right. * Markdown Rendering: Issue descriptions, comments, and notes are beautifully rendered with syntax highlighting, headers, and lists. * Instant Filtering: Zero-latency filtering. Press o for Open, c for Closed, or r for Ready (unblocked) tasks. * Live Reload: Watches .beads/beads.jsonl and refreshes lists, details, and insights automatically when the file changes—no restart needed.

🔎 Rich Context

Don't just read the title. bv gives you the full picture: * Comments & History: Scroll through the full conversation history of any task. * Metadata: Instantly see Assignees, Labels, Priority badges, and creation dates. * Search: Powerful fuzzy search (/) finds issues by ID, title, or content instantly.

🎯 Focused Workflows

• Kanban Board: Press b to switch to a columnar view (Open, In Progress, Blocked, Closed) to visualize flow.
• Visual Graph: Press g to explore the dependency tree visually.
• Insights: Press i to see graph metrics and bottlenecks.
• History View: Press h to see the timeline of changes, correlating git commits with bead modifications. On wider terminals, enjoy a responsive three-pane layout showing commits, affected beads, and details.
• Ultra-Wide Mode: On large monitors, the list expands to show extra columns like sparklines and label tags.

🛠️ Quick Actions

• Export: Press E to export all issues to a timestamped Markdown file with Mermaid diagrams.
• Graph Export (CLI): bv --robot-graph outputs the dependency graph as JSON, DOT (Graphviz), or Mermaid format. Use --graph-format=dot for rendering with Graphviz, or --graph-root=ID --graph-depth=3 to extract focused subgraphs.
• Copy: Press C to copy the selected issue as formatted Markdown to your clipboard.
• Edit: Press O to open the .beads/beads.jsonl file in your preferred GUI editor.
• Time-Travel: Press t to compare against any git revision, or T for quick HEAD~5 comparison. Combined with History view (h), you can navigate to any commit and see exactly what changed.

🔌 Automation Hooks

Configure pre- and post-export hooks in .bv/hooks.yaml to run validations, notifications, or uploads. Defaults: pre-export hooks fail fast on errors (on_error: fail), post-export hooks log and continue (on_error: continue). Empty commands are ignored with a warning for safety. Hook env includes BV_EXPORT_PATH, BV_EXPORT_FORMAT, BV_ISSUE_COUNT, BV_TIMESTAMP, plus any custom env entries.

🤖 Ready-made Blurb to Drop Into Your AGENTS.md or CLAUDE.md Files

```

Using bv as an AI sidecar

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, critical path, cycles, HITS, eigenvector, k-core).

Scope boundary: bv handles what to work on (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use MCP Agent Mail.

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

The Workflow: Start With Triage

bv --robot-triage is your single entry point. It returns everything you need in one call: - 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

Count semantics (strict since #165): - quick_ref.open_count / project_health.counts.open — issues with status exactly open; always equals counts.by_status.open - quick_ref.blocked_count / counts.blocked — issues with status exactly blocked; always equals counts.by_status.blocked - quick_ref.in_progress_count — status exactly in_progress - counts.closed — closed-like issues (closed + tombstone) - quick_ref.not_closed_count / counts.not_closed — every non-closed issue (open+in_progress+blocked+deferred); this is the pre-#165 meaning of open_count - quick_ref.actionable_count / counts.actionable — non-closed issues with no open blocking dependencies (ready to work now) - quick_ref.not_actionable_count / counts.dependency_blocked — non-closed issues blocked by open dependencies regardless of status; this is the pre-#165 meaning of blocked_count - Partition invariant: not_closed == actionable + not_actionable (every non-closed issue is exactly one of the two)

Liveness (#166): the git-history prologue of --robot-triage is bounded (default 10s; tune via --robot-history-timeout-ms <ms> or BV_ROBOT_HISTORY_TIMEOUT_MS, 0 = unbounded). On timeout the in-flight git subprocess is killed and triage proceeds without history; meta.history_status reports ok, error, or timeout (omitted when history was not attempted).

bv --robot-triage # THE MEGA-COMMAND: start here bv --robot-next # Minimal: just the single top pick + claim command

Token-optimized output (TOON) for lower LLM context usage:

bv --robot-triage --format toon export BV_OUTPUT_FORMAT=toon bv --robot-next

Before claiming, verify the current bead state with br show <id> --json or br ready --json. recommendations can include graph-important blocked or assigned work; only quick_ref.top_picks and non-empty claim_command fields represent claimable work.

Other Commands

Planning: | Command | Returns | |---------|---------| | --robot-plan | Parallel execution tracks with unblocks lists | | --robot-priority | Priority misalignment detection with confidence |

Graph Analysis: | Command | Returns | |---------|---------| | --robot-insights | Full metrics: PageRank, betweenness, HITS (hubs/authorities), eigenvector, critical path, cycles, k-core, articulation points, slack | | --robot-label-health | Per-label health: health_level (healthy|warning|critical), velocity_score, staleness, blocked_count | | --robot-label-flow | Cross-label dependency: flow_matrix, dependencies, bottleneck_labels | | --robot-label-attention [--attention-limit=N] | Attention-ranked labels by: (pagerank × staleness × block_impact) / velocity |

History & Change Tracking: | Command | Returns | |---------|---------| | --robot-history | Bead-to-commit correlations: stats, histories (per-bead events/commits/milestones), commit_index | | --robot-diff --diff-since <ref> | Changes since ref: new/closed/modified issues, cycles introduced/resolved |

Other Commands: | Command | Returns | |---------|---------| | --robot-burndown <sprint> | Sprint burndown, scope changes, at-risk items | | --robot-forecast <id\|all> | ETA predictions with dependency-aware scheduling | | --robot-alerts | Stale issues, blocking cascades, priority mismatches | | --robot-suggest | Hygiene: duplicates, missing deps, label suggestions, cycle breaks | | --robot-graph [--graph-format=json\|dot\|mermaid] | Dependency graph export | | --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 (no blockers) bv --recipe high-impact --robot-triage # Pre-filter: top PageRank scores bv --robot-triage --robot-triage-by-track # Group by parallel work streams bv --robot-triage --robot-triage-by-label # Group by domain

Understanding Robot Output

All robot JSON includes: - data_hash — Fingerprint of source 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: - Phase 1 (instant): degree, topo sort, density — always available immediately - Phase 2 (async, 500ms timeout): PageRank, betweenness, HITS, eigenvector, cycles — check status flags

For large graphs (>500 nodes): Some metrics may be approximated or skipped. Always check status.

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 '.p