Beads Viewer (bv)

The development of Beads Viewer follows a phased approach. While users primarily interact with the current version, this roadmap outlines the planned evolution of the tool's capabilities:

• Phase 1 (Foundation): Focuses on Unified Triage and the Agent Registry (data model and basic commands).
• Phase 2 (Core): Introduces Work Claims & Conflicts, Proactive Alerts, and Graph Visualization (via DOT export).
• Phase 3 (Advanced): Adds the Sprint System, ETA Forecasting, and Agent Partitioning.
• Phase 4 (Polish): Finalizes the user experience with ASCII graphs in the TUI, Smart Suggestions, and a dedicated Query Language.

bv manages its local artifacts (semantic search index, baselines, drift config) under the .bv/ directory. To prevent these from being committed to git, bv follows these rules:

1. Opt-out: If BV_NO_GITIGNORE is set, bv does nothing.
2. Non-git repos: If no .git is found, nothing is written.
3. Existing ignores: If .bv/ is already in .gitignore, .git/info/exclude, or global gitignore, bv leaves it alone.
4. Automatic addition: Otherwise, bv appends .bv/ to .git/info/exclude (the per-repo exclude file). This keeps the ignore rule invisible to collaborators.

bv uses pure file I/O and does not require git to be installed or spawn git subprocesses.

The bv loader is designed for high reliability and handles file system inconsistencies through several mechanisms:

1. Priority-based Discovery: It searches for data in this order:
   • issues.jsonl (Canonical/Preferred)
   • beads.jsonl (Legacy fallback)
   • beads.base.jsonl (Used by br in daemon mode)
2. Lossy-Tolerant Parsing: The parser uses a buffered scanner with a 10MB line limit. If it encounters malformed lines or corrupted JSON (e.g., from a git merge conflict), it logs a warning to stderr and continues loading valid data instead of crashing.
3. File Filtering: It automatically skips temporary files like *.backup or deletions.jsonl to ensure only valid state is displayed.

The Beads Viewer data plane is shared between the Robot (CLI) and the TUI (Terminal User Interface). The processing pipeline follows these steps:

1. Loading: Data is loaded from .beads/issues.jsonl (preferred) or .beads/beads.jsonl (fallback) using pkg/loader/loader.go.
2. Graph Construction & Analysis: The system builds a graph and computes metrics via the Analyzer in pkg/analysis/graph.go (using NewAnalyzer, AnalyzeAsync, or AnalyzeWithProfile).
3. Output Derivation: Higher-level outputs like unified triage (pkg/analysis/triage.go) or priority tuning (pkg/analysis/priority.go) are derived from the analysis.
4. Presentation: Results are presented via Robot JSON (cmd/bv/main.go with --robot-* flags) or TUI snapshots (pkg/ui/snapshot.go).

bv automatically adjusts its analysis strategy based on the number of nodes to balance accuracy and speed:

Beads Viewer (bv) can optionally integrate with cass (Claude Agent Session Store) to correlate issues with AI coding sessions. When cass is installed and indexed, bv automatically enhances its correlation capabilities with session-based insights, such as showing which AI sessions may have contributed to a specific issue.

If cass is not installed, bv continues to function normally with no errors or broken UI; the features simply become unavailable.

The TOON format (via the tru binary) provides canonical encoding for all beads_viewer robot output shapes, including support for primitives, nested objects, and specialized tabular arrays.

Supported output shapes include:

• TriageResult: Encoded as a nested object.
• []Recommendation: Encoded as a tabular array (e.g., [N]{fields}: rows) for uniform object arrays.
• TopPick: Encoded as a simple object.
• ProjectHealth: Encoded as a nested object.

When using workspace configuration, bv automatically namespaces issue IDs to prevent collisions across repositories. The format is {prefix}{LocalID}.

Example mapping:

• Local ID AUTH-123 in a repo with prefix api- becomes api-AUTH-123.
• Local ID UI-456 in a repo with prefix web- becomes web-UI-456.

This namespacing enables cross-repository dependencies, where an issue in one repository (e.g., web-UI-456) can explicitly block issues in another (e.g., api-AUTH-123).

When parsing bv robot output, use these strict definitions for counts:

• quick_ref.open_count / project_health.counts.open: Issues with status exactly open.
• quick_ref.blocked_count / counts.blocked: Issues with status exactly blocked.
• quick_ref.in_progress_count: Issues with status exactly in_progress.
• counts.closed: Issues with status closed or tombstone.
• quick_ref.not_closed_count / counts.not_closed: All non-closed issues (open + in_progress + blocked + deferred).
• quick_ref.actionable_count / counts.actionable: Non-closed issues with no open blocking dependencies (ready to work).
• quick_ref.not_actionable_count / counts.dependency_blocked: Non-closed issues blocked by open dependencies.

Invariant: not_closed == actionable + not_actionable.

Because floating-point calculations (like PageRank or Betweenness) may vary slightly due to parallel reduction or iteration order, Beads Viewer uses an Epsilon Policy to define equality. When comparing outputs, values are considered equal if they fall within the following tolerances:

Ordering Rule: If two scores differ by less than epsilon, their relative order is considered equivalent as long as the set of items remains identical.

In the bead detail pane (the right pane in split view), the history section provides a chronological timeline of the bead's lifecycle and its relationship to Git commits.

Displayed Information

• Lifecycle Events: Shows events like Created, Claimed, and Closed with timestamps and the responsible author (e.g., 🟢 Created Jan 10, 14:32 alice@dev).
• Related Commits: Displays commits correlated to the bead, including a confidence bar (e.g., ████ 95%) and the specific files changed (e.g., pkg/auth/login.go (+45, -12)).