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

brew install dicklesworthstone/tap/bv

This method provides:

• Automatic updates via brew upgrade
• Dependency management
• Easy uninstall via brew uninstall

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

Download the latest release for your platform:

• Linux x86_64
• macOS Intel
• macOS ARM
• Windows

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.

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.

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

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.

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.

• 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.

• 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.

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.

### 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](https://github.com/Dicklesworthstone/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

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

#### 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 '.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")'

**Performance:** Phase 1 instant, Phase 2 async (500ms timeout). Prefer `--robot-plan` over `--robot-insights` when speed matters. Results cached by data hash.

Use bv instead of parsing beads.jsonl—it computes PageRank, critical paths, cycles, and parallel tracks deterministically.

bv can automatically add the above instructions to your project's agent file:

• On first run, bv checks for AGENTS.md (or similar files) and offers to inject the blurb if not present
• Choose "Yes" to add the instructions, "No" to skip, or "Don't ask again" to remember your preference
• Preferences are stored per-project in ~/.config/bv/agent-prompts/

Supported Files (checked in order):

1. AGENTS.md (preferred)
2. CLAUDE.md
3. agents.md
4. claude.md

Manual Control:

bd agents --show              # Display current blurb content
bd agents --check             # Check if blurb is present in agent file
bd agents --add               # Add blurb to agent file
bd agents --remove            # Remove blurb from agent file
bd agents --clear-preference  # Reset the "don't ask again" preference

Version Tracking:

The blurb uses HTML comment markers for version tracking:

<!-- bv-agent-instructions-v1 -->
... content ...
<!-- end-bv-agent-instructions -->

When a new version of the blurb is released, bv can detect the outdated version and offer to update it.

bv treats your project as a Directed Acyclic Graph (DAG), not just a list. This allows it to derive insights about what is truly important.

graph TD
    %% Soft Pastel Theme — Refined
    classDef data fill:#e3f2fd,stroke:#90caf9,stroke-width:2px,color:#1565c0,rx:8
    classDef logic fill:#fff8e1,stroke:#ffcc80,stroke-width:2px,color:#e65100,rx:8
    classDef ui fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px,color:#6a1b9a,rx:8
    classDef output fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px,color:#2e7d32,rx:8

    subgraph storage [" 📂 Data Layer "]
        A[".beads/beads.jsonl<br/>JSONL Issue Store"]:::data
    end

    subgraph engine [" ⚙️ Analysis Engine "]
        B["Loader"]:::logic
        C["Graph Builder"]:::logic
        D["9 Metrics<br/>PageRank · Betweenness · HITS..."]:::logic
    end

    subgraph interface [" 🖥️ TUI Layer "]
        E["Bubble Tea Model"]:::ui
        F["List View"]:::ui
        G["Graph View"]:::ui
        G2["Tree View"]:::ui
        H["Insights Dashboard"]:::ui
    end

    subgraph outputs [" 📤 Outputs "]
        I["--robot-insights<br/>JSON for AI Agents"]:::output
        J["--export-md<br/>Markdown Report"]:::output
    end

    A --> B
    B --> C
    C --> D
    D --> E
    D --> I
    D --> J
    E --> F
    E --> G
    E --> G2
    E --> H

    linkStyle 0,1,2 stroke:#90caf9,stroke-width:2px
    linkStyle 3,4,5 stroke:#ffcc80,stroke-width:2px
    linkStyle 6,7,8,9 stroke:#ce93d8,stroke-width:2px

bv computes 9 graph-theoretic metrics to surface hidden project dynamics:

The Math: Originally designed to rank web pages by "importance" based on incoming links, PageRank models a "random surfer" walking the graph. In our dependency graph (u → v implies u depends on v), we treat dependencies as "votes" of importance. $$ PR(v) = \frac{1-d}{N} + d \sum_{u \in M(v)} \frac{PR(u)}{L(u)} $$

The Intuition: If many tasks depend on Task A, or if a single very important Task B depends on Task A, then Task A implicitly becomes "heavy." A random walker following dependency links will frequently get stuck at Task A.

Pragmatic Meaning: Foundational Blocks. High PageRank tasks are the bedrock of your project. They are rarely "features" in the user-facing sense; they are often schemas, core libraries, or architectural decisions. Breaking them breaks the graph.

The Math: Defined as the fraction of all shortest paths in the network that pass through a given node $v$. $$C_B(v) = \sum_{s \neq v \neq t} \frac{\sigma_{st}(v)}{\sigma_{st}}$$

The Intuition: Imagine information (or progress) flowing from every task to every other task along the most efficient route. "Bridge nodes" that connect otherwise isolated clusters (e.g., the Frontend cluster and the Backend cluster) will see a massive amount of traffic.

Pragmatic Meaning: Gatekeepers & Bottlenecks. A task with high Betweenness is a choke point. It might be an API contract that both the mobile app and the server team are waiting on. If this task is delayed, it doesn't just block one thread; it prevents entire sub-teams from synchronizing.

The Math: An iterative algorithm that defines two scores for every node:

• Authority: The sum of Hub scores of nodes pointing to it.
• Hub: The sum of Authority scores of nodes it points to.

The Intuition: This models a "mutually reinforcing" relationship. Good libraries (Authorities) are used by many applications. Good applications (Hubs) use many good libraries.

Pragmatic Meaning: Epics vs. Infrastructure.

• High Hub Score: These are your Epics or Product Features. They aggregate many dependencies to deliver value.
• High Authority Score: These are your Utilities. They provide value to many consumers.

The Math: In a DAG, the longest path represents the minimum time required to complete the project (assuming infinite parallelism). bv computes this recursively: $$Impact(u) = 1 + \max({Impact(v) \mid u \to v})$$

The Intuition: If you hold the graph by its "leaf" nodes (tasks with no dependencies) and let it dangle, the tasks at the very top that support the longest chains are carrying the most weight.

Pragmatic Meaning: Keystones. A Keystone task is one where any delay translates 1:1 into a delay for the final project delivery. These tasks have zero "slack."

The Math: Eigenvector centrality measures a node's influence by considering not just its connections, but the importance of those connections. A node with few but highly influential neighbors can score higher than a node with many unimportant neighbors. $$x_i = \frac{1}{\lambda} \sum_{j \in N(i)} x_j$$

Where $\lambda$ is the largest eigenvalue of the adjacency matrix and $N(i)$ are neighbors of node $i$.

The Intuition: It's not just how many connections you have, but who you're connected to. Being depended on by a critical task makes you more important than being depended on by many trivial tasks.

Pragmatic Meaning: Strategic Dependencies. High Eigenvector tasks are connected to the "power players" in your graph. They may not have many direct dependents, but their dependents are themselves critical.

The Math: The simplest centrality measure—just count the edges. $$C_D^{in}(v) = |{u : u \to v}|$$

$$C_D^{out}(v) = |{u : v \to u}|$$

The Intuition:

• In-Degree: How many tasks depend on me? (I am a blocker)
• Out-Degree: How many tasks do I depend on? (I am blocked)

Pragmatic Meaning: Immediate Impact.

• High In-Degree: This task is a direct blocker for many others. Completing it immediately unblocks work.
• High Out-Degree: This task has many prerequisites. It's likely to be blocked and should be scheduled later in the execution plan.

The Math: Density measures how "connected" the graph is relative to its maximum possible connections. $$D = \frac{|E|}{|V|(|V|-1)}$$

Where $|E|$ is the edge count and $|V|$ is the node count. For a directed graph, the maximum edges is $|V|(|V|-1)$.

The Intuition: A density of 0.0 means no dependencies exist (isolated tasks). A density approaching 1.0 means everything depends on everything (pathological complexity).

Pragmatic Meaning: Project Health Indicator.

• Low Density (< 0.05): Healthy. Tasks are relatively independent and can be parallelized.
• Medium Density (0.05 - 0.15): Normal. Reasonable interconnection reflecting real-world dependencies.
• High Density (> 0.15): Warning. Overly coupled project. Consider breaking into smaller modules.

The Math: A cycle in a directed graph is a path v₁ → v₂ → ⋯ → vₖ → v₁ where the start and end nodes are identical. bv uses Tarjan's algorithm variant via topo.DirectedCyclesIn to enumerate all elementary cycles.

The Intuition: If A depends on B, and B depends on A, neither can ever be completed. This is a logical impossibility that must be resolved.

Pragmatic Meaning: Structural Errors. Cycles are bugs in your project plan, not just warnings. They indicate:

• Misclassified dependencies (A doesn't really block B, or vice versa)
• Missing intermediate tasks (A and B both depend on an unstated C)
• Scope confusion (A and B should be merged into a single task)

The Math: A topological ordering of a DAG is a linear sequence of all vertices such that for every edge u → v, vertex u appears before v in the sequence. Only acyclic graphs have valid topological orderings.

The Intuition: If you must complete tasks in dependency order, topological sort gives you a valid order (there may be many).

Pragmatic Meaning: Work Queue. The topological order is the foundation of bv's execution planning. Combined with priority weights, it generates the "what to work on next" recommendations that power --robot-plan.

bv bridges the gap between raw data and AI agents. Agents struggle with graph algorithms; bv solves this by acting as a deterministic "sidecar" that offloads the cognitive burden of graph traversal.

sequenceDiagram
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'primaryTextColor': '#2e7d32', 'primaryBorderColor': '#81c784', 'lineColor': '#90a4ae', 'secondaryColor': '#fff8e1', 'tertiaryColor': '#fce4ec'}}}%%

    participant User
    participant Agent as 🤖 AI Agent
    participant BV as ⚡ bv
    participant File as 📄 beads.jsonl

    User->>Agent: "Fix the next blocked task"

    rect rgba(232, 245, 233, 0.4)
        Note over Agent, BV: Cognitive Offloading
        Agent->>BV: bv --robot-plan
        BV->>File: Read & Parse
        BV->>BV: PageRank + Topo Sort
        BV-->>Agent: { next: "TASK-123", unblocks: 5 }
    end

    rect rgba(255, 243, 224, 0.3)
        Note over Agent: Implementation Phase
        Agent->>Agent: Fix TASK-123
        Agent->>BV: bv --robot-insights
        BV-->>Agent: Updated graph metrics
    end

The primary design goal of the Robot Protocol is Cognitive Offloading. Large Language Models (LLMs) are probabilistic engines; they are excellent at semantic reasoning (coding, writing) but notoriously unreliable at algorithmic graph traversal (finding cycles, computing shortest paths). The two-phase analyzer returns degree/topo/density immediately and completes PageRank/Betweenness/HITS/Eigenvector/Critical Path/Cycles asynchronously with size-aware timeouts and hashed caching, so repeat robot calls stay fast when the graph hasn’t changed.

If you feed an Agent raw beads.jsonl data, you are forcing the Agent to:

1. Parse thousands of lines of JSON.
2. Reconstruct the dependency graph in its context window.
3. "Hallucinate" a path traversal or cycle check.

bv solves this by providing a deterministic graph engine sidecar.

Using beads directly gives an agent data. Using bv --robot-insights gives an agent intelligence.

Agents typically use bv in three phases:

1. Triage & Orientation: Before starting a session, the agent runs bv --robot-insights. It receives a lightweight JSON summary of the project's structural health. It immediately knows:

   • "I should not work on Task C yet because it depends on Task B, which is a Bottleneck."
   • "The graph has a cycle (A->B->A); I must fix this structural error before adding new features."

2. Impact Analysis: When asked to "refactor the login module," the agent checks the PageRank and Impact Scores of the relevant beads. If the scores are high, the agent knows this is a high-risk change with many downstream dependents, prompting it to run more comprehensive tests.

3. Execution Planning: Instead of guessing the order of operations, the agent uses bv's topological sort to generate a strictly linearized plan.

JSON Output Schema (--robot-insights): The output is designed to be strictly typed and easily parseable by tools like jq or standard JSON libraries.

{
  "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": { "CORE-123": 0.15, "...": "..." },
    "betweenness": { "CORE-123": 0.45, "...": "..." },
    "eigenvector": { "AUTH-007": 0.82, "...": "..." },
    "hubs": { "EPIC-100": 0.67, "...": "..." },
    "authorities": { "UTIL-050": 0.91, "...": "..." },
    "inDegree": { "CORE-123": 5, "...": "..." },
    "outDegree": { "CORE-123": 2, "...": "..." },
    "criticalPathScore": { "API-001": 12.0, "...": "..." },
    "density": 0.045,
    "topologicalOrder": ["CORE-123", "API-001", "..."]
  }
}

bv is built with the Bubble Tea framework, ensuring a glitch-free, 60fps experience. It features an adaptive layout engine that responds to terminal resize events and a custom ASCII/Unicode graph renderer.

flowchart LR
    classDef core fill:#fef3e2,stroke:#f5d0a9,stroke-width:2px,color:#8b5a2b
    classDef engine fill:#f0e6f6,stroke:#d4b8e0,stroke-width:2px,color:#5d3a6b
    classDef ui fill:#e6f3e6,stroke:#b8d9b8,stroke-width:2px,color:#2d5a2d
    classDef output fill:#e8f4f8,stroke:#b8d4e3,stroke-width:2px,color:#2c5f7c

    INPUT["⌨️ Input<br/>Keys · Mouse · Resize"]:::core
    MODEL["🫖 Model<br/>Issues · Stats · Focus"]:::core
    GRAPH["🧮 Graph Engine<br/>PageRank · HITS · Cycles"]:::engine
    VIEWS["🖼️ Views<br/>List · Board · Graph · Tree · Insights"]:::ui
    LAYOUT["📐 Layout<br/>Mobile · Split · Wide"]:::ui
    TERM["🖥️ Terminal<br/>60fps Output"]:::output

    INPUT -->|tea.Msg| MODEL
    GRAPH -->|metrics| MODEL
    MODEL -->|state| VIEWS
    VIEWS --> LAYOUT
    LAYOUT --> TERM

    linkStyle 0 stroke:#f5d0a9,stroke-width:2px
    linkStyle 1 stroke:#d4b8e0,stroke-width:2px
    linkStyle 2 stroke:#b8d9b8,stroke-width:2px
    linkStyle 3,4 stroke:#b8d4e3,stroke-width:2px

bv doesn't just dump text; it calculates geometry on every render cycle.

• Dynamic Resizing: The View() function inspects the current terminal width (msg.Width) on every frame.
• Breakpoint Logic:
  • < 100 cols: Mobile Mode. List takes 100% width.
  • > 100 cols: Split Mode. List takes 40%, Details take 60%.
  • > 140 cols: Ultra-Wide. List injects extra columns (Sparklines, Labels) that are normally hidden.
• Padding Awareness: The layout engine explicitly accounts for borders (2 chars) and padding (2 chars) to prevent "off-by-one" wrapping errors that plague many TUIs.

Rendering 10,000 issues would choke a naive terminal app. bv implements Viewport Virtualization:

• Windowing: We only render the slice of rows currently visible in the terminal window.
• Pre-Computation: Graph metrics (PageRank, etc.) are computed once at startup in a separate goroutine, not on every frame. The underlying graph uses a compact adjacency-list implementation that's 50-100× faster than naive map-backed approaches.
• Detail Caching: The Markdown renderer is instantiated lazily and reused, avoiding expensive regex recompilation.

We built a custom 2D ASCII/Unicode rendering engine from scratch to visualize the dependency graph.

• Canvas Abstraction: A 2D grid of rune cells and style pointers allows us to draw "pixels" in the terminal.
• Manhattan Routing: Edges are drawn using orthogonal lines with proper Unicode corner characters ( ╭, ─, ╮, │, ╰, ╯) to minimize visual noise.
• Topological Layering: Nodes are arranged in layers based on their "Impact Depth," ensuring that dependencies always flow downwards.

We use Lipgloss to enforce a strict design system.

• Semantic Colors: Colors are defined semantically (Theme.Blocked, Theme.Open) rather than hardcoded hex values. This allows bv to switch between "Dracula" (Dark) and "Light" modes seamlessly.
• Status Indicators: We use Nerd Font glyphs (🐛, ✨, 🔥) paired with color coding to convey status instantly without reading text.

In dense information environments like the terminal, text is expensive. bv employs high-density data visualization techniques (pkg/ui/visuals.go) inspired by Edward Tufte to convey complex metrics in minimal space.

When viewing the list in Ultra-Wide mode, bv renders a "Graph Score" column using Unicode block characters ( , ▂, ▃, ▄, ▅, ▆, ▇, █).

• The Math: RenderSparkline(val, width) normalizes a float value (0.0 - 1.0) against the available character width. It calculates the precise block height for each character cell to create a continuous bar chart effect.
• The Utility: This allows you to scan a list of 50 issues and instantly spot the "spikes" in complexity or centrality without reading a single number.

We don't just use random colors. pkg/ui/visuals.go implements a perceptually uniform color ramp (GetHeatmapColor) that maps metric intensity to a gradient:

• 0.0 - 0.2: Low (Gray/Dim)
• 0.2 - 0.5: Mid (Blue/Cool)
• 0.5 - 0.8: High (Purple/Warm)
• 0.8 - 1.0: Peak (Pink/Hot) This visual encoding is applied to badges in the Insights Dashboard, allowing you to differentiate between "somewhat important" and "critically urgent" tasks at a glance.

In a project with thousands of issues, you cannot afford to wait for a backend query. bv implements a composite, in-memory fuzzy search that feels instantaneous.

Instead of searching fields individually (which requires complex UI controls), bv flattens every issue into a single searchable "vector" at load time. The FilterValue() method constructs a composite string containing:

• Core Identity: ID ("CORE-123") and Title ("Fix login race condition")
• Metadata: Status ("open"), Type ("bug"), Priority
• Context: Assignee ("@steve") and Labels ("frontend, v1.0")

When you press /, the search engine performs a fuzzy subsequence match against this composite vector.

• Example: Typing "log fix" successfully matches "Fix login race condition".
• Example: Typing "steve bug" finds bugs assigned to Steve.
• Example: Typing "open v1.0" filters for open items in the v1.0 release.

• Zero Allocation: The search index is built once during the initial load (loader.LoadIssues).
• Client-Side Filtering: Filtering happens entirely within the render loop. There is no database latency, no network round-trip, and no "loading" spinner.
• Stable Sort: Search results maintain the topological and priority sorting of the main list, ensuring that even filtered views reflect the project's true priorities.

A common question is: "How do you render complex diagrams in a text-only terminal?"

bv approaches this problem in two ways:

For the interactive TUI, we built a specialized ASCII/Unicode Graph Engine (pkg/ui/graph.go) that replicates the core value of a Mermaid flowchart without requiring graphical protocol support (like Sixel).

• Topological Layering: Nodes are automatically sorted by their dependency depth.
• Orthogonal Routing: Connections use box-drawing characters (│, ─, ╭, ╯) to draw clean, right-angled paths that avoid crossing through node text.
• Adaptive Canvas: The virtual canvas expands infinitely, but the viewport (pkg/ui/viewport.go) clips rendering to exactly what fits on your screen, panning smoothly with h/j/k/l.

For external reporting, bv includes a robust Mermaid Generator (pkg/export/markdown.go).

• Sanitization: It automatically escapes unsafe characters in issue titles to prevent syntax errors in the Mermaid parser.
• Collision-Proof IDs: When sanitization would collide (e.g., symbol-only IDs), nodes get a stable hash suffix so edges never merge or disappear.
• Class-Based Styling: Nodes are assigned CSS classes (classDef open, classDef blocked) based on their status, so the resulting diagram visually matches the TUI's color scheme when rendered on GitHub or GitLab.
• Semantic Edges: Blockers are rendered with thick arrows (==>), while loose relations use dashed lines (-.->), encoding the severity of the link into the visual syntax.

graph TD
    %% Generated by bv — Soft Pastel Theme
    classDef open fill:#c8e6c9,stroke:#81c784,stroke-width:2px,color:#2e7d32
    classDef blocked fill:#ffcdd2,stroke:#e57373,stroke-width:2px,color:#c62828
    classDef inProgress fill:#fff3e0,stroke:#ffb74d,stroke-width:2px,color:#ef6c00

    A["CORE-123<br/>Refactor Login"]:::open
    B["UI-456<br/>Login Page"]:::blocked
    C["API-789<br/>Auth Endpoint"]:::inProgress

    A --> B
    A --> C
    C -.-> B

    linkStyle 0 stroke:#81c784,stroke-width:2px
    linkStyle 1 stroke:#81c784,stroke-width:2px
    linkStyle 2 stroke:#e57373,stroke-width:1px,stroke-dasharray:5

Export the dependency graph in multiple formats for visualization, documentation, or integration with other tools:

bv --robot-graph                              # JSON (default)
bv --robot-graph --graph-format=dot           # Graphviz DOT
bv --robot-graph --graph-format=mermaid       # Mermaid diagram

# Focused subgraph extraction
bv --robot-graph --graph-root=bv-123          # Subgraph from specific root
bv --robot-graph --graph-root=bv-123 --graph-depth=3  # Limited depth

For large projects, extract focused views around specific issues:

• --graph-root=ID: Start from a specific issue and include all its dependencies and dependents
• --graph-depth=N: Limit traversal to N levels (0 = unlimited)

{
  "nodes": [
    { "id": "bv-123", "title": "Fix auth", "status": "open", "priority": 1 }
  ],
  "edges": [
    { "from": "bv-124", "to": "bv-123", "type": "blocks" }
  ],
  "metadata": {
    "data_hash": "abc123",
    "node_count": 45,
    "edge_count": 62
  }
}

For deep exploration of complex dependency structures, bv generates self-contained HTML visualizations powered by a force-directed graph engine. Unlike static exports, these are fully interactive—pan, zoom, filter, and drill into individual beads without any server or dependencies.

# Generate interactive HTML graph
bv --export-graph graph.html                    # Export to specific file
bv --export-graph                               # Auto-generate timestamped filename
bv --export-graph --graph-title "Q4 Sprint"     # Custom title
bv --export-graph --graph-include-closed        # Include closed issues

Traditional list-based views show tasks in isolation. The interactive graph reveals the hidden structure of your project:

• Dependency Chains: See at a glance which tasks are blocking others, and trace critical paths through your backlog
• Bottleneck Detection: Nodes sized by PageRank/betweenness instantly reveal which items have outsized impact
• Cluster Discovery: Force-directed layout naturally groups related work, exposing team boundaries or feature clusters
• Context Switching: Hover over any node to see full details—description, design notes, acceptance criteria—without leaving the visualization

Each HTML file is completely self-contained (typically 400KB-1MB depending on project size):

The visualization provides a rich, keyboard-driven interface:

┌─────────────────────────────────────────────────────────────────────────────┐
│  📊 Project Graph | [Search...] | Layout ▾ | Filters ▾ | 🔥 📋 ⭐ ☀️ ❓    │
├──────────────────────┬──────────────────────────────────────────────────────┤
│                      │                                                      │
│   Bead Details       │              Force-Directed Graph                    │
│   ═══════════════    │                                                      │
│   ID: bv-xyz         │         ●───────●                                    │
│   Title: Feature X   │        /│\      │                                    │
│                      │       ● ● ●     ●───●                                │
│   Description:       │         │           │                                │
│   [markdown...]      │         ●───────────●                                │
│                      │                                                      │
│   Graph Metrics:     │              ┌──────────────────┐                    │
│   PageRank: 2.34%    │              │ Low ▰▰▰▰ High   │  <- Heatmap Legend │
│   Betweenness: 0.12  │              └──────────────────┘                    │
│   Critical Path: 4.0 │         ┌─────────────┐                              │
│                      │         │ Mini-map    │                              │
│   Blocked By: [...]  │         └─────────────┘                              │
│   Blocks: [...]      │                                                      │
└──────────────────────┴──────────────────────────────────────────────────────┘

Nodes encode multiple dimensions of information simultaneously:

The visualization is fully keyboard-driven:

Filtering & Search

• Full-text search: Find beads by ID, title, or content with live preview
• Status filter: Open, In Progress, Blocked, Closed
• Type filter: Feature, Bug, Task, Epic
• Priority filter: P0 (Critical) through P4 (Backlog)
• Label filter: Dynamically populated from your data

Navigation

• Path Finder: Press P, then click two nodes to find and highlight the shortest path between them
• Recently Viewed: Press Y to see your navigation history and jump back to previous nodes
• Mini-map: Overview in the corner shows your current viewport position

Panels

• Docked Detail Panel: Left sidebar shows full bead information on hover (default)
• Floating Mode: Press D to detach the panel for floating tooltip-style display
• Triage Panel: Shows top recommendations with scores and reasoning
• Top Nodes: Lists highest PageRank nodes for quick navigation

Customization

• Layout Modes: Force-directed (default), DAG top-down, DAG left-right, Radial
• Size Metric: Choose what determines node size (PageRank, betweenness, critical path, in-degree)
• Light/Dark Mode: Full theme support with proper contrast
• Preferences Saved: Theme and layout choices persist via localStorage

# 1. Generate the visualization
bv --export-graph sprint_review.html --graph-title "Sprint 42 Review"

# 2. Open in browser
open sprint_review.html    # macOS
xdg-open sprint_review.html  # Linux
start sprint_review.html   # Windows

# 3. Share with team
# The HTML file is self-contained—just send it or host anywhere

• No Server Required: Everything runs client-side in the browser
• Offline Capable: Works completely offline once opened
• Modern Browsers: Tested on Chrome, Firefox, Safari, Edge
• Performance: Handles 500+ nodes smoothly with WebGL-accelerated rendering
• File Size: Typically 400KB-1MB depending on project size and content

bv isn't just for personal browsing; it's a communication tool. The --export-md flag generates a Management-Ready Status Report that converts your repo state into a polished document suitable for stakeholders.

The exporter (pkg/export/markdown.go) constructs a document that bridges human readability and visual data:

• Summary at a Glance: Top-level statistics (Total, Open, Blocked, Closed) give immediate health context.
• Embedded Graph: It injects the full dependency graph as a Mermaid diagram right into the document. On platforms like GitHub or GitLab, this renders as an interactive chart.
• Anchor Navigation: A generated Table of Contents uses URL-friendly slugs (#core-123-refactor-login) to link directly to specific issue details, allowing readers to jump between the high-level graph and low-level specs.

We don't just dump JSON values. The exporter applies specific formatting rules to ensure the report looks professional:

• Metadata Tables: Key fields (Assignee, Priority, Status) are aligned in GFM (GitHub Flavored Markdown) tables with emoji indicators.
• Conversation threading: Comments are rendered as blockquotes (>) with relative timestamps, preserving the flow of discussion distinct from the technical spec.
• Intelligent Sorting: The report doesn't list issues ID-sequentially. It applies the same priority logic as the TUI: Open Critical issues appear first, ensuring the reader focuses on what matters now.

One of bv's most powerful capabilities is Time-Travel—the ability to compare your project's state across any two points in git history. This transforms bv from a "viewer" into a progress tracking and regression detection system.

bv captures the complete state of your project at any moment:

graph LR
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'primaryTextColor': '#2e7d32', 'primaryBorderColor': '#81c784', 'lineColor': '#90a4ae'}}}%%

    subgraph "Git History"
        A["HEAD~10<br/><small>10 commits ago</small>"]
        B["HEAD~5<br/><small>5 commits ago</small>"]
        C["HEAD<br/><small>Current</small>"]
    end

    subgraph "Snapshots"
        D["Snapshot A<br/><small>45 issues, 3 cycles</small>"]
        E["Snapshot B<br/><small>52 issues, 1 cycle</small>"]
        F["Snapshot C<br/><small>58 issues, 0 cycles</small>"]
    end

    A --> D
    B --> E
    C --> F
    D -.->|"diff"| E
    E -.->|"diff"| F

    style D fill:#ffcdd2,stroke:#e57373,stroke-width:2px
    style E fill:#fff3e0,stroke:#ffb74d,stroke-width:2px
    style F fill:#c8e6c9,stroke:#81c784,stroke-width:2px

The SnapshotDiff captures every meaningful change:

The GitLoader enables loading issues from any git revision:

loader := NewGitLoader("/path/to/repo")

// Load from various references
current, _ := loader.LoadAt("HEAD")
lastWeek, _ := loader.LoadAt("HEAD~7")
release, _ := loader.LoadAt("v1.0.0")
byDate, _ := loader.LoadAt("main@{2024-01-15}")

Cache Architecture:

• Revisions are resolved to commit SHAs for stable caching
• Thread-safe sync.RWMutex protects concurrent access
• 5-minute TTL prevents stale data while avoiding redundant git calls

1. Sprint Retrospectives: "How many issues did we close this sprint?"
2. Regression Detection: "Did we accidentally reintroduce a dependency cycle?"
3. Trend Analysis: "Is our graph density increasing? Are we creating too many dependencies?"
4. Release Notes: "Generate a diff of all changes between v1.0 and v2.0"

Instead of memorizing CLI flags or repeatedly setting filters, bv supports Recipes—YAML-based view configurations that can be saved, shared, and version-controlled.

# .beads/recipes/sprint-review.yaml
name: sprint-review
description: "Issues touched in the current sprint"

filters:
  status: [open, in_progress, closed]
  updated_after: "14d"              # Relative time: 14 days ago
  exclude_tags: [backlog, icebox]

sort:
  field: updated
  direction: desc
  secondary:
    field: priority
    direction: asc

view:
  columns: [id, title, status, priority, updated]
  show_metrics: true
  max_items: 50

export:
  format: markdown
  include_graph: true

bv ships with 11 pre-configured recipes:

# Interactive picker (press 'R' in TUI)
bv

# Direct recipe invocation
bv --recipe actionable
bv --recipe high-impact

# Custom recipe file
bv --recipe .beads/recipes/sprint-review.yaml

Traditional issue trackers sort by a single dimension—usually priority. bv computes a multi-factor Impact Score that blends graph-theoretic metrics with temporal and priority signals.

$$ \text{Impact} = 0.30 \cdot \text{PageRank} + 0.30 \cdot \text{Betweenness} + 0.20 \cdot \text{BlockerRatio} + 0.10 \cdot \text{Staleness} + 0.10 \cdot \text{PriorityBoost} $$

• 60% Graph Metrics: The structure of dependencies is the primary driver of true importance.
• 20% Blocker Ratio: Direct dependents matter for immediate unblocking.
• 10% Staleness: Old issues deserve attention; they may be forgotten blockers.
• 10% Priority: Human judgment is valuable but can be outdated or politically biased.

{
  "issue_id": "CORE-123",
  "title": "Refactor auth module",
  "score": 0.847,
  "breakdown": {
    "pagerank": 0.27,
    "betweenness": 0.25,
    "blocker_ratio": 0.18,
    "staleness": 0.07,
    "priority_boost": 0.08
  }
}

bv generates actionable recommendations when the computed impact score diverges significantly from the human-assigned priority:

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

Press p in the list view to toggle Priority Hints—inline visual indicators showing which issues have misaligned priorities:

┌──────────────────────────────────────────────────────────────┐
│  OPEN     CORE-123 ⬆ Database schema migration       P3  🟢 │
│  OPEN     UI-456     Login page styling              P2  🟢 │
│  BLOCKED  API-789  ⬇ Legacy endpoint wrapper         P1  🔴 │
└──────────────────────────────────────────────────────────────┘
        ⬆ = Impact suggests higher priority (red arrow)
        ⬇ = Impact suggests lower priority (teal arrow)

This provides at-a-glance feedback on whether your priority assignments match the computed graph importance.

When you ask "What should I work on next?", bv doesn't just pick the highest-priority item. It generates a complete execution plan that respects dependencies and identifies opportunities for parallel work.

The planner uses Union-Find to identify connected components in the dependency graph, grouping related issues into independent "tracks" that can be worked on concurrently.

graph TD
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    subgraph track_a ["🅰️ Track A: Auth System"]
        A1["AUTH-001<br/>P1 · Unblocks 3"]:::actionable
        A2["AUTH-002"]:::blocked
        A3["AUTH-003"]:::blocked
    end

    subgraph track_b ["🅱️ Track B: UI Polish"]
        B1["UI-101<br/>P2 · Unblocks 1"]:::actionable
        B2["UI-102"]:::blocked
    end

    subgraph track_c ["🅲 Track C: Independent"]
        C1["DOCS-001<br/>P3 · Unblocks 0"]:::actionable
    end

    A1 --> A2
    A2 --> A3
    B1 --> B2

    classDef actionable fill:#c8e6c9,stroke:#81c784,stroke-width:2px,color:#2e7d32
    classDef blocked fill:#ffcdd2,stroke:#e57373,stroke-width:2px,color:#c62828

    linkStyle 0,1,2 stroke:#81c784,stroke-width:2px

{
  "tracks": [
    {
      "track_id": "track-A",
      "reason": "Independent work stream",
      "items": [
        { "id": "AUTH-001", "priority": 1, "unblocks": ["AUTH-002", "AUTH-003", "API-005"] }
      ]
    },
    {
      "track_id": "track-B",
      "reason": "Independent work stream",
      "items": [
        { "id": "UI-101", "priority": 2, "unblocks": ["UI-102"] }
      ]
    }
  ],
  "total_actionable": 3,
  "total_blocked": 5,
  "summary": {
    "highest_impact": "AUTH-001",
    "impact_reason": "Unblocks 3 tasks",
    "unblocks_count": 3
  }
}

1. Identify Actionable Issues: Filter to non-closed issues with no open blockers.
2. Compute Unblocks: For each actionable issue, calculate what becomes unblocked if it's completed.
3. Find Connected Components: Use Union-Find to group issues by their dependency relationships.
4. Build Tracks: Create parallel tracks from each component, sorted by priority within each track.
5. Compute Summary: Identify the single highest-impact issue (most downstream unblocks).

• Deterministic: Same input always produces same plan (no LLM hallucination).
• Parallelism-Aware: Multiple agents can grab different tracks without conflicts.
• Impact-Ranked: The highest_impact field tells agents exactly where to start.

The Insights Dashboard (i) transforms abstract graph metrics into an interactive exploration interface. Instead of just showing numbers, it lets you drill into why a bead scores high and what that means for your project.

┌─────────────────────┬─────────────────────┬─────────────────────┐
│  🚧 Bottlenecks     │  🏛️ Keystones       │  🌐 Influencers     │
│  Betweenness        │  Impact Depth       │  Eigenvector        │
│  ─────────────────  │  ─────────────────  │  ─────────────────  │
│  ▸ 0.45 AUTH-001    │    12.0 CORE-123    │    0.82 API-007     │
│    0.38 API-005     │    10.0 DB-001      │    0.71 AUTH-001    │
└─────────────────────┴─────────────────────┴─────────────────────┘
┌─────────────────────┬─────────────────────┬─────────────────────┐
│  🛰️ Hubs            │  📚 Authorities     │  🔄 Cycles          │
│  HITS Hub Score     │  HITS Auth Score    │  Circular Deps      │
│  ─────────────────  │  ─────────────────  │  ─────────────────  │
│    0.67 EPIC-100    │    0.91 UTIL-050    │  ⚠ A → B → C → A    │
│    0.54 FEAT-200    │    0.78 LIB-010     │  ⚠ X → Y → X        │
└─────────────────────┴─────────────────────┴─────────────────────┘

When you select a bead, the right-side Detail Panel shows not just the score, but the proof—the actual beads and values that contributed:

─── CALCULATION PROOF ───
BW(v) = Σ (σst(v) / σst) for all s≠v≠t

Betweenness Score: 0.452

Beads depending on this (5):
  ↓ UI-Login: Implement login form
  ↓ UI-Dashboard: User dashboard
  ↓ API-Auth: Authentication endpoint
  ... +2 more

This depends on (2):
  ↑ DB-Schema: User table migration
  ↑ CORE-Config: Environment setup

This bead lies on many shortest paths between
other beads, making it a critical junction.

The Kanban Board (b) provides a columnar workflow view with intelligent swimlane grouping, visual dependency indicators, and rich card details. Empty columns automatically collapse to maximize screen real estate.

Press s to cycle through three grouping modes:

The current mode is shown in the status bar. Each mode uses distinct column colors for quick visual identification.

Card borders are color-coded to show dependency status at a glance:

┌─ 🔴 RED ──────────────────┐    ┌─ 🟡 YELLOW ─────────────────┐
│ BLOCKED                    │    │ HIGH-IMPACT                  │
│ This card has unresolved   │    │ This card blocks others.     │
│ dependencies. Work on      │    │ Completing it will unblock   │
│ blockers first.            │    │ downstream work.             │
└────────────────────────────┘    └──────────────────────────────┘

┌─ 🟢 GREEN ────────────────┐    ┌─ ⬜ DEFAULT ─────────────────┐
│ READY TO WORK              │    │ NORMAL                       │
│ Open issue with no         │    │ Standard priority, no        │
│ blockers. Pick this up!    │    │ blocking relationships.      │
└────────────────────────────┘    └──────────────────────────────┘

Search matches overlay with purple (current match) or blue (other matches) borders.

Each card displays comprehensive metadata in a compact format:

┌────────────────────────────────────┐
│ 🐛 P1 BUG-1234           3d       │  ← Line 1: Type, Priority, ID, Age
│ Fix authentication timeout         │  ← Line 2: Title (truncated)
│ 👤alice  ⛔3  →2  🏷️2             │  ← Line 3: Assignee, Blockers, Blocks, Labels
│ auth, backend, critical            │  ← Line 4: Label names
└────────────────────────────────────┘

Each column header shows aggregate statistics:

┌─────────────────────────────────────┐
│  IN PROGRESS (5)  🔥2 ⚠️1          │
└─────────────────────────────────────┘
         │          │   │
         │          │   └── ⚠️ Blocked items in this column
         │          └────── 🔥 P0/P1 critical items
         └───────────────── Total count

Press d to expand the selected card inline, showing:

• Full issue description
• All blocking dependencies (with titles)
• All downstream dependents
• Complete label list
• Comments preview

Navigation (j/k) auto-collapses expanded cards for smooth browsing.

Press Tab to open a side panel with the full issue detail view (on wide terminals). Scroll with Ctrl+J/Ctrl+K.

Press s to cycle through five distinct sort modes, giving you instant control over how issues are organized. The current sort mode is displayed in the status bar.

The sort system uses a stable secondary sort to ensure deterministic ordering. When primary sort values are equal, issues fall back to ID ordering for consistency across sessions. This prevents the "shuffling list" problem where equal-priority items randomly reorder.

┌────────────────────────────────────────────────────────────┐
│  📋 ISSUES                                    [Created ↓]  │
├────────────────────────────────────────────────────────────┤
│  OPEN   FEAT-789  Add dark mode toggle           P2  🟢   │
│  OPEN   BUG-456   Fix login race condition       P1  🟢   │
│  OPEN   TASK-123  Update documentation           P3  🟢   │
└────────────────────────────────────────────────────────────┘

The [Created ↓] badge instantly communicates the active sort mode without requiring you to remember which mode you're in.

Press E to open the Hierarchical Tree View—a collapsible tree that visualizes parent-child relationships between issues. Unlike the Graph View which shows all dependency types, the Tree View focuses exclusively on structural hierarchy: which issues are "part of" other issues.

In complex projects, issues often have two distinct relationship types:

• Blocking dependencies (blocks/blocked_by): Task B cannot start until Task A completes
• Parent-child relationships (parent): Feature X contains Tasks A, B, and C as sub-work

The Tree View renders only parent-child relationships, creating a work breakdown structure (WBS) that answers questions like:

• "What sub-tasks make up this epic?"
• "Which feature does this bug belong to?"
• "How is work decomposed across the project?"

┌─────────────────────────────────────────────────────────────────────────────┐
│  🌲 TREE VIEW                                           3 roots · 12 nodes  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ▾ 🎯 P1 EPIC-100   Auth System Overhaul                        ● open     │
│  │ ├─ ▸ ✨ P1 FEAT-101   Implement OAuth2 flow                  ● open     │
│  │ │   └─ • 📝 P2 TASK-102   Add token refresh logic            ○ closed   │
│  │ └─ • 🐛 P0 BUG-103   Fix session timeout race               ⚠ blocked  │
│  │                                                                          │
│  ▾ 🎯 P2 EPIC-200   UI Polish Sprint                            ● open     │
│  │ ├─ • ✨ P2 FEAT-201   Dark mode support                      ● open     │
│  │ └─ • ✨ P3 FEAT-202   Responsive layout                      ● open     │
│  │                                                                          │
│  • 📝 P3 TASK-300   Update documentation                        ● open     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

The tree construction uses a parent-child only filter with intelligent root detection:

1. Filter Dependencies: Only DepParentChild type dependencies are considered; blocking and related dependencies are ignored
2. Build Index: Create a parent → children mapping for efficient traversal
3. Identify Roots: Issues with no parent (or whose parent doesn't exist in the dataset) become root nodes
4. Recursive Build: Depth-first traversal with cycle detection prevents infinite loops
5. Sort Children: Within each parent, children are sorted by: Priority (ascending) → Type (epic > feature > bug > task) → Creation Date (newest first)

Handling Edge Cases:

• Orphan References: If an issue references a parent that doesn't exist, it becomes a root node (not silently dropped)
• Cycles: Detected during traversal; cyclic nodes are rendered without recursing further
• Deep Hierarchies: No depth limit—the tree faithfully represents arbitrarily nested structures

Both views complement each other: use Tree View to understand structure, Graph View to understand flow.

Press a to open the Actionable Plan View—a structured display of work items grouped into independent execution tracks. This view transforms abstract graph analysis into a concrete "what to work on next" interface.

Traditional priority lists show tasks in a single ordered queue. But in complex dependency graphs, some work streams are completely independent—working on one doesn't affect another. The Actionable Plan View identifies these parallel tracks using Union-Find connected component analysis, letting multiple agents or team members work concurrently without stepping on each other.

┌─────────────────────────────────────────────────────────────────────────────┐
│  🎯 ACTIONABLE PLAN                                      3 tracks · 8 items  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ━━━ Track A: Auth System ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                             │
│  ▸ 🎯 P1 AUTH-001   Implement OAuth2 flow                    unblocks 3    │
│    ✨ P2 AUTH-002   Add token refresh                        unblocks 1    │
│                                                                             │
│  ━━━ Track B: UI Polish ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                             │
│    📝 P2 UI-101     Dark mode toggle                         unblocks 2    │
│    📝 P3 UI-102     Responsive layout                        unblocks 0    │
│                                                                             │
│  ━━━ Track C: Independent ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                             │
│    📝 P3 DOCS-001   Update API documentation                 unblocks 0    │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  Highest Impact: AUTH-001 (unblocks 3)                                      │
└─────────────────────────────────────────────────────────────────────────────┘

An issue appears in the Actionable Plan when:

1. Status is open or in_progress (not closed)
2. No open blockers exist (all blocking dependencies are closed)

This ensures every item in the view can be started immediately without waiting on anything else.

Each item shows an unblocks count—the number of other issues that would become actionable if this item were completed. High unblock counts indicate force multipliers: completing them unlocks a cascade of downstream work.

The Highest Impact summary at the bottom identifies the single item that, when completed, unblocks the most additional work. This is your optimal "next thing to pick up."

Press f to open the Flow Matrix View—an interactive dashboard visualizing how labels (domains/teams) depend on each other. This reveals cross-team bottlenecks that aren't visible in single-issue views.

In large projects, work is often organized by labels: frontend, backend, api, auth, infra. Dependencies between issues create implicit dependencies between labels. The Flow Matrix exposes these patterns:

• Which team is blocking others the most?
• Which domain is waiting on the most external work?
• Where are the cross-team coordination bottlenecks?

┌─────────────────────────────────────────────────────────────────────────────┐
│  🔀 FLOW MATRIX                                             5 labels · 23 deps │
├───────────────────────────────────────────┬─────────────────────────────────┤
│  LABELS                                   │  DETAIL                          │
│  ─────────────────────────────────────    │  ─────────────────────────────   │
│                                           │                                  │
│  ▸ 🔴 api      ━━━━━━━━━━ 0.72           │  Label: api                      │
│       outgoing: 8 → [auth, db, infra]    │  ──────────────────────          │
│       incoming: 3 ← [frontend, mobile]   │                                  │
│                                           │  Bottleneck Score: 0.72         │
│    🟡 auth     ━━━━━━━━   0.58           │  (top 20% = critical)            │
│       outgoing: 4 → [db]                 │                                  │
│       incoming: 5 ← [api, frontend]      │  Outgoing Dependencies:          │
│                                           │    → auth (3 issues)             │
│    🟢 frontend ━━━━━     0.31            │    → db (4 issues)               │
│       outgoing: 2 → [api]                │    → infra (1 issue)             │
│       incoming: 0                        │                                  │
│                                           │  Incoming Dependencies:          │
│    🟢 db       ━━━       0.22            │    ← frontend (2 issues)         │
│       outgoing: 0                        │    ← mobile (1 issue)            │
│       incoming: 7 ← [api, auth]          │                                  │
│                                           │  Critical Path: YES              │
└───────────────────────────────────────────┴─────────────────────────────────┘

The bottleneck score (0.0–1.0) measures how much a label blocks cross-domain work:

$$ \text{Bottleneck} = \frac{\text{Outgoing Deps}}{\text{Total Cross-Label Deps}} \times \text{Criticality Weight} $$

Press Enter on a label to drill down into the specific issues creating cross-label dependencies:

┌─────────────────────────────────────────────────────────────────────────────┐
│  🔀 FLOW MATRIX > api → auth                                    3 issues    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│    🐛 P1 API-123   Auth endpoint returns 500         blocks AUTH-456       │
│    ✨ P2 API-456   Add OAuth scope validation        blocks AUTH-789       │
│    📝 P2 API-789   Token refresh rate limiting       blocks AUTH-101       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

bv --robot-label-flow | jq '.flow.bottleneck_labels'

Press ] to open the Attention View—a ranked table of labels by attention score, helping you identify which project areas need focus.

The attention score combines multiple signals to surface neglected or problematic areas:

$$ \text{Attention} = \frac{\text{PageRank}_{\text{avg}} \times \text{Staleness} \times \text{BlockImpact}}{\text{Velocity} + \epsilon} $$

High attention scores indicate labels that are both important and neglected—they need intervention.

┌─────────────────────────────────────────────────────────────────────────────┐
│  🎪 ATTENTION VIEW                                                          │
├──────┬────────────┬───────────┬─────────────────────────────────────────────┤
│ Rank │ Label      │ Attention │ Reason                                      │
├──────┼────────────┼───────────┼─────────────────────────────────────────────┤
│  1   │ api        │    2.45   │ blocked=5 stale=3 vel=0.8                   │
│  2   │ auth       │    1.89   │ blocked=2 stale=4 vel=1.2                   │
│  3   │ infra      │    1.23   │ blocked=1 stale=6 vel=0.5                   │
│  4   │ frontend   │    0.67   │ blocked=0 stale=1 vel=3.5                   │
│  5   │ docs       │    0.34   │ blocked=0 stale=2 vel=2.1                   │
└──────┴────────────┴───────────┴─────────────────────────────────────────────┘

• High Attention + Low Velocity: Area is stuck—investigate blockers
• High Attention + High Stale: Work forgotten—resurface and reprioritize
• Low Attention + High Velocity: Healthy area—keep momentum
• High Blocked Count: Dependencies creating bottleneck

bv --robot-label-attention --attention-limit=10

Press ; (semicolon) or F2 to toggle the Shortcuts Sidebar—a persistent panel showing context-aware keyboard shortcuts alongside your current view.

The ? help overlay shows shortcuts but blocks your view. The shortcuts sidebar stays visible while you work, perfect for:

• Learning keyboard shortcuts without interrupting your flow
• Quick reference during complex navigation
• Teaching new users while pair programming

The sidebar automatically filters shortcuts to show only those relevant to your current view:

┌──────────────────────────────────────────────┬──────────────────────┐
│                                              │  ⌨️ SHORTCUTS         │
│                                              │  ──────────────────  │
│               Main Content Area              │                      │
│                                              │  Navigation          │
│           (List, Board, Graph, etc.)         │  j/k    Move ↓/↑     │
│                                              │  G/gg   End/Start    │
│                                              │  ^d/^u  Page ↓/↑     │
│                                              │                      │
│                                              │  Views               │
│                                              │  b      Board        │
│                                              │  g      Graph        │
│                                              │  i      Insights     │
│                                              │                      │
│                                              │  ; to hide           │
└──────────────────────────────────────────────┴──────────────────────┘

The sidebar occupies a fixed 34-character width on the right edge of the terminal.

Press ` (backtick) to open the Interactive Tutorial—a comprehensive multi-page walkthrough that teaches all bv features through rich, styled content.

The tutorial uses a component-based rendering system that produces beautiful terminal output:

The tutorial covers these topics in depth:

1. Introduction — What bv is and why it exists
2. Core Concepts — Beads, dependencies, labels, priorities
3. List View — Navigation, filtering, sorting
4. Board View — Kanban workflows, swimlanes
5. Graph View — Dependency visualization
6. Tree View — Parent-child hierarchies
7. Insights Dashboard — Graph metrics deep dive
8. History View — Git correlation
9. Robot Protocol — AI agent integration
10. Workflows — Triage, planning, sprint management

The tutorial automatically tracks which pages you've viewed:

┌─────────────────────────────────────────────────────────────────────────────┐
│  📖 TUTORIAL                                           Page 3/10 · 30% ████░░░░│
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ## List View Navigation                                                    │
│  ─────────────────────────                                                  │
│                                                                             │
│  The list view is your home base. Navigate with vim-style keys:             │
│                                                                             │
│    j / k       Move down / up                                               │
│    g / G       Jump to top / bottom                                         │
│    Ctrl+D/U    Page down / up                                               │
│                                                                             │
│  ╭──────────────────────────────────────────────────────────────────────╮   │
│  │ 💡 TIP  Press `/` to search, then type any part of an issue title   │   │
│  ╰──────────────────────────────────────────────────────────────────────╯   │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  ← h previous │ l next → │ t TOC │ q close                                  │
└─────────────────────────────────────────────────────────────────────────────┘

Progress persists across sessions, so you can close bv and resume where you left off.

When you open the tutorial from a specific view (e.g., press ` while in Board view), the tutorial can filter to show only pages relevant to that context. This provides focused learning without overwhelming new users.

bv provides two help levels:

From Quick Reference, press Space to jump directly into the full tutorial.

Press h to open the History View—an interactive timeline that correlates beads with their related git commits. This bridges the gap between "what work was planned" and "what code was actually written."

The pkg/correlation package implements a multi-strategy correlation system that infers relationships between beads and commits using several techniques:

graph TD
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    subgraph strategies ["🔍 Correlation Strategies"]
        E["Explicit Mentions<br/><small>Commit contains bead ID</small>"]
        T["Temporal Proximity<br/><small>Commit near bead events</small>"]
        C["Co-Commit Analysis<br/><small>Files changed together</small>"]
        P["Path Matching<br/><small>File paths match bead scope</small>"]
    end

    subgraph scorer ["📊 Confidence Scorer"]
        S["Multi-Factor Scoring<br/><small>Weighted combination</small>"]
    end

    subgraph output ["📈 Output"]
        H["BeadHistory<br/><small>Events + Commits + Milestones</small>"]
    end

    E --> S
    T --> S
    C --> S
    P --> S
    S --> H

    classDef strategy fill:#e3f2fd,stroke:#90caf9,stroke-width:2px,color:#1565c0
    classDef score fill:#fff8e1,stroke:#ffcc80,stroke-width:2px,color:#e65100
    classDef out fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px,color:#2e7d32

    class E,T,C,P strategy
    class S score
    class H out

Each correlation receives a confidence score (0.0–1.0) computed by:

$$ \text{Confidence} = w_1 \cdot \text{Explicit} + w_2 \cdot \text{Temporal} + w_3 \cdot \text{CoCommit} + w_4 \cdot \text{Path} $$

Default weights: Explicit=0.5, Temporal=0.25, CoCommit=0.15, Path=0.10

The History View uses a responsive three-pane layout that adapts to terminal width:

Wide Terminal (3-pane) Layout:

┌─────────────────────────────────────────────────────────────────────────────────┐
│  📜 HISTORY VIEW                                          [Bead Mode] [≥ 0.5]   │
├───────────────────────┬───────────────────┬─────────────────────────────────────┤
│  BEADS                │  TIMELINE         │  COMMIT DETAIL                      │
│  ─────────────────    │  ─────────────    │  ─────────────────────────          │
│ ▸ BV-123 (3 commits)  │    ┃              │  abc1234 - Fix auth race            │
│   🎯 BV-456 (1)       │   ━╋━ Jan 15      │  Author: [email protected]          │
│   🔗 BV-789 (5)       │    ┃   ▪▪▪        │  Date:   2025-01-15 14:32           │
│   📁 BV-100 (2)       │   ━╋━ Jan 14      │  Confidence: 0.85 (explicit)        │
│                       │    ┃   ▪          │                                      │
│                       │   ━╋━ Jan 13      │  Files changed:                      │
│                       │    ┃   ▪▪▪▪▪      │    M pkg/auth/session.go            │
└───────────────────────┴───────────────────┴─────────────────────────────────────┘

Press t to show/hide the Timeline Panel—a visual density chart of project activity:

• Vertical axis: Time (newest at top)
• Horizontal bars: Activity density (commits per day)
• Bar magnitude: ▪ = 1-2, ▪▪ = 3-5, ▪▪▪ = 6-10, ▪▪▪▪ = 11+
• Highlights: Selected bead's commits are marked with ━

Click or navigate to a date to filter the view to that time period.

Each bead-commit correlation shows its detection method as a visual marker:

Press v to toggle between two view modes:

Press f to switch to File Mode—a tree view of changed files grouped by directory:

┌─────────────────────────────────────────────────────────────────────────┐
│  📁 FILE MODE                                              [12 files]   │
├─────────────────────────────────────────────────────────────────────────┤
│  ▼ pkg/auth/                                                            │
│      session.go       42 changes   BV-123, BV-456                       │
│      token.go         18 changes   BV-123                               │
│      middleware.go    8 changes    BV-789                               │
│  ▼ pkg/api/                                                             │
│      handler.go       25 changes   BV-100                               │
│      routes.go        12 changes   BV-100, BV-456                       │
└─────────────────────────────────────────────────────────────────────────┘

Navigate to a file and press Enter to see all beads and commits that touched it.

bv --robot-history                          # Full history report
bv --robot-history --bead-history BV-123    # Single bead focus
bv --robot-history --history-since '30 days ago'
bv --robot-history --min-confidence 0.7     # High-confidence only

Output Schema:

{
  "stats": {
    "total_beads": 58,
    "beads_with_commits": 42,
    "total_commits": 156,
    "avg_cycle_time_hours": 72.5,
    "method_distribution": {
      "explicit": 89,
      "temporal": 45,
      "cocommit": 22
    }
  },
  "histories": {
    "BV-123": {
      "events": [...],
      "commits": [...],
      "milestones": [...],
      "cycle_time_hours": 48.2
    }
  },
  "commit_index": {
    "abc1234": ["BV-123", "BV-456"]
  }
}

Beyond simple bead-to-commit correlation, bv provides deep analysis of how beads relate to each other through shared code changes. This helps identify hidden dependencies, find related work, and understand the true impact of changes.

The Impact Network visualizes implicit relationships between beads based on:

graph LR
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e3f2fd', 'lineColor': '#90a4ae'}}}%%

    subgraph connections ["🔗 Edge Types"]
        SC["Shared Commit<br/><small>Same commit touches both beads</small>"]
        SF["Shared File<br/><small>Both beads modify same files</small>"]
        DEP["Dependency<br/><small>Explicit blocker relationship</small>"]
    end

    classDef edge fill:#fff8e1,stroke:#ffcc80,stroke-width:2px
    class SC,SF,DEP edge

bv automatically detects clusters of tightly-connected beads using community detection:

┌─────────────────────────────────────────────────────────────────────────┐
│  🔗 IMPACT NETWORK                                        [3 clusters]  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─── Cluster 1: Auth Module ───┐     ┌─── Cluster 2: API Layer ───┐   │
│  │  BV-123 ←──→ BV-456          │     │  BV-789 ←──→ BV-100        │   │
│  │    ↕           ↕              │     │    ↕                        │   │
│  │  BV-321 ←──→ BV-654          │────→│  BV-111                     │   │
│  └──────────────────────────────┘     └─────────────────────────────┘   │
│                                                                         │
│  Central bead: BV-123 (highest degree)                                 │
│  Internal connectivity: 0.85 (tightly coupled)                         │
│  External edges: 1 (to API layer cluster)                              │
└─────────────────────────────────────────────────────────────────────────┘

Find all beads that have touched a specific file using --robot-file-beads:

bv --robot-file-beads pkg/ui/board.go

Returns beads sorted by recency with commit details:

{
  "file_path": "pkg/ui/board.go",
  "total_beads": 21,
  "open_beads": [],
  "closed_beads": [
    {
      "bead_id": "bv-v67w",
      "title": "Board: Integration & Polish",
      "status": "closed",
      "commit_shas": ["abc123"],
      "last_touch": "2025-12-18T00:19:21-05:00",
      "total_changes": 17
    }
  ]
}

Use cases:

• Code ownership: "Who has worked on this file recently?"
• Impact analysis: "What work items are affected by this file?"
• Bug investigation: "What changes might have introduced this regression?"

Find commits that should be linked to beads but aren't using --robot-orphans:

bv --robot-orphans

Returns candidate commits with probable bead matches:

{
  "stats": {
    "total_commits": 500,
    "correlated_count": 242,
    "orphan_count": 258,
    "orphan_ratio": 0.516
  },
  "candidates": [
    {
      "sha": "abc1234",
      "message": "feat: add auth caching",
      "suspicion_score": 100,
      "probable_beads": [
        {
          "bead_id": "bv-xyz",
          "confidence": 65,
          "reasons": ["touches file pkg/auth/cache.go", "same author worked on bead nearby"]
        }
      ]
    }
  ]
}

Use cases:

• Hygiene: Find commits that slipped through without proper linking
• Audit: Ensure all code changes are tracked to work items
• Correlation improvement: Train the system by confirming/rejecting suggestions

For any bead, bv can find related work across four dimensions:

Each relation includes a relevance score (0-100) indicating strength.

# Get the full impact network (use "all" for complete graph)
bv --robot-impact-network all

# Get subnetwork focused on specific bead (default depth=2, max=3)
bv --robot-impact-network bv-123 --network-depth 2

# Find related work for a bead
bv --robot-related bv-123

# Include closed beads in related work results
bv --robot-related bv-123 --related-include-closed

# Tune related work thresholds
bv --robot-related bv-123 --related-min-relevance 30 --related-max-results 20

# Analyze causal chain for a bead (timeline, blockers, insights)
bv --robot-causality bv-123

# Find beads that touched a file
bv --robot-file-beads pkg/auth/session.go

# Find orphan commits (unlinked to beads)
bv --robot-orphans

The --robot-causality command reveals why a bead took as long as it did by reconstructing its timeline of events:

Insights provided:

• Blocked percentage: How much time was spent waiting on dependencies
• Critical path: The chain of events determining minimum completion time
• Longest gap: Identifies stalled periods needing investigation
• Recommendations: Actionable suggestions (e.g., "Consider breaking into smaller beads")

Causality Output Schema:

{
  "generated_at": "2025-01-15T14:32:00Z",
  "data_hash": "abc123...",
  "chain": {
    "bead_id": "bv-123",
    "title": "Implement auth caching",
    "status": "closed",
    "events": [
      {"id": 1, "type": "created", "timestamp": "2025-01-10T10:00:00Z"},
      {"id": 2, "type": "claimed", "timestamp": "2025-01-10T11:00:00Z", "caused_by_id": 1},
      {"id": 3, "type": "blocked", "timestamp": "2025-01-11T09:00:00Z", "blocker_id": "bv-456"},
      {"id": 4, "type": "unblocked", "timestamp": "2025-01-12T16:00:00Z"},
      {"id": 5, "type": "commit", "timestamp": "2025-01-13T10:00:00Z", "commit_sha": "abc1234"},
      {"id": 6, "type": "closed", "timestamp": "2025-01-13T17:00:00Z"}
    ],
    "edge_count": 5,
    "total_time": "79h0m0s",
    "is_complete": true
  },
  "insights": {
    "total_duration": "79h0m0s",
    "blocked_duration": "31h0m0s",
    "active_duration": "48h0m0s",
    "blocked_percentage": 39.2,
    "blocked_periods": [
      {"start_time": "2025-01-11T09:00:00Z", "end_time": "2025-01-12T16:00:00Z", "blocker_id": "bv-456"}
    ],
    "commit_count": 1,
    "critical_path_desc": "created → claimed → blocked → unblocked → commit → closed",
    "summary": "Bead took 79h total; 39% blocked by bv-456",
    "recommendations": ["Consider unblocking bv-456 earlier to reduce wait time"]
  }
}

Train the correlation engine by confirming or rejecting its suggestions:

# Explain why a correlation exists
bv --robot-explain-correlation abc1234:bv-xyz

# Confirm a correct correlation (boosts confidence)
bv --robot-confirm-correlation abc1234:bv-xyz

# Reject an incorrect correlation (removes it)
bv --robot-reject-correlation abc1234:bv-xyz

# View feedback statistics
bv --robot-correlation-stats

Feedback Stats Output:

{
  "total_feedback": 15,
  "confirmed": 12,
  "rejected": 3,
  "accuracy_rate": 0.80,
  "avg_confirm_conf": 0.85,
  "avg_reject_conf": 0.42
}

This feedback loop improves correlation accuracy over time—confirmed correlations strengthen pattern recognition, while rejections help eliminate false positives.

Impact Network Output Schema:

{
  "generated_at": "2025-01-15T14:32:00Z",
  "data_hash": "abc123...",
  "stats": {
    "total_nodes": 58,
    "total_edges": 142,
    "cluster_count": 5,
    "avg_degree": 4.9,
    "density": 0.086,
    "isolated_nodes": 3
  },
  "clusters": [
    {
      "cluster_id": 1,
      "bead_ids": ["BV-123", "BV-456", "BV-321"],
      "label": "Auth Module",
      "internal_connectivity": 0.85,
      "central_bead": "BV-123",
      "shared_files": ["pkg/auth/session.go", "pkg/auth/token.go"]
    }
  ],
  "edges": [
    {"from_bead": "BV-123", "to_bead": "BV-456", "edge_type": "shared_commit", "weight": 5}
  ]
}

bv optionally integrates with cass (Claude Agent Session Store)—a tool that captures and indexes coding sessions from AI assistants like Claude. When cass is installed, bv automatically enhances its correlation capabilities with session-based insights.

graph LR
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    CASS["🤖 cass<br/><small>Session Store</small>"]
    BV["⚡ bv<br/><small>Issue Viewer</small>"]
    CORR["🔗 Enhanced<br/>Correlation"]

    CASS --> BV
    BV --> CORR

    classDef tool fill:#e3f2fd,stroke:#90caf9,stroke-width:2px
    class CASS,BV,CORR tool

Graceful Degradation: If cass is not installed, bv works normally—no errors, broken UI, or loading states. Cass features simply become unavailable.

bv automatically detects cass on startup:

Press V on any bead to open the Session Preview Modal—a view of AI coding sessions that may have contributed to that issue:

┌─────────────────────────────────────────────────────────────────────────┐
│  🤖 Related Coding Sessions for BV-123                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ▸ Session 1 (claude-opus-4)                         Dec 15, 2:30 PM   │
│    "Implementing session refresh timeout handling..."                   │
│    Confidence: 0.92 (explicit mention)                                  │
│                                                                         │
│    Session 2 (claude-opus-4)                         Dec 14, 10:15 AM  │
│    "Refactoring token validation middleware..."                         │
│    Confidence: 0.67 (file overlap)                                      │
│                                                                         │
│    Session 3 (claude-opus-4)                         Dec 13, 4:45 PM   │
│    "Adding retry logic to auth service..."                              │
│    Confidence: 0.45 (temporal)                                          │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│  j/k: Navigate   y: Copy search command   Enter: View full session      │
└─────────────────────────────────────────────────────────────────────────┘

Session Correlation Methods:

When cass is healthy, the status bar shows agent activity:

┌────────────────────────────────────────────────────────────────────────┐
│  📋 437 issues  •  🤖 claude-opus-4 (active)  •  Last: 5m ago          │
└────────────────────────────────────────────────────────────────────────┘

# Install cass (see https://github.com/Dicklesworthstone/cass for full docs)
brew install dicklesworthstone/tap/cass   # macOS
# or
cargo install cass                         # From source

# Index your coding sessions
cass index

# Verify integration
bv  # Look for 🤖 in status bar

When cass is available, the History View gains additional capabilities:

• Session Timeline: V key shows sessions alongside commits
• Agent Attribution: See which AI assistant contributed to changes
• Enhanced Search: Search across both commits and sessions

Press P (uppercase) to open the Sprint Dashboard—a comprehensive view of sprint progress with burndown visualization, scope change tracking, and at-risk detection.

┌─────────────────────────────────────────────────────────────────────────┐
│  📅 Sprint: January 2025                                                │
│  ───────────────────────────────────────────────────────────────────    │
│  Dates:     Jan 6 → Jan 20                                              │
│  Remaining: 5 days                                                      │
│                                                                         │
│  ══════════════════════════════════════════════════════════════════    │
│                          PROGRESS                                       │
│  ══════════════════════════════════════════════════════════════════    │
│                                                                         │
│  Total: 24 beads    Closed: 18 (75%)    Remaining: 6                    │
│  [████████████████████░░░░░░] 75%                                       │
│                                                                         │
│  ══════════════════════════════════════════════════════════════════    │
│                          BURNDOWN                                       │
│  ══════════════════════════════════════════════════════════════════    │
│                                                                         │
│  24 ┤ ·                                                                 │
│  20 ┤  ·····                                                            │
│  16 ┤       ····▸                                                       │
│  12 ┤            ╲    (ideal)                                           │
│   8 ┤             ╲                                                     │
│   4 ┤              ╲                                                    │
│   0 ┼──────────────────────────────────────────────────────────────    │
│     Jan 6          Jan 13                Jan 20                         │
│                                                                         │
│  Legend: · = Actual    ╲ = Ideal    ▸ = Today                           │
│                                                                         │
│  ══════════════════════════════════════════════════════════════════    │
│                       SCOPE CHANGES                                     │
│  ══════════════════════════════════════════════════════════════════    │
│                                                                         │
│  Jan 8:  +2 beads added (BV-456, BV-457)                                │
│  Jan 10: -1 bead removed (BV-100 moved to backlog)                      │
│                                                                         │
│  ══════════════════════════════════════════════════════════════════    │
│                        AT-RISK ITEMS                                    │
│  ══════════════════════════════════════════════════════════════════    │
│                                                                         │
│  ⚠ BV-789 (P0 Critical) - Blocked for 3 days                           │
│  ⚠ BV-234 (P1 High) - No activity for 5 days                           │
└─────────────────────────────────────────────────────────────────────────┘

The burndown chart implements a scope-aware algorithm that tracks not just completion velocity but also scope changes:

1. Ideal Burn Rate: Total Beads / Sprint Duration
2. Actual Burn Rate: Closed Beads / Days Elapsed
3. Scope Events: Added/removed beads create discontinuities in the ideal line

When beads are added mid-sprint, the burndown recalculates the ideal trajectory from that point forward, providing a realistic view of progress rather than a misleading "behind schedule" indicator.

Items are flagged as at-risk based on multiple heuristics:

bv --robot-sprint-list                # List all sprints
bv --robot-sprint-show sprint-1       # Details for specific sprint
bv --robot-burndown current           # Burndown for active sprint
bv --robot-burndown sprint-1          # Burndown for specific sprint

Burndown Output:

{
  "sprint_id": "sprint-1",
  "total_days": 14,
  "elapsed_days": 9,
  "remaining_days": 5,
  "total_issues": 24,
  "completed_issues": 18,
  "remaining_issues": 6,
  "ideal_burn_rate": 1.71,
  "actual_burn_rate": 2.0,
  "projected_complete": "2025-01-18",
  "on_track": true,
  "scope_changes": [
    {"date": "2025-01-08", "delta": 2, "reason": "Added BV-456, BV-457"}
  ]
}

Press L (uppercase) to open the Label Dashboard—a table view showing health metrics for each label in your project. This enables domain-driven prioritization by surfacing which areas of your codebase need attention.

┌─────────────────────────────────────────────────────────────────────────┐
│  🏷️ LABEL HEALTH                                                        │
├──────────────┬────────┬────────┬────────┬────────┬────────┬────────────┤
│  Label       │ Health │ Status │ Open   │ Blocked│ Stale  │ Velocity   │
├──────────────┼────────┼────────┼────────┼────────┼────────┼────────────┤
│  🔴 api      │  0.32  │ CRIT   │   12   │   5    │   3    │   0.8/wk   │
│  🟡 auth     │  0.58  │ WARN   │    8   │   2    │   1    │   2.1/wk   │
│  🟢 ui       │  0.85  │ OK     │    4   │   0    │   0    │   4.2/wk   │
│  🟢 docs     │  0.92  │ OK     │    2   │   0    │   0    │   1.5/wk   │
│  🟡 infra    │  0.61  │ WARN   │    6   │   1    │   2    │   1.2/wk   │
└──────────────┴────────┴────────┴────────┴────────┴────────┴────────────┘

The label health score combines multiple factors:

$$ \text{Health} = 1 - \left( w_1 \cdot \frac{\text{Blocked}}{\text{Open}} + w_2 \cdot \frac{\text{Stale}}{\text{Open}} + w_3 \cdot (1 - \text{VelocityScore}) \right) $$

--robot-label-health: Per-label health metrics

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

--robot-label-flow: Cross-label dependency flow matrix

bv --robot-label-flow
bv --robot-label-flow | jq '.flow.bottleneck_labels'

--robot-label-attention: Attention-ranked labels for prioritization

bv --robot-label-attention --attention-limit=5

Use --label to scope any robot command to a specific label's subgraph:

bv --robot-insights --label api    # Graph metrics for api-labeled issues only
bv --robot-plan --label backend    # Execution plan for backend domain
bv --robot-priority --label auth   # Priority recommendations for auth work

This enables domain isolation: analyze and plan within a bounded context rather than the entire project graph.

The flow matrix reveals how labels depend on each other:

          → api  → auth  → ui   → docs
api         -      3       2      0
auth        1      -       0      1
ui          4      2       -      0
docs        0      0       0      -

Read as: "api has 3 issues that depend on auth issues." High values indicate coupling between domains; the bottleneck_labels field highlights labels that block the most cross-domain work.

bv can generate self-contained static websites for sharing project status with stakeholders who don't have terminal access.

bv --pages

Launches an interactive wizard that guides you through:

1. Export: Generate the static bundle
2. Preview: Local server at http://localhost:9000 (or next available port)
3. Deploy: Push to GitHub Pages with automatic repository creation

bv --export-pages ./bv-pages                    # Export to directory
bv --export-pages ./bv-pages --pages-title "Sprint 42 Status"
bv --export-pages ./bv-pages --pages-exclude-closed   # Omit closed issues
bv --export-pages ./bv-pages --pages-exclude-history  # Omit git history

# Preview an existing bundle without regenerating
bv --preview-pages ./bv-pages                   # Serve at localhost:9000 (or next available port)

For very large datasets, you can build an optional WASM scorer used by the static viewer.

# Build once (requires wasm-pack)
./scripts/build_hybrid_wasm.sh

# Or build during export
BV_BUILD_HYBRID_WASM=1 bv --export-pages ./bv-pages

If the wasm/ assets are missing, the viewer automatically falls back to the JS scorer.

./bv-pages/
├── index.html              # Main dashboard with Alpine.js + Tailwind
├── beads.sqlite3           # Full SQLite database (~2MB for 400+ issues)
├── data/
│   ├── graph_layout.json   # Pre-computed positions + metrics (~82KB)
│   ├── meta.json           # Export metadata
│   ├── triage.json         # Triage recommendations
│   └── history.json        # Bead-commit correlation data
└── vendor/
    ├── d3.v7.min.js        # Visualization library
    ├── force-graph.min.js  # Graph rendering
    └── bv_graph.js         # WASM graph engine

The export uses a hybrid architecture for instant graph loading:

How it works:

1. Browser loads tiny graph_layout.json first (~100ms over broadband)
2. Graph renders instantly with pre-computed fx/fy fixed positions
3. SQLite loads in parallel for search and detail functionality
4. Force simulation is completely bypassed—no jittering, no layout delay

Performance comparison:

Click any node to open a 400px sliding detail pane:

┌─────────────────────────────────────────────────────────────────────┐
│                              │ ╭─────────────────────────╮          │
│                              │ │ BV-123: Auth refactor   │          │
│       [Interactive Graph]    │ │ ─────────────────────── │          │
│                              │ │ Priority: P1 (High)     │          │
│             ⬤               │ │ Type: Feature           │          │
│            /│\               │ │ Status: In Progress     │          │
│           / │ \              │ │                         │          │
│          ⬤  ⬤  ⬤           │ │ **Description**         │          │
│                              │ │ Refactor auth module... │          │
│                              │ │                         │          │
│                              │ │ ⛔ 3 blockers           │          │
│                              │ │ 📤 blocks 5 issues      │          │
│                              │ ╰─────────────────────────╯          │
└─────────────────────────────────────────────────────────────────────┘

Detail pane includes:

• Full issue title and description (markdown rendered)
• Priority, type, status with visual indicators
• Blockers count ("⛔ 3 blockers")—issues that must complete first
• Blocks count ("📤 blocks 5 issues")—downstream work waiting on this
• PageRank, betweenness metrics (from pre-computed data)

• Full-Text Search: SQLite FTS5 powers instant search across all issue titles and descriptions. Results appear as you type—no server required.
• Interactive Graph: Visualize dependencies with D3.js force-graph, featuring zoom, pan, and node selection
• Detail Pane: Click any node to see full issue details with dependency info
• Triage View: Same recommendations as --robot-triage
• Offline Support: Works without network after initial load
• Mobile Responsive: Adapts to phone/tablet screens with touch-friendly interactions

The static export uses a hybrid architecture combining:

1. Pure-Go SQLite (modernc.org/sqlite):

   • No C compiler required—works on any system without CGO
   • Cross-platform bundle generation
   • FTS5 full-text search built-in

2. Pre-computed Graph Layout:

   • BFS hierarchical layout with depth-based X positioning
   • Node positions stored as [x, y] pairs
   • Metrics stored as compact 5-element arrays: [pagerank, betweenness, inDegree, outDegree, inCycle]
   • ~91% size reduction vs. full graph JSON

3. WASM Graph Engine (bv_graph.js):

   • Client-side cycle detection
   • Efficient neighbor lookups
   • Path finding for blocker chains

The Alerts System surfaces potential problems before they become blockers. It combines drift detection (changes from baseline) with proactive analysis (pattern-based warnings).

Press ! to open the Alerts Panel:

┌─────────────────────────────────────────────────────────────┐
│  🚨 ALERTS (3 active)                               [!] close │
├─────────────────────────────────────────────────────────────┤
│  ⚠️  WARNING: bv-123 stale for 45 days                       │
│  🔴 CRITICAL: bv-456 blocks 8 tasks (cascade risk)           │
│  ℹ️  INFO: Open issues increased 23% this sprint             │
├─────────────────────────────────────────────────────────────┤
│  j/k navigate • Enter jump to issue • d dismiss • q close   │
└─────────────────────────────────────────────────────────────┘

# Get all alerts as JSON
bv --robot-alerts

# Filter by severity (info, warning, critical)
bv --robot-alerts --severity=critical

# Filter by type
bv --robot-alerts --alert-type=blocking_cascade

# Filter by affected label
bv --robot-alerts --alert-label=backend

{
  "alerts": [
    {
      "type": "blocking_cascade",
      "severity": "critical",
      "issue_id": "bv-456",
      "message": "Blocks 8 downstream tasks",
      "blocked_ids": ["bv-101", "bv-102", "..."],
      "suggested_action": "Prioritize completion or break into smaller tasks"
    }
  ],
  "summary": {
    "total": 3,
    "critical": 1,
    "warning": 1,
    "info": 1
  }
}

Beyond the interactive TUI, bv provides a comprehensive command-line interface for scripting, automation, and AI agent integration.

bv                      # Launch interactive TUI
bv --help               # Show all options
bv --version            # Show version

These commands output structured JSON designed for programmatic consumption:

All robot commands support --as-of <ref> for historical analysis. Output includes as_of and as_of_commit metadata fields when specified.

The --as-of flag lets you view project state at any historical point without modifying your working tree. It works with both the interactive TUI and all robot commands.

# View historical state (TUI)
bv --as-of HEAD~10              # 10 commits ago
bv --as-of v1.0.0               # At release tag
bv --as-of 2024-01-15           # At specific date
bv --as-of main@{2024-01-15}    # Branch at date

# Historical analysis with robot commands
bv --robot-insights --as-of HEAD~30    # Graph metrics from 30 commits ago
bv --robot-plan --as-of v1.0.0         # Execution plan at release
bv --robot-triage --as-of 2024-06-01   # Full triage from specific date
bv --robot-priority --as-of HEAD~5     # Priority recs from 5 commits ago

# Compare changes
bv --diff-since HEAD~5          # Changes in last 5 commits
bv --diff-since v1.0.0          # Changes since release
bv --diff-since 2024-01-01      # Changes since date

# JSON diff output (combines --as-of for "to" snapshot)
bv --diff-since HEAD~10 --robot-diff                # From HEAD~10 to current
bv --diff-since HEAD~10 --as-of HEAD~5 --robot-diff # From HEAD~10 to HEAD~5

When using --as-of with robot commands, the JSON output includes additional metadata:

• as_of: The ref you specified (e.g., "HEAD~30", "v1.0.0")
• as_of_commit: The resolved commit SHA for reproducibility

# List available recipes
bv --robot-recipes

# Apply built-in recipes
bv --recipe actionable          # Ready to work
bv --recipe high-impact         # Top PageRank scores
bv --recipe stale               # Untouched 30+ days
bv --recipe blocked             # Waiting on dependencies
bv -r recent                    # Short flag, updated in 7 days

# Apply custom recipe
bv --recipe .beads/recipes/sprint.yaml

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

# Export priority brief (focused summary)
bv --priority-brief brief.md

# Export complete agent brief bundle
bv --agent-brief ./agent-bundle/
# Creates: triage.json, insights.json, brief.md, helpers.md

# Forecast completion ETA for a specific issue
bv --robot-forecast bv-123

# Forecast all open issues with filtering
bv --robot-forecast all --forecast-label=backend
bv --robot-forecast all --forecast-sprint=sprint-1
bv --robot-forecast all --forecast-agents=2     # Multi-agent parallelism

# Capacity simulation: when will everything be done?
bv --robot-capacity                              # Default: 1 agent
bv --robot-capacity --agents=3                   # 3 parallel agents
bv --robot-capacity --capacity-label=frontend    # Scoped to label

# Get all alerts (drift warnings + proactive health checks)
bv --robot-alerts

# Filter by severity
bv --robot-alerts --severity=critical
bv --robot-alerts --severity=warning

# Filter by alert type
bv --robot-alerts --alert-type=stale_issue
bv --robot-alerts --alert-type=blocking_cascade

# Filter by label scope
bv --robot-alerts --alert-label=backend

# Group recommendations by execution track (parallel work streams)
bv --robot-triage --robot-triage-by-track

# Group recommendations by label (domain-focused agents)
bv --robot-triage --robot-triage-by-label

Generate executable shell scripts from recommendations for automated workflows:

# Emit bash script for top 5 recommendations
bv --robot-triage --emit-script --script-limit=5

# Different shell formats
bv --robot-triage --emit-script --script-format=fish
bv --robot-triage --emit-script --script-format=zsh

The feedback system learns from your accept/ignore decisions to tune recommendation weights:

# Record positive feedback (you worked on this recommendation)
bv --feedback-accept bv-123

# Record negative feedback (you skipped this recommendation)
bv --feedback-ignore bv-456

# View current feedback state and weight adjustments
bv --feedback-show

# Reset feedback to defaults
bv --feedback-reset

# Save current state as baseline
bv --save-baseline "Pre-release v2.0"

# Show baseline information
bv --baseline-info

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

# Semantic vector search over titles/descriptions
bv --search "login oauth"

# JSON output for automation
bv --search "login oauth" --robot-search

# Hybrid search (text + graph metrics)
bv --search "login oauth" --search-mode hybrid --search-preset impact-first

# Hybrid with 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}'

Semantic search builds a lightweight vector index from a weighted issue document (ID and title repeated, labels and description included). This keeps lookup fast while still behaving like a human-readable search.

Hybrid mode is a two-stage pipeline: it first retrieves the top candidates by semantic similarity, then re-ranks those candidates using graph-aware signals (PageRank, status, impact, priority, recency). That keeps results anchored to your query while surfacing items that matter most in the dependency graph—a good fit for bv’s goal of making the “why this matters” visible.

Short, intent-heavy queries (e.g., “benchmarks”, “oauth”) are treated differently on purpose. bv widens the candidate pool, boosts literal matches, and raises the text weight so quick lookups behave like a precise search. Longer, descriptive queries lean more on graph signals for smart tie‑breaking and prioritization.

Hybrid defaults can be set via:

• BV_SEARCH_MODE (text|hybrid)
• BV_SEARCH_PRESET (default|bug-hunting|sprint-planning|impact-first|text-only)
• BV_SEARCH_WEIGHTS (JSON string, overrides preset)

In --robot-search JSON, hybrid results include mode, preset, weights, plus per-result text_score and component_scores.

#!/bin/bash
# agent-workflow.sh - Autonomous task selection

# 1. Get the execution plan
PLAN=$(bv --robot-plan)

# 2. Extract highest-impact actionable task
TASK=$(echo "$PLAN" | jq -r '.plan.summary.highest_impact')

# 3. Get full insights for context
INSIGHTS=$(bv --robot-insights)

# 4. Check if completing this introduces regressions
BASELINE=$(bv --diff-since HEAD~1 --robot-diff)

echo "Working on: $TASK"
echo "Unblocks: $(echo "$PLAN" | jq '.plan.summary.unblocks_count') tasks"

--robot-priority Output:

{
  "generated_at": "2025-01-15T10:30:00Z",
  "recommendations": [
    {
      "issue_id": "CORE-123",
      "current_priority": 3,
      "suggested_priority": 1,
      "confidence": 0.87,
      "direction": "increase",
      "reasoning": "High PageRank (0.15) + High Betweenness (0.45) indicates foundational blocker"
    }
  ],
  "summary": {
    "total_issues": 58,
    "recommendations": 12,
    "high_confidence": 5
  }
}

--robot-recipes Output:

{
  "recipes": [
    { "name": "actionable", "description": "Ready to work (no blockers)", "source": "builtin" },
    { "name": "high-impact", "description": "Top PageRank scores", "source": "builtin" },
    { "name": "sprint-review", "description": "Current sprint issues", "source": "project" }
  ]
}

For monorepo and multi-package architectures, bv provides workspace configuration that unifies issues across multiple repositories into a single coherent view.

# .bv/workspace.yaml - Multi-repo workspace definition
name: my-workspace

repos:
  - name: api
    path: services/api
    prefix: "api-"        # Issues become api-AUTH-123
    beads_path: .beads    # Optional per-repo override (defaults to .beads)

  - name: web
    path: apps/web
    prefix: "web-"        # Issues become web-UI-456

  - name: shared
    path: packages/shared
    prefix: "lib-"        # Issues become lib-UTIL-789

discovery:
  enabled: true
  patterns:
    - "*"                 # Direct children
    - "packages/*"        # npm/pnpm workspaces
    - "apps/*"            # Next.js/Turborepo
    - "services/*"        # Microservices
    - "libs/*"            # Library packages
  exclude:
    - node_modules
    - vendor
    - .git
  max_depth: 2

defaults:
  beads_path: .beads      # Where to find beads.jsonl in each repo

When working across repositories, issues are automatically namespaced:

The workspace system enables cross-repo blocking relationships:

┌─────────────────────────────────────────────────────────┐
│  web-UI-456 (apps/web)                                  │
│  "Implement OAuth login page"                           │
│                                                         │
│  blocks: api-AUTH-123, lib-UTIL-789                     │
└─────────────────────────────────────────────────────────┘
         │                      │
         ▼                      ▼
┌─────────────────┐    ┌─────────────────┐
│ api-AUTH-123    │    │ lib-UTIL-789    │
│ (services/api)  │    │ (packages/lib)  │
│ "Auth endpoint" │    │ "Token utils"   │
└─────────────────┘    └─────────────────┘

Use --repo to scope the view (and robot outputs) to a specific repository prefix. Matching is case-insensitive and accepts common separators (-, :, _); it also honors the source_repo field when present.

The IDResolver handles cross-repo references intelligently:

resolver := NewIDResolver(config, "api")

// From api repo context:
resolver.Resolve("AUTH-123")      // → {Namespace: "api-", LocalID: "AUTH-123"}
resolver.Resolve("web-UI-456")    // → {Namespace: "web-", LocalID: "UI-456"}
resolver.IsCrossRepo("web-UI-456") // → true
resolver.DisplayID("api-AUTH-123") // → "AUTH-123" (local, strip prefix)
resolver.DisplayID("web-UI-456")   // → "web-UI-456" (cross-repo, keep prefix)

Beyond CLI diff commands, bv supports interactive time-travel within the TUI itself. This mode overlays diff badges on your issue list, letting you visually explore what changed.

Press t in the main list view to enter time-travel mode with a custom revision prompt:

┌──────────────────────────────────────────┐
│  ⏱️  Time-Travel Mode                    │
│                                          │
│  Compare current state with a            │
│  historical revision                     │
│                                          │
│  ⏱️  Revision: HEAD~5█                   │
│                                          │
│  Examples: HEAD~5, main, v1.0.0,         │
│           2024-01-01, abc123             │
│                                          │
│  Press Enter to compare, Esc to cancel   │
└──────────────────────────────────────────┘

For quick access, press T (uppercase) to instantly compare against HEAD~5 without the prompt.

Once activated, issues display visual badges indicating their diff status:

┌────────────────────────────────────────────────────────────┐
│  📋 ISSUES (since HEAD~5)                          58 total │
├────────────────────────────────────────────────────────────┤
│  [NEW]      ✨ FEAT-789  Add dark mode toggle      P2  🟢  │
│  [NEW]      🐛 BUG-456   Fix login race condition  P1  🟢  │
│  [MODIFIED] 📝 TASK-123  Update documentation     P3  🟡  │
│             ✨ FEAT-100  OAuth integration        P1  🟢  │
│  [CLOSED]   🐛 BUG-001   Memory leak in parser    P0  ⚫  │
└────────────────────────────────────────────────────────────┘

The footer shows aggregate statistics:

─────────────────────────────────────────────────────────────
📊 Changes: +3 new  ✓2 closed  ~1 modified  ↺0 reopened
Health: ↑ improving (density: -0.02, cycles: -1)
─────────────────────────────────────────────────────────────

Trust is earned. bv employs a rigorous testing strategy to ensure it can handle the messy reality of real-world repositories.

We don't just test on "happy path" data. The test suite (pkg/loader/synthetic_test.go) generates Synthetic Complex Graphs—large JSONL files with thousands of nodes, intricate dependency cycles, and edge-case UTF-8 characters—to verify that the graph engine and rendering logic never panic under load.

In a git-based workflow, merge conflicts and partial writes happen. The TestLoadIssuesRobustness suite explicitly injects garbage lines and corrupted JSON into the data stream.

• Result: bv detects corruption, logs a warning to stderr, and continues loading the valid data. It never crashes the user session due to a single bad line.

For contributors writing tests, see the comprehensive Testing Guide which covers:

• Test philosophy (no mocks, table-driven tests, golden files)
• Using the testutil package for fixture generation
• Running tests, coverage, and benchmarks
• E2E test patterns and CI integration

bv includes a proactive, non-intrusive update check to ensure you never miss a feature. We believe tools should maintain themselves without interrupting your flow.

The updater (pkg/updater/updater.go) is architected for silence and safety:

1. Non-Blocking Concurrency: The check runs in a detached goroutine with a strict 2-second timeout. It never delays your startup time or UI interactivity.
2. Semantic Versioning: It doesn't just match strings. A custom SemVer comparator ensures you are only notified about strictly newer releases, handling complex edge cases like release candidates vs. stable builds.
3. Resilience: It gracefully handles network partitions, GitHub API rate limits (403/429), and timeouts by silently failing. You will never see a crash or error log due to an update check.
4. Unobtrusive Notification: When an update is found, bv doesn't pop a modal. It simply renders a subtle Update Available indicator (⭐) in the footer, letting you choose when to upgrade.

Reliability is key. bv doesn't assume a perfect environment; it actively handles common file system inconsistencies.

The loader (pkg/loader/loader.go) doesn't just blindly open .beads/beads.jsonl. It employs a priority-based discovery algorithm:

1. Canonical: Checks for issues.jsonl (preferred by beads upstream).
2. Legacy: Fallback to beads.jsonl for backward compatibility.
3. Base: Checks beads.base.jsonl (used by bd in daemon mode).
4. Validation: It skips temporary files like *.backup or deletions.jsonl to prevent displaying corrupted state.

The JSONL parser is designed to be Lossy-Tolerant.

• It uses a buffered scanner (bufio.NewScanner) with a generous 10MB line limit to handle massive description blobs.
• Malformed lines (e.g., from a merge conflict) are skipped with a warning rather than crashing the application, ensuring you can still view the readable parts of your project even during a bad git merge.

Traditional issue trackers (Jira, GitHub Issues, Trello) model work as Buckets: "To Do", "In Progress", "Done". This is fine for simple task lists, but it fails at scale because it ignores Structure.

In complex software projects, tasks are not isolated. They are deeply interconnected. A "simple" frontend task might depend on a backend endpoint, which depends on a schema change, which depends on a migration script.

bv adopts a Graph-First philosophy:

1. Structure is Reality: The dependency graph is the project. The list view is just a projection of that graph.
2. Explicit Blocking: We don't just "relate" tasks; we define strict "blocks". If A blocks B, you literally cannot mark B as "Ready" in bv until A is Closed.
3. Local-First, Text-Based: Your project data lives in your repo (.beads/beads.jsonl), not on a remote server. It travels with your code, branches with your git, and merges with your PRs.

bv is engineered for speed. We believe that latency is the enemy of flow.

• Startup Time: < 50ms for typical repos (< 1000 issues).
• Rendering: 60 FPS UI updates using Bubble Tea.
• Virtualization: List views and Markdown renderers are fully windowed. bv can handle repositories with 10,000+ issues without UI lag, consuming minimal RAM.
• Graph Compute: A two-phase analyzer computes topo/degree/density instantly, then PageRank/Betweenness/HITS/Critical Path/Cycles asynchronously with size-aware timeouts.
• Caching: Repeated analyses reuse hashed results automatically, avoiding recomputation when the bead graph hasn’t changed.

bv includes a comprehensive benchmark suite for performance validation:

# Run all benchmarks
./scripts/benchmark.sh

# Save current performance as baseline
./scripts/benchmark.sh baseline

# Compare against baseline (requires benchstat)
./scripts/benchmark.sh compare

# Quick benchmarks (CI mode)
./scripts/benchmark.sh quick

Benchmark Categories:

• Full Analysis: End-to-end Analyze() pipeline at various scales
• Individual Algorithms: PageRank, Betweenness, HITS, TopoSort isolation
• Pathological Graphs: Stress tests for timeout protection (many cycles, complete graphs)
• Timeout Verification: Ensures large graphs don't hang

Timeout Protection: All expensive algorithms (Betweenness, PageRank, HITS, Cycle detection) have 500ms timeouts to prevent blocking on large or pathological graphs.

Detailed Tuning Guide: For comprehensive performance documentation including troubleshooting, size-based algorithm selection, and tuning options, see docs/performance.md.

The analysis engine uses a compact adjacency-list graph (compactDirectedGraph) instead of the standard Gonum map-backed implementation. This optimization delivers significant performance improvements:

Why it matters: The default Gonum DirectedGraph uses map-backed edge sets, which cause heavy allocations during graph construction. Our compact implementation:

• Pre-allocates node arrays at known size
• Uses []int64 adjacency lists instead of map[int64]set
• Eliminates map grow/rehash overhead entirely

Real-data benchmarks: Run go test -bench=BenchmarkRealData ./pkg/analysis/... to validate performance against your project's actual .beads/issues.jsonl data.

Q: My icons look weird / text is misaligned.

• bv requires a terminal with TrueColor support and a Nerd Font installed.
• Recommended: Nerd Fonts (e.g., "JetBrains Mono Nerd Font" or "Hack Nerd Font").
• Terminals: Windows Terminal, iTerm2, Alacritty, Kitty, WezTerm.

Q: Live reload isn’t updating (especially on NFS/SMB/SSHFS/FUSE).

• Some filesystems don’t reliably deliver filesystem events. bv will try to auto-detect this and switch to polling.
• If it still misbehaves, force polling:

  BV_FORCE_POLLING=1 bv
  # or
  BV_FORCE_POLL=1 bv

Q: I see polling … in the footer. Is that bad? No — it just means bv is using polling instead of filesystem events for live reload (common on remote filesystems). Polling can add a small delay before updates appear.

Q: I see ⚠ STALE / ✗ bg … / ⚠ worker unresponsive / ↻ recovered in the footer. These indicators mean the background worker hasn’t produced a fresh snapshot recently (or needed to self-heal). Try Ctrl+R/F5, check filesystem permissions/health, or temporarily disable background mode (BV_BACKGROUND_MODE=0) to fall back to synchronous reload.

Q: I see "Cycles Detected" in the dashboard. What now? A: A cycle (e.g., A → B → A) means your project logic is broken; no task can be finished first. Use the Insights Dashboard (i) to find the specific cycle members, then use bd to remove one of the dependency links (e.g., bd unblock A --from B).

Q: Does this work with Jira/GitHub? A: bv is data-agnostic. The Beads data schema supports an external_ref field. If you populate your .beads/beads.jsonl file with issues from external trackers (e.g., using a custom script or sync tool), bv will render them alongside your local tasks. Future versions of the bd CLI may support native syncing, but bv is ready for that data today.

Q: What's the difference between "bead" and "issue"? A: They're the same thing! In the Beads ecosystem, the unit of work is called a "bead" (hence the name). However, bv uses "issue" in many places since that's the more familiar term for most developers. The CLI flags use both interchangeably: --robot-file-beads, --pages-include-closed (issues), etc. Think of "bead" as the Beads-specific term and "issue" as the general concept.

The fastest way to get started. Detects your OS and architecture automatically.

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

For Windows users using PowerShell:

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

Requirements:

• Go 1.21+ installed and in your PATH (download)
• For best display, use Windows Terminal with a Nerd Font

Requires Go 1.21+.

git clone https://github.com/Dicklesworthstone/beads_viewer.git
cd beads_viewer
go install ./cmd/bv

For Nix users, bv provides a flake for reproducible builds and development environments.

# Run directly
nix run github:Dicklesworthstone/beads_viewer

# Install to profile
nix profile install github:Dicklesworthstone/beads_viewer

# Development shell with Go toolchain
nix develop github:Dicklesworthstone/beads_viewer

Or add to your flake inputs:

{
  inputs.bv.url = "github:Dicklesworthstone/beads_viewer";
  # Use: bv.packages.${system}.default
}

Navigate to any project initialized with bd init and run:

bv

bv has a comprehensive built-in help system:

Quick Reference (?) - Press anywhere to see keyboard shortcuts for your current view. From here, press Space to jump directly to the full tutorial.

Interactive Tutorial (` backtick) - A multi-page walkthrough covering all features:

• Concepts: beads, dependencies, labels, priorities
• Views: list, board, graph, tree, insights, history
• Workflows: AI agent integration, triage, planning
• Progress is automatically saved—resume where you left off

bv automatically detects your terminal capabilities to render the best possible UI. It looks for .beads/beads.jsonl in your current directory.

Use cases for BEADS_DIR:

• Monorepos: Single beads directory shared across multiple packages
• Non-standard layouts: Projects where .beads isn't in the working directory
• Testing: Point to test fixtures without changing directory
• Cross-directory access: View beads from anywhere on the filesystem

# Example: Point to a different beads directory
BEADS_DIR=/path/to/shared/beads bv

# Example: Use in monorepo
export BEADS_DIR=$(git rev-parse --show-toplevel)/.beads

The TUI can run live reload using an experimental background snapshot worker (moves file I/O + analysis off the UI thread).

Enable (opt-in):

BV_BACKGROUND_MODE=1 bv
bv --background-mode

Disable / rollback:

BV_BACKGROUND_MODE=0 bv
bv --no-background-mode

User config file (when neither CLI flags nor BV_BACKGROUND_MODE are set):

# ~/.config/bv/config.yaml
experimental:
  background_mode: true

Precedence: CLI flags → BV_BACKGROUND_MODE → ~/.config/bv/config.yaml.

Migration plan (high level):

• Phase A (now): opt-in background mode, sync remains default.
• Phase B: broaden rollout; keep explicit rollback (--no-background-mode / BV_BACKGROUND_MODE=0).
• Phase C: flip default when stable; keep sync as fallback for a period.
• Phase D: remove legacy sync reload path after deprecation window.

Monitoring plan: no automatic telemetry today; rely on CI + regression tests and user reports during Phase A/B.

When background mode or live reload is enabled, the footer may display these indicators:

• ◌ metrics… — Phase 2 metrics are still computing; the UI renders immediately with Phase 1 data.
• ⚠ 45s ago — snapshot age warning (data is getting stale).
• ⚠ STALE: 3m ago — snapshot is stale.
• ✗ bg <phase> (3x) — background worker hit repeated errors building snapshots (phase shown; retry count in parentheses).
• ↻ recovered xN — watchdog recovered the background worker N times (transient failures/self-healing).
• ⚠ worker unresponsive — watchdog detected the worker is stuck and is recovering.
• polling … — live reload is using polling instead of filesystem events (common on remote filesystems); changes may appear with a small delay.

Tip: Ctrl+R (or F5) forces a refresh.

The UI uses a visually distinct, high-contrast theme inspired by Dracula Principles to ensure readability.

• Primary: #BD93F9 (Purple)
• Status Open: #50FA7B (Green)
• Status Blocked: #FF5555 (Red)

MIT License

Copyright (c) 2025 Jeffrey Emanuel

• Deterministic JSON contracts: robot commands emit stable field names, stable ordering (ties broken by ID), and include data_hash, analysis_config, and computed_at so multiple calls can be correlated safely.
• Health flags: every expensive metric reports status (computed, approx, timeout, skipped) plus elapsed ms and (when sampled) the sample size used.
• Consistent cache: robot subcommands share the same analyzer/cache keyed by the issue data hash, avoiding divergent outputs across --robot-insights, --robot-plan, and --robot-priority.
• Instant + eventual completeness: Phase 1 metrics are available immediately; Phase 2 fills in and the status flags tell you when it is done or if it degraded.

.beads/beads.jsonl
   ↓ tolerant loader (BOM strip, 10MB lines, skip malformed)
   ↓ graph builder (blocking deps only)
   ↓ analyzer (Phase 1 fast; Phase 2 centralities with timeouts)
   ↓ cache (hash-keyed)
   ↓ outputs: TUI | robot JSON | exports/hooks

• Hash and config travel with every robot payload so downstream consumers can verify consistency.

• PageRank: “blocking authority” — foundational tasks with many (or important) dependents.
• Betweenness: “bridges” — nodes on many shortest paths; bottlenecks between clusters.
• HITS: hubs (aggregators) vs authorities (prerequisites).
• Critical-path depth: longest downstream chain length; zero slack keystones.
• Eigenvector: influence via influential neighbors.
• Density, degree, topo sort: structural backbone.
• Cycles: detected via Tarjan SCC + DirectedCyclesIn; capped with timeouts and stored count.
• Each appears in robot insights with its status flag and, when ready, per-issue scores.

• Phase 1 (instant): degree, topo sort, density; always present.
• Phase 2 (async): PageRank, Betweenness, HITS, Eigenvector, Critical Path, Cycles; 500ms defaults with size-based adjustments. Status flag reflects computed/approx/timeout/skipped.

• Per-metric status: computed (full), approx (e.g., sampled betweenness), timeout (fallback), skipped (size/density guard).
• Payload example:

  {
    "status": {
      "pagerank": {"state":"computed","ms":142},
      "betweenness": {"state":"approx","ms":480,"sample":120},
      "cycles": {"state":"timeout","ms":500,"reason":"deadline"}
    }
  }