Beads Viewer (bv)

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

     ![Main split view](screenshots/screenshot_01__main_screen.webp) 

Main split view: fast list + rich details

     ![Kanban board](screenshots/screenshot_03__kanban_view.webp) 

Kanban board (b) for flow at a glance

     ![Insights view](screenshots/screenshot_02__insights_view.webp) 

Insights panel: PageRank, critical path, cycles

     ![Graph view](screenshots/screenshot_04__graph_view.webp) 

Graph view (g): navigate the dependency DAG

Installation

Recommended: Homebrew (macOS/Linux)

brew install dicklesworthstone/tap/bv

This method provides:

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

Windows: Scoop

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

Homebrew and Scoop select the version in their published manifests. To pin v0.25.2, use a verified release archive below. See the distribution checks for version and checksum details.

Alternative: Direct Download

Pick the archive for your platform from the latest release page. Archives are named bv___.tar.gz (.zip on Windows), for example bv_0.25.2_linux_amd64.tar.gz, bv_0.25.2_darwin_arm64.tar.gz, bv_0.25.2_windows_amd64.zip, so a downloaded file always says which release it came from. Every release also ships checksums.txt; verify before extracting:

sha256sum -c --ignore-missing checksums.txt

Releases up to v0.22.0 used unversioned names (bv_linux_amd64.tar.gz); bv --update and install.sh accept both forms.

Alternative: Install Script

Linux/macOS: Prefer Homebrew, Scoop, or a checksum-verified release archive above. If you do pipe the script, pin it to a commit you have read instead of the moving main branch:

# Pinned to a reviewed commit; read it first: https://github.com/Dicklesworthstone/beads_viewer/blob/a43b8e85a39664381566abdfd85dc8fcbfdcb773/install.sh
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/a43b8e85a39664381566abdfd85dc8fcbfdcb773/install.sh" | bash

Warning: curl ... | bash runs whatever the URL serves at that moment. The pinned form above cannot change under you; the main form can. install.sh downloads the release archive for your platform, verifies it against the release checksums.txt, and refuses to install on a mismatch.

Windows (PowerShell):

# Pinned to a reviewed commit; read it first: https://github.com/Dicklesworthstone/beads_viewer/blob/a43b8e85a39664381566abdfd85dc8fcbfdcb773/install.ps1
irm "https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/a43b8e85a39664381566abdfd85dc8fcbfdcb773/install.ps1" | iex

Note: The pinned installer above downloads the Windows release zip, verifies it against the release checksums.txt with Get-FileHash, and refuses anything that does not verify; no Go toolchain is needed. Pass -Version v0.25.2 to pin a release or -InstallDir to choose the folder (default %LOCALAPPDATA%\Programs\bv). Scoop installs the archive selected by its manifest. For best display, use Windows Terminal with a Nerd Font.

For a source build, use install.ps1 from this checkout (requires Git and Go 1.26+):

.\install.ps1 -FromSource -Version v0.25.2

This source path builds a verified checkout of the requested tag with that tag's vendored dependencies, checks the executable's version and Git revision before installation, and retains diagnostics on failure. The pinned installer above uses the same verified source-build path. Selecting an older release tag does not include later, unreleased fixes from this checkout.

Vendoring covers the Go module dependencies, not the compiler. When your Go differs from the toolchain directive in that tag's go.mod, Go downloads the pinned toolchain before compiling, so the source build needs network access even though the dependencies are vendored, and on a slow machine that download alone can take several minutes. The installer's progress line reports the Go it was launched with, not the toolchain it ends up building with; go version -m on the installed executable reports the one actually used.

Generating the JSONL File (br and bd)

bv reads Beads JSONL exports from .beads/. Current br and Dolt-backed bd workspaces use .beads/issues.jsonl; older legacy workspaces may use .beads/beads.jsonl. bv auto-discovers the supported file names.

Rust (br) users — run br sync --flush-only after Beads mutations so .beads/issues.jsonl is current.

Go (bd) users — run:

bd export -o .beads/issues.jsonl

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

🤖 Agent Quickstart (Robot Mode)

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

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

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

# 3) TOON output: smaller only for wide tabular payloads (--robot-graph); larger
#    for nested ones such as --robot-triage. Check with --stats before adopting.
bv --robot-graph --format toon
bv --robot-triage --format toon --stats
export BV_OUTPUT_FORMAT=toon

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

Output conventions

• stdout = JSON/TOON data only
• stderr = diagnostics
• exit 0 = success

TOON uses an external toon_rust encoder. Discovery honors TOON_TRU_BIN or TOON_BIN, then looks for tru or toon on PATH and the library's known fallback paths; candidates are validated as toon_rust. If none is available, bv warns on stderr and emits JSON. A successful fallback is not evidence that TOON encoding ran. Keep the format set to JSON when copying the jq examples below.

💡 TL;DR

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

Why you'd care:

• Local browsing: Browse thousands of issues without a network round trip. Response time depends on the graph, selected view, and host.
• Focus: Stay in your terminal and use Vim-style keys (j/k) to navigate.
• Intelligence: It visualizes your project as a dependency graph, automatically highlighting bottlenecks, cycles, and critical paths that traditional list-based trackers miss.
• AI-Ready: It provides structured, pre-computed insights for AI coding agents, acting as a "brain" for your project's task management.

📖 The Core Experience

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

⚡ Fast, Fluid Browsing

Browse your issue backlog in the terminal using standard Vim keys (j/k). Startup and navigation time depend on the workload; measured limits are described under Performance.

• 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.
• Keyboard Filtering: Press o for Open, c for Closed, or r for Ready (unblocked) tasks.
• Live Reload: Watches the active Beads JSONL or SQLite source and refreshes lists, details, and insights automatically. SQLite updates are detected even while committed changes remain in its write-ahead log (WAL).

🔎 Rich Context

Don't just read the title. bv gives you the full picture:

• Comments & History: Scroll through the full conversation history of any task.
• Metadata: Instantly see Assignees, Labels, Priority badges, and creation dates.
• Search: Fuzzy list filtering (/) matches the title, ID, status, issue type, assignee, labels and repo prefix, whether or not the current terminal width displays them. CLI keyword search (--search) also indexes descriptions and can combine text scores with graph metrics.
• Dependency Details: The detail pane shows dependencies up to three edges from the selected issue. Each issue's dependencies appear once along a shortest path; other occurrences say (reference: shown elsewhere). Every relationship within that limit retains its type and target metadata. Cycle-closing edges carry a separate (cycle) marker.

🎯 Focused Workflows

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

🛠️ Quick Actions

• Export: Press x to export all issues to a timestamped Markdown file with Mermaid diagrams (E opens the tree view).
• 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 loaded source in a GUI editor, or edit the focused issue's frontmatter in a terminal editor while the TUI is suspended.
• Time-Travel: Press t to compare against any git revision, or T for quick HEAD~5 comparison. Combined with History view (h), you can navigate to any commit and see exactly what changed.

🔌 Automation Hooks

Configure pre- and post-export hooks in .bv/hooks.yaml to run validations, notifications, or uploads. Report exports (--export / --export-md) and Pages exports run configured hooks; pass --no-hooks to skip them for one export. Defaults: pre-export hooks fail fast on errors (on_error: fail), post-export hooks log and continue (on_error: continue). A post-export hook declared on_error: fail makes the export exit 1 even though the bundle has already been written. 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.

Security: hooks are shell commands defined by the project you are exporting, so treat .bv/hooks.yaml in an unfamiliar repository as untrusted code and review it before exporting (or pass --no-hooks). To limit blast radius, bv strips credential-bearing environment variables (names containing TOKEN, SECRET, PASSWORD, CREDENTIAL, API_KEY, ACCESS_KEY, PRIVATE_KEY, etc., plus SSH_AUTH_SOCK) from hook subprocesses. A hook that legitimately needs one must re-grant it explicitly, e.g. env: { GITHUB_TOKEN: "${GITHUB_TOKEN}" }.

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

The text below is exactly what bv --agents-add (and the TUI's AGENTS.md prompt) installs (pkg/agents/blurb.go, AgentBlurb); a docs parity test keeps this copy identical to it.

---

## Beads Workflow Integration

This project uses a Beads tracker—either the Go `bd` CLI or the Rust `br` CLI—for issue tracking, plus [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) (`bv`) for graph-aware triage. Issues are stored in `.beads/`. `bv` auto-discovers supported JSONL exports, including `.beads/issues.jsonl` and legacy `.beads/beads.jsonl`.

**Choose the tracker CLI from this repository's instructions and configuration.** Use `bd` commands in a Go Beads workspace and `br` commands in a beads_rust workspace. Do not run both trackers against the same workspace or infer the tracker solely from the JSONL filename.

### Using bv as an AI sidecar

bv is a graph-aware triage engine for Beads projects. Instead of parsing .beads/issues.jsonl / .beads/beads.jsonl directly 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). The selected tracker CLI (`bd` or `br`) handles creating, claiming, modifying, and closing beads.

**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.** Its `triage` object contains:
- `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

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

# TOON output (--format toon): a compact tabular encoding. Measured on this
# repository it is 7% smaller than JSON for --robot-graph but 9-15% LARGER for
# nested payloads (--robot-triage, --robot-plan, --robot-insights,
# --robot-label-health); use --stats to see both sizes before adopting it.
# TOON encoding shells out to the tru binary. With no encoder installed,
# --format toon prints a fallback warning, emits JSON with output_format "json",
# and --stats prints no sizes at all.
bv --robot-graph --format toon
bv --robot-triage --format toon --stats
```

Recommendations can include blocked or assigned work; `triage.quick_ref.top_picks` reflects snapshot readiness. A suggested action records its original local ID, working directory, and tracker route. Use that route rather than a namespaced display ID or an unrelated current directory. Inspect current tracker state before execution: analysis does not reserve work or guarantee that a later claim succeeds.

#### Other bv Commands

| Command | Returns |
|---------|---------|
| `--robot-plan` | Parallel execution tracks with unblocks lists |
| `--robot-priority` | Priority misalignment detection with confidence |
| `--robot-insights` | Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core |
| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |
| `--robot-suggest` | Hygiene: duplicates, missing deps, label suggestions, cycle breaks |
| `--robot-diff --diff-since ` | Changes since ref: new/closed/modified issues |
| `--robot-graph [--graph-format=json\|dot\|mermaid]` | Dependency graph export |

Robot analysis commands default to JSON; `--format toon` selects TOON, and `--robot-help` defaults to text. In JSON mode, `--graph-format=dot` or `mermaid` puts diagram text in the `graph` field (`bv --robot-graph --graph-format=dot | jq -r .graph`).

#### Scoping & Filtering

```bash
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
```

### Tracker Commands for Issue Management

Use exactly one command family, matching the tracker configured for the repository.

#### Rust beads_rust (`br`)

Use `br` 0.6.0 or newer when executing saved claim commands. It rechecks
deferred status and future `defer_until` values when the claim runs, so a
recommendation captured before a deferral cannot bypass it. This requirement
applies to executing tracker claims.

```bash
br ready --json                       # Show issues ready to work (no blockers)
br list --status=open --json          # All open issues
br show  --json                   # Full issue details with dependencies
br create --title="..." --type=task --priority=2 --json
br update  --claim --json         # Claim for the current actor and start work
br close  --reason="Completed" --json
br close   --reason="Completed" --json
br sync --flush-only                  # Export DB to JSONL after Beads mutations
```

#### Go Beads (`bd`)

```bash
bd ready --json                       # Show issues ready to work
bd show  --json                   # Full issue details
bd create "..." -t task -p 2 --json
bd update  --claim --json         # Atomically claim work
bd close  --json
bd dep add  
bd export -o .beads/issues.jsonl        # Refresh the compatibility export read by bv
```

### Workflow Pattern

1. **Triage**: Run `bv --robot-triage` to find the highest-impact actionable work
2. **Verify**: Check the selected tracker's `show`/`ready` output before claiming
3. **Claim**: Use `br update  --claim --json` or `bd update  --claim --json`
4. **Work**: Implement the task
5. **Complete**: Use the selected tracker's `close` command
6. **Refresh for bv**: Run `br sync --flush-only` or the `bd export` command above so the JSONL export is current

### Key Concepts

- **Dependencies**: Issues can block other issues. `br ready --json` and `bd ready --json` show unblocked work.
- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
- **Types**: task, bug, feature, epic, chore, docs, question
- **Blocking**: Use `br dep add  ` or `bd dep add  ` to add dependencies

### Git Policy

Tracker commands do not grant permission to commit or push application code. Follow this repository's own git and tracker instructions before staging, committing, syncing, or pushing. If the repository says "commit only when asked," that rule overrides any generic workflow advice.

Version Tracking:

The blurb uses HTML comment markers for version tracking:

... content ...

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

📐 Architecture & Design

bv treats your project as a directed dependency graph, including cycles when present. Its graph metrics help identify blockers and structural importance.

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/issues.jsonl  
or legacy beads.jsonl  
JSONL Issue Store"]:::data
    end

    subgraph engine [" ⚙️ Analysis Engine "]
        B["Loader"]:::logic
        C["Graph Builder"]:::logic
        D["9 Metrics  
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  
JSON for AI Agents"]:::output
        J["--export-md  
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

Key Metrics & Algorithms

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

1. PageRank (Dependency Authority)

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.

2. Betweenness Centrality (Bottlenecks)

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.

3. HITS (Hubs & Authorities)

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.

4. Critical Path (Longest Path in DAG)

The Math: In a DAG, bv measures unweighted chain depth in tasks. Edges point from a dependent to its prerequisite, so the score is: $$Impact(u) = 1 + \max({Impact(v) \mid v \to u} \cup {0})$$ The implementation evaluates this in topological order. This node-count metric does not use task durations or establish a minimum project completion time.

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. High scores identify prerequisites supporting long dependent chains. Inspect the separate Slack metric for structural scheduling flexibility; neither metric proves that a delay translates one-for-one into delivery time. Cyclic graphs can leave critical-path metrics unavailable, as reported by .status.Critical.

5. Eigenvector Centrality (Influential Neighbors)

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.

6. Degree Centrality (Direct Connections)

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 can make its dependents ready when their remaining prerequisites and eligibility conditions are satisfied.
• High Out-Degree: This task has many prerequisites. It's likely to be blocked and should be scheduled later in the execution plan.

7. Graph Density (Interconnectedness)

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.

8. Cycle Detection (Circular Dependencies)

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 strongly connected components algorithm and extracts one representative cycle from each cyclic component. It analyzes blocking edges among non-closed, non-tombstoned issues, applies a storage cap, and reports truncation in .status.Cycles.reason. It does not enumerate every elementary cycle; breaking one reported cycle can leave others in the same component.

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)

9. Topological Sort (Execution Order)

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: Edge direction matters. In bv's stored graph, A → B means A depends on B. A raw topological ordering of those edges puts A before B; bv reverses that ordering so its published order puts prerequisites first. The cross-label Flow Matrix presents the opposite edge direction, from blocker to dependent.

Pragmatic Meaning: Work Queue. --robot-plan checks dependency eligibility and groups actionable work into tracks. Raw topological order alone does not establish readiness: lifecycle status, unresolved blockers and deferral also matter.

🤖 The Robot Protocol (AI Interface)

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 "Cognitive Offloading" Strategy

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 first and computes the remaining metrics asynchronously with size-aware timeouts. Graph-stat caches are keyed by issue data and analysis configuration; readiness and ranking also depend on the selected scope and reference clock. Check each metric's status before interpreting its values.

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.

Why bv vs. Raw Beads?

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

Agent Usage Patterns

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: The agent uses --robot-plan to select currently actionable work and group it into dependency-connected tracks. Items are ordered by priority, then ID within each track; the plan does not assign agents or establish freedom from file conflicts.

JSON Output Excerpt (--robot-insights): Field names are case-sensitive. This excerpt uses illustrative values and omits the source envelope and other metrics; bv --robot-schema describes the complete contract.

{
  "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,
  "full_stats": {
    "pagerank": { "CORE-123": 0.15 },
    "betweenness": { "CORE-123": 0.45 },
    "eigenvector": { "AUTH-007": 0.82 },
    "critical_path_score": { "API-001": 12.0 }
  },
  "status": {
    "PageRank": { "state": "computed" },
    "Cycles": { "state": "computed" }
  }
}

🎨 TUI Engineering & Craftsmanship

bv is built with the Bubble Tea framework. Its adaptive layout responds to terminal resize events, and its custom graph renderer supports ASCII and Unicode. A 60fps frame budget is a design target; actual interaction latency depends on the graph, view, terminal, and host.

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  
Keys · Mouse · Resize"]:::core
    MODEL["🫖 Model  
Issues · Stats · Focus"]:::core
    GRAPH["🧮 Graph Engine  
PageRank · HITS · Cycles"]:::engine
    VIEWS["🖼️ Views  
List · Board · Graph · Tree · Insights"]:::ui
    LAYOUT["📐 Layout  
Mobile · Split · Wide"]:::ui
    TERM["🖥️ Terminal  
Rendered 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

1. Adaptive Layout Engine

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

• Dynamic Resizing: Update() handles terminal-size messages and resizes the views.
• Terminal Breakpoint: At 100 columns or fewer, the list uses a single pane. Above 100 columns, the default split allocates 40% of the available content width to the list and 60% to details, after panel overhead. The pane ratio is adjustable.
• Optional Row Columns: The default list delegate uses the actual list-row width, not terminal width: above 100 cells it can show an assignee, above 120 a graph-score sparkline, and above 140 label tags. A 140-column terminal with the default split does not have room for these columns.
• 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.

2. Viewport Virtualization

bv limits list rendering to visible rows, including when browsing 10,000 issues:

• Windowing: We only render the slice of rows currently visible in the terminal window.
• Pre-Computation: Expensive graph metrics are computed asynchronously at startup and when source snapshots change. Navigation reuses the completed results.
• Detail Caching: The Markdown renderer is reused. It can retain the last exact render within a 512 KiB input/output budget; selecting a different issue renders its actual details. Virtualizing the list does not eliminate the cost of rendering long details or analyzing a large graph.

3. Visual Graph Engine (pkg/ui/graph.go)

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

• Line Canvas: The renderer assembles styled strings into a line-based canvas and clips it to the viewport.
• Dependency Neighborhood: The selected issue appears between its blockers above and its dependents below, joined by Unicode connectors. Impact scores order the node selector; this is not a whole-graph topological layout.
• Panning: Horizontal and vertical scrolling reveal portions of the selected neighborhood outside the viewport.

4. Thematic Consistency

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.

📈 Visual Data Encoding: Sparklines & Heatmaps

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.

1. Unicode Sparklines

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.

2. Semantic Heatmaps

GetHeatmapColor in pkg/ui/visuals.go maps scores to four discrete themed bands:

• ≤ 0.2: Low (Theme.Secondary)
• > 0.2 through 0.5: Mid (Theme.InProgress)
• > 0.5 through 0.8: High (Theme.Feature)
• > 0.8: Peak (Theme.Primary) These colors style the list's graph-score sparklines; they indicate score bands, not an independent urgency classification.

🔍 Search Architecture

The TUI's / filter performs local fuzzy matching over a composite string for each list item. This differs from --search, which uses hashed keyword vectors over ID, title, description and labels, with optional graph-based ranking.

The "Flattened Vector" Index

IssueItem.FilterValue() constructs a string in this order: title, ID, status, issue type, assignee (if set), labels, and repository prefix (if set). Description text and priority are not included in this default list filter.

Fuzzy Subsequence Matching

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

• Example: "fix log" matches "Fix login race condition" in that order.
• Example: "bug steve" can match issue type bug followed by assignee steve.
• Example: "open v1.0" can match status followed by a label. This is subsequence matching, not a typed status/label query; use the dedicated filters for exact field selection.

Performance Characteristics

• Local work: The list's filter command builds target strings and fuzzy-match results in memory; it makes no database or network request.
• Allocations: FilterValue() builds strings during filtering, and the matcher allocates its result data. This path is not allocation-free.
• Ranking: The default filter sorts by fuzzy-match score. Stable ties retain input order; unequal scores can change the original priority or recipe order.

🧜 Mermaid Integration: Diagrams in the Terminal?

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

bv approaches this problem in two ways:

1. The Native Graph Visualizer (g)

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

• Selected-node neighborhood: Boxes show the selected issue, its blockers, and its dependents. The node list sorts by project critical-path depth when available, then by ID. A ◆ marks nodes on one deterministic longest dependency chain within the displayed scope; cyclic displayed graphs have no computed critical chain. The metrics panel retains the project analysis values.
• Expandable dependency paths: Press Space to reveal upstream and downstream edges beyond the immediate neighborhood. Paths retain their prerequisite-to-dependent direction, stop at filtered-out records, and handle cycles without recursive loops. Press Space again to collapse; expansion is remembered per selected node.
• Scrollable canvas: H/L pan horizontally and J/K scroll vertically through graph content and metrics. The viewport clips terminal cells without splitting Unicode graphemes or ANSI styles. Lowercase h/j/k/l select nodes; Enter opens details. The footer shows the current scroll position.

2. The Export Engine (--export-md)

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  
Refactor Login"]:::open
    B["UI-456  
Login Page"]:::blocked
    C["API-789  
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

📸 Graph Export (--robot-graph)

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           # JSON envelope; DOT text in .graph
bv --robot-graph --graph-format=mermaid       # JSON envelope; Mermaid text in .graph

# In default JSON mode, robot-graph wraps DOT or Mermaid text in an envelope.
# Extract its graph field:
bv --robot-graph --graph-format=dot | jq -r .graph > graph.dot
bv --robot-graph --graph-format=mermaid | jq -r .graph > graph.mmd

# 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

Output Formats

Subgraph Extraction

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)

JSON Output Excerpt

Top-level nodes and edges are counts. Node and edge records live under adjacency; other envelope fields are omitted here, and the node records below are abbreviated too — each real record also carries labels and pagerank. Edges run from the issue to its referenced dependency and retain the recorded dependency type. Empty output can omit adjacency.

{
  "format": "json",
  "data_hash": "abc123",
  "nodes": 2,
  "edges": 1,
  "adjacency": {
    "nodes": [
      { "id": "bv-123", "title": "Fix auth", "status": "open", "priority": 1 },
      { "id": "bv-124", "title": "Test auth", "status": "open", "priority": 2 }
    ],
    "edges": [
      { "from": "bv-124", "to": "bv-123", "type": "blocks" }
    ]
  }
}

bv --robot-graph | jq '{nodes, edges, ids: [.adjacency.nodes[]?.id]}'
bv --robot-graph | jq '.adjacency.edges[]? | {from, to, type}'

🌌 Interactive Graph Visualization (--export-graph)

For deep exploration of complex dependency structures, bv generates single-file HTML visualizations powered by a force-directed graph engine. Pan, zoom, filter, and drill into individual beads without a server. Scripts and styles are embedded, fonts use the system stack, and the standalone graph makes no external requests.

# 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.svg --graph-preset roomy  # Static SVG/PNG snapshot; presets: compact (default), roomy
bv --recipe actionable --export-graph ready.html # Export only work ready to start

HTML, SVG and PNG exports apply --recipe, including custom recipe files and sorted max_items limits, together with --label and --repo. Readiness still checks prerequisites in the full loaded source. An empty selection reports an error without creating a graph file.

Why Interactive Graph Visualization?

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

What's Included in the Export

Each export is a single HTML file (typically 1-2 MB depending on project size; the vendored graph library and all bead data are inlined):

Interface Overview

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: [...]      │                                                      │
└──────────────────────┴──────────────────────────────────────────────────────┘

Visual Encoding

Nodes encode multiple dimensions of information simultaneously:

Keyboard Shortcuts

The visualization is fully keyboard-driven:

Features

Filtering & Search

• Full-text search: Dropdown search over ID, title, description, design, notes, acceptance criteria, labels and assignee, with live preview (2-character minimum, top 8 results). The graph filter itself dims nodes by ID and title only.
• 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

Use Cases

Example Workflow

# 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
# One HTML file: just send it or host anywhere

Technical Notes

• No Server Required: Everything runs client-side in the browser
• Offline Capable: Works offline once opened and makes no network requests at all; Inter and JetBrains Mono are used when installed locally, otherwise the system UI and monospace fonts
• Modern Browsers: Tested on Chrome, Firefox, Safari, Edge
• Performance: Handles 500+ nodes smoothly with Canvas 2D rendering (force-graph)
• File Size: Typically 1-2 MB depending on project size and content

📄 The Status Report Engine

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.

1. The "Hybrid Document" Architecture

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.

2. Semantic Formatting

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 the author and the absolute date (YYYY-MM-DD), preserving the flow of discussion distinct from the technical spec.
• Selected Order: --export-md preserves the selected recipe's order and max_items limit. Without a recipe, it retains the loaded issue order.

⏳ Time-Travel: Snapshot Diffing & Git History

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.

The Snapshot Model

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  
10 commits ago"]
        B["HEAD~5  
5 commits ago"]
        C["HEAD  
Current"]
    end

    subgraph "Snapshots"
        D["Snapshot A  
45 issues, 3 cycles"]
        E["Snapshot B  
52 issues, 1 cycle"]
        F["Snapshot C  
58 issues, 0 cycles"]
    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

What Gets Tracked

The SnapshotDiff captures every meaningful change:

Git History Integration (pkg/loader/git.go)

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

Use Cases

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"

🍳 Recipe System: Declarative View Configuration

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

Recipe Structure

Recipes are loaded from four sources, later ones overriding earlier ones by name: the built-in defaults, ~/.config/bv/recipes.yaml (user, recipes: map), .bv/recipes.yaml (project, recipes: map), and one recipe per file under .beads/recipes/.yaml. --robot-recipes reports each recipe's source.

# .bv/recipes.yaml
recipes:
  sprint-review:
    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

The TUI applies recipe filters, the complete sort chain, and max_items to its view while retaining the loaded issues for subsequent recipe changes. Custom presentation fields configure the existing list, details, and graph:

Grouping preserves recipe order within each group. A refresh keeps selected issue IDs and expanded groups; changing recipes resets recipe-owned grouping and display defaults. Narrow rows fit the available width, and full issue details remain accessible. Invalid columns, metrics, group names, and negative widths fail recipe validation.

Recipe exports

Export settings take effect only with an explicit output request:

bv --recipe sprint-review --export review.md
bv --recipe sprint-review --export review.json --export-format json
bv --recipe sprint-review --export review.csv --export-format csv --export-include-graph=false
bv --recipe sprint-review --export review.mmd --export-format mermaid

Explicit export flags override recipe defaults. Without either, the format is Markdown and graphs are included; CSV defaults to no graph. --export-md PATH explicitly selects Markdown. --export-include-graph=false disables a recipe graph, and --export-template= clears a recipe template. CSV with a graph, Mermaid without a graph, and custom templates for other formats are errors. Selecting a recipe for the TUI or robot analysis creates no export file.

Report bodies retain recipe membership, ordering, and max_items. Graphs also include recursively referenced dependency context, without adding those issue bodies to the report. JSON reports preserve source completeness and provenance alongside selected issues and their verified action routes. An explicit SOURCE_DATE_EPOCH fixes the generation time for reproducible reports. Pre-export hooks run before writing; post-export hooks run afterward, including their configured failure policy.

export.template and --export-template PATH read a Markdown template relative to the working directory. Templates receive .Title, .GeneratedAt, .Issues, and .Graph (Mermaid text when graphs are enabled). Each issue exposes .ID, .Title, .Status, .IssueType, .Priority, .Description, and .Labels. Issue text is escaped for literal Markdown/HTML display. Templates have no command, environment, filesystem, or issue-method access; missing fields and parse/render errors fail before writing. Template input is limited to 1 MiB and rendered output to 16 MiB.

Filter Capabilities

Built-in Recipes

bv ships with 11 pre-configured recipes:

Using Recipes

# Open bv, then press the apostrophe key (') for the recipe picker
bv

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

# Project or user recipe, by name
bv --recipe sprint-review

🎯 Composite Impact Scoring

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.

The Scoring Formula

$$ \text{Impact} = 0.22 \cdot \text{PageRank} + 0.20 \cdot \text{Betweenness} + 0.13 \cdot \text{BlockerRatio} + 0.05 \cdot \text{Staleness} + 0.10 \cdot \text{PriorityBoost} + 0.10 \cdot \text{TimeToImpact} + 0.10 \cdot \text{Urgency} + 0.10 \cdot \text{Risk} $$

Each factor is normalized to 0-1 before weighting (the *_norm fields in the breakdown). The weights are the Weight* constants in pkg/analysis/priority.go.

Component Breakdown

Why These Weights?

• 42% Graph Metrics: The structure of dependencies (PageRank plus betweenness) is the primary driver of true importance.
• 13% Blocker Ratio: Direct dependents matter for immediate unblocking.
• 30% Time, Urgency, Risk: Depth on the critical path, urgent labels, and volatility signals surface work that the pure structure would miss.
• 10% Priority: Human judgment is valuable but can be outdated or politically biased.
• 5% Staleness: Old issues deserve a nudge, but age alone should not dominate.

Feedback retunes the weights. --feedback-accept and --feedback-ignore record events in .beads/feedback.json; once at least MinFeedbackSamples (3) events exist, --robot-triage scores with the adjusted, renormalized weights and reports feedback.applied: true together with the effective weights. --feedback-reset restores the constants.

Score Output

{
  "issue_id": "CORE-123",
  "title": "Refactor auth module",
  "score": 0.87,
  "breakdown": {
    "pagerank": 0.20,
    "betweenness": 0.17,
    "blocker_ratio": 0.12,
    "staleness": 0.03,
    "priority_boost": 0.08,
    "time_to_impact": 0.09,
    "urgency": 0.08,
    "risk": 0.10
  }
}

Priority Recommendations

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.

Priority Hints Overlay

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.

🛤️ Parallel Execution Planning

When you ask "What should I work on next?", bv generates a plan for currently actionable work, respecting dependency gates and identifying opportunities for parallel work. Blocked issues provide context and counts but do not appear as actionable track items.

Track-Based Planning

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  
P1 · Unblocks 3"]:::actionable
        A2["AUTH-002"]:::blocked
        A3["AUTH-003"]:::blocked
    end

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

    subgraph track_c ["🅲 Track C: Independent"]
        C1["DOCS-001  
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

Plan Output (--robot-plan)

Abbreviated example; the response also includes source identity and metric status.

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

The Algorithm

1. Identify Actionable Issues: Require an actionable status, elapsed deferral, and satisfied dependencies in the full loaded source; retain candidate filters separately.
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; ties broken by highest priority, then lowest ID).

Benefits for AI Agents

• Deterministic: The same source, candidate scope, readiness policy and reference clock produce the same dependency plan. A deferral can expire between calls.
• Parallelism-Aware: Tracks separate dependency components. They do not detect overlapping file edits or reserve work; coordinate claims and file access separately.
• Impact-Ranked: The highest_impact field tells agents exactly where to start.

🔬 Insights Dashboard: Interactive Graph Analysis

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.

The 10-Panel Layout

The dashboard includes Bottlenecks, Keystones, Influencers, Hubs, Authorities, Cores, Cut Points, Slack, Cycles, and Priority. The illustration below shows six of those panels; the actual layout adapts to the available height.

┌─────────────────────┬─────────────────────┬─────────────────────┐
│  🚧 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        │
└─────────────────────┴─────────────────────┴─────────────────────┘

Panel Descriptions

The Detail Panel: Calculation Proofs

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.

Dashboard Navigation

📋 Kanban Board: Visual Workflow State

The Kanban Board (b) provides a columnar workflow view with swimlane grouping, visual dependency indicators, and card details. By default, Status mode keeps empty columns visible; Priority and Type modes hide them. Press e to cycle automatic, show-all, and hide-empty behavior.

Swimlane Grouping Modes

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.

Visual Dependency Indicators

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.

Rich 4-Line Card Format

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
└────────────────────────────────────┘

Column Statistics

Each column header shows aggregate statistics:

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

Inline Card Expansion

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.

Detail Panel

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

Board Navigation

🔄 List Sorting: Multi-Dimensional Organization

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.

Sort Modes

Design Philosophy

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.

Status Bar Indicator

┌────────────────────────────────────────────────────────────┐
│  📋 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.

🌲 Hierarchical Tree View: Parent-Child Visualization

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

Why Parent-Child Matters

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

• Blocking dependencies (blocks, conditional-blocks, waits-for, and any dependency written without a type, which stays blocking for legacy data): predecessor completion gates readiness according to the dependency type
• Parent-child relationships (parent-child): 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 Layout

┌─────────────────────────────────────────────────────────────────────────────┐
│  🌲 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     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Visual Encoding

Tree Building Algorithm

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), then type (epic → feature → task → bug → chore → other), then creation date (oldest 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: Components with no natural root receive a deterministic display root from a parent-child cycle, keeping their issues inspectable. Traversal guards stop repeated ancestry without changing source dependencies. Correct invalid parent links in the tracker; displaying the tree does not prove the hierarchy is acyclic.
• Deep Hierarchies: No depth limit—the tree faithfully represents arbitrarily nested structures

Tree Navigation

Use Cases

Tree vs. Graph View

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

🎯 Actionable Plan View: Parallel Execution Tracks

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.

Why Tracks Matter

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.

Visual Layout

┌─────────────────────────────────────────────────────────────────────────────┐
│  🎯 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)                                      │
└─────────────────────────────────────────────────────────────────────────────┘

What Makes an Item "Actionable"

An issue appears in the Actionable Plan when it is in the selected candidate scope, its status is open or in_progress, its deferral has elapsed, and its dependency gates are satisfied. Direct blockers and inherited parent gates are checked against the full loaded source. Closed or tombstoned predecessors satisfy a gate; a missing dependency record does not. Parked statuses such as blocked, deferred and draft are not ready merely because they have no edges. Only blocking types (blocks, conditional-blocks, waits-for, untyped) and parent-child inheritance gate readiness: related, discovered-from and any unrecognised type are informational, and they neither gate readiness nor enter the analysis graph.

Planning readiness includes ongoing or assigned work. A new claim additionally requires an open, unassigned, non-epic issue without open children or configured not-ready labels. --robot-next also requires complete source authority and a usable live tracker route before emitting a claim. These checks describe the snapshot; they do not reserve work or guarantee a later tracker mutation succeeds.

Unblock Analysis

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 identifies the plan item that unlocks the most additional ready work, with priority and ID tie-breaks. Use --robot-next and its typed action route when choosing a new claim.

Navigation

Use Cases

🔀 Flow Matrix View: Cross-Label Dependency Analysis

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.

Why Cross-Label Flow Matters

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?

Visual Layout

┌─────────────────────────────────────────────────────────────────────────────┐
│  🔀 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]          │                                  │
│                                           │                                  │
└───────────────────────────────────────────┴─────────────────────────────────┘

Bottleneck Score

The bottleneck score (0.0–1.0) measures how much a label blocks cross-domain work relative to the busiest label. It is computed in the TUI (pkg/ui/flow_matrix.go) and is not part of the --robot-label-flow payload, which reports bottleneck_labels instead:

$$ \text{Bottleneck} = \frac{\text{Outgoing Cross-Label Deps}}{\max_{\text{labels}} \text{Outgoing Cross-Label Deps}} $$

Drilldown Mode

Press Enter on a label to see its actual cross-label blocking relationships. Each relationship shows the blocker followed by the dependent; unrelated issues sharing the label are excluded. Multiple labels do not duplicate the same issue pair.

┌─────────────────────────────────────────────────────────────────────────────┐
│  Dependencies involving: api (3 relationships)                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│    ● API-123 Auth endpoint returns 500                                      │
│    ●   blocks AUTH-456 Authentication rollout                              │
│    ● API-456 Add OAuth scope validation                                    │
│    ●   blocks AUTH-789 Scoped access rollout                               │
│    ● API-789 Token refresh rate limiting                                   │
│    ●   blocks AUTH-101 Token rollout                                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Navigation

Endpoint inspection preserves the active recipe and work-selection scope. Open relationships and details refresh when issue data changes; closed or removed relationships disappear. The view does not currently display critical-path annotations for labels.

Robot Command

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

🎪 Attention View: Label Priority Ranking

Press ] (or F4) to open the Attention View—a ranked table of labels by attention score, helping you identify which project areas need focus. It is a focused view with its own cursor: move with j/k, jump with g/G, and press Enter on a label to drill into that label's issues.

Attention Score Formula

The attention score (ComputeLabelAttentionScores in pkg/analysis/label_health.go) combines multiple signals to surface neglected or problematic areas:

$$ \text{Attention} = \frac{\text{PageRank}_{\text{sum}} \times \left(1 + \frac{\text{Stale}}{\text{Open}}\right) \times (1 + \text{BlockImpact})}{\text{ClosedLast30Days} + 1} $$

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

Visual Layout

┌─────────────────────────────────────────────────────────────────────────────┐
│  🎪 ATTENTION VIEW                                                          │
├──────┬────────────┬───────────┬─────────────────────────────────────────────┤
│ Rank │ Label      │ Attention │ Reason                                      │
├──────┼────────────┼───────────┼─────────────────────────────────────────────┤
│  1   │ api        │    2.45   │ pr=0.49 stale=1.00 block=4 closed30=0      │
│  2   │ auth       │    1.89   │ pr=0.63 stale=1.00 block=2 closed30=0      │
│  3   │ infra      │    1.23   │ pr=0.41 stale=1.50 block=1 closed30=0      │
│  4   │ frontend   │    0.67   │ pr=0.67 stale=1.00 block=0 closed30=0      │
│  5   │ docs       │    0.34   │ pr=0.34 stale=1.00 block=0 closed30=0      │
└──────┴────────────┴───────────┴─────────────────────────────────────────────┘

Interpreting Results

• 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

Navigation

Robot Command

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

📚 Shortcuts Sidebar: Persistent Keyboard Reference

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

Why a Sidebar (Not Just Help)?

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

Context Awareness

The sidebar automatically filters shortcuts to show only those relevant to your current view. Sections come from the key registry (pkg/ui/keybindings.go) and are named Navigation, Views, Filters, Actions, Graph, Board, Insights, and History:

? and ; live in Views and are listed in every context.

Visual Layout

┌──────────────────────────────────────────────┬──────────────────────┐
│                                              │  ⌨️ 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           │
└──────────────────────────────────────────────┴──────────────────────┘

Sidebar Controls

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

🎓 Interactive Tutorial System

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

Tutorial Architecture

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

Tutorial Sections

The tutorial is 30 pages in 6 sections (pkg/ui/tutorial_content.go):

1. Introduction (4 pages): Welcome, the Beads philosophy, who it is for, quick start
2. Core Concepts (5 pages): Beads, dependencies and blocking, labels, priorities and status, the dependency graph
3. Views (8 pages): Navigation fundamentals, list, detail, split, board, graph, insights, history
4. Advanced (7 pages): Semantic and hybrid search, time travel, label analytics, export and deployment, workspace mode, recipes, AI agent integration
5. Workflows (5 pages): New feature, bug triage, sprint planning, onboarding, stakeholder review
6. Reference (1 page): Keyboard reference

Progress Tracking

The tutorial shows a page counter and progress bar as you read:

┌─────────────────────────────────────────────────────────────────────────────┐
│  📖 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: pages you have seen are recorded in the user config directory (pkg/ui/tutorial_progress.go) when the tutorial closes, and reopening it resumes on the page you left. Set BV_NO_SAVED_CONFIG=1 to keep it session-only.

Tutorial Navigation

Context-Sensitive Filtering

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.

Quick Reference vs. Full Tutorial

bv provides two help levels:

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

📜 History View: Bead-to-Commit Correlation

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 Correlation Engine

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  
Commit contains bead ID"]
        T["Temporal Proximity  
Commit near bead events"]
        C["Co-Commit Analysis  
Files changed together"]
    end

    subgraph scorer ["📊 Confidence Scorer"]
        S["Multi-Factor Scoring  
Weighted combination"]
    end

    subgraph output ["📈 Output"]
        H["BeadHistory  
Events + Commits + Milestones"]
    end

    E --> S
    T --> S
    C --> 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 strategy
    class S score
    class H out

Correlation Strategies

pkg/correlation/types.go defines three correlation methods, and the Correlator behind the History view and --robot-history runs all three over the same commit window: the co-commit strategy, the explicit-ID matcher (explicit.go, extended by --id-pattern), and the temporal correlator (temporal.go). When several strategies match the same (commit, bead) pair the highest-confidence one becomes method and every match is listed in methods; stats.method_distribution and stats.strategies report the per-strategy counts. Stored confirm/reject feedback is applied on top (see Correlation Feedback System).

There is no path-matching strategy; label-to-path hints only nudge temporal scores inside temporal.go.

Confidence Scoring

Each correlation carries a confidence score (0.0–1.0). The table gives single-strategy ranges; combining strategies can boost the strongest score, and confirming a pair pins it to 1.0. --robot-explain-correlation also reports heuristic signal weights: co-commit 50, explicit message match 40, timing 25 plus author match 15, file overlap 5 per file (capped at 15), and proximity 7 near the top of the method's range. Those explanatory weights are not an arithmetic derivation of the confidence score.

History View Layout

The History View uses a responsive layout that adapts to terminal width (layoutBreakpointStandard and layoutBreakpointWide in pkg/ui/history.go):

Standard Terminal (3-pane) Layout, abbreviated:

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

Timeline Panel

At 150 columns or wider in bead mode, the Timeline Panel appears automatically as a fourth pane. It lists the selected bead's lifecycle events and correlated commits chronologically, oldest first, with timestamps and event or commit details. It is not a project-wide activity-density chart.

The pane is on by default at 150 columns or wider; press t in the History view to toggle it for the session (it needs bead mode and at least 100 columns).

Causality Markers

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

A pair matched by more than one strategy shows the highest-confidence marker; a confirmed pair (--robot-confirm-correlation) is pinned to confidence 1.0 and flagged confirmed.

View Modes

Press v to toggle between two view modes:

File-Centric Drill-Down (f Key)

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.

History Navigation

Robot Command: --robot-history

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
bv --robot-history | jq '{avg_cycle_time_days: .stats.avg_cycle_time_days, beads: [.histories | to_entries[] | {id: .key, claim_to_close_ns: .value.cycle_time.claim_to_close}]}'

Abbreviated output example: lifecycle events, commits and additional metadata are omitted here. milestones is an object keyed by lifecycle event; cycle_time durations are nanoseconds, while the aggregate average uses days.

{
  "stats": {
    "total_beads": 58,
    "beads_with_commits": 42,
    "total_commits": 156,
    "avg_cycle_time_days": 3.0,
    "method_distribution": {
      "explicit_id": 89,
      "temporal_author": 45,
      "co_committed": 22
    }
  },
  "histories": {
    "BV-123": {
      "milestones": {},
      "cycle_time": { "claim_to_close": 173520000000000 }
    }
  },
  "commit_index": {
    "abc1234": ["BV-123", "BV-456"]
  }
}

🔗 Correlation Analysis: Impact Network & Related Work

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.

Impact Network Graph

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  
Same commit touches both beads"]
        SF["Shared File  
Both beads modify same files"]
        DEP["Dependency  
Explicit blocker relationship"]
    end

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

Network Clusters

bv automatically detects clusters of tightly-connected beads as the connected components of the network after dropping edges with weight below 2 (detectClusters in pkg/correlation/network.go):

┌─────────────────────────────────────────────────────────────────────────┐
│  🔗 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)                              │
└─────────────────────────────────────────────────────────────────────────┘

File-to-Bead Lookup

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",