# Beads Viewer Beads Viewer (bv) is a [[Terminal User Interface (TUI)]] for browsing and managing tasks in projects using the [[Beads]] issue tracking system. Written in Go, it provides graph-aware analysis of project dependencies. The tool treats projects as [[Directed Acyclic Graphs (DAG)]] rather than simple lists. This enables visualization of dependencies, bottlenecks, and critical paths that traditional issue trackers miss. ## Key Features ### Interactive Interface - Vim-style keyboard navigation (j/k for movement) - Split-view dashboard showing lists and detailed information - Markdown rendering with syntax highlighting - Real-time filtering (Open, Closed, Ready tasks) - File-watching that auto-refreshes when `.beads/beads.jsonl` changes ### View Modes - **List view**: Fast browsing of issues - **[[Kanban board]]** (`b`): Workflow visualization - **Graph view** (`g`): Dependency exploration - **Insights dashboard** (`i`): Graph metrics display - **History view** (`h`): Commit correlation with changes - **Tree view**: Hierarchical exploration ### Graph Analysis The system computes nine graph-theoretic metrics: - **PageRank**: Identifies foundational blockers through recursive dependency analysis - **Betweenness**: Reveals cross-team bottlenecks and communication chokepoints - **HITS**: Distinguishes epics (hubs) from infrastructure (authorities) - **Critical Path**: Finds zero-slack tasks determining project minimum completion time - **Eigenvector Centrality**: Surfaces strategic dependencies beyond simple connection counts - **Degree, Density, Cycles, Topological Sort** ## AI Agent Integration Beads Viewer provides "robot mode" for programmatic access via `--robot-*` flags: - `--robot-triage`: Comprehensive analysis with rankings and recommendations - `--robot-next`: Minimal output showing top priority item - `--robot-plan`: Parallel execution tracks with blocking information - `--robot-insights`: Full graph metrics computation - `--robot-graph`: Dependency graph export (JSON, DOT, Mermaid formats) Important: Never run bare `bv` in agent context. Always use `--robot-*` flags to prevent launching the interactive TUI. The tool can automatically inject instructions into `AGENTS.md`, `CLAUDE.md`, or equivalent files. ## Quick Actions - `E`: Export issues to timestamped Markdown with diagrams - `C`: Copy selected issue as formatted Markdown - `O`: Open `.beads/beads.jsonl` in GUI editor - `t/T`: Time-travel comparing against git revisions - `/`: Fuzzy search by ID, title, or content ## Installation ### Homebrew (Recommended) ```bash brew install dicklesworthstone/tap/bv ``` ### Windows (Scoop) ```bash scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket scoop install dicklesworthstone/bv ``` ### Install Scripts Linux/macOS: ```bash curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/main/install.sh" | bash ``` Windows PowerShell: ```powershell irm "https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/main/install.ps1" | iex ``` ## References - https://github.com/Dicklesworthstone/beads_viewer ## Related - [[Beads]] - [[Ralph TUI]] - [[Terminal User Interface (TUI)]] - [[Directed Acyclic Graph (DAG)]] - [[Git]] - [[Command Line Interface (CLI)]]