beads_viewer: Beyond the Kanban: How bv Uses Graph Theory to Solve Project Deadlocks
A high-performance TUI that treats your issue tracker like a neural network, identifying critical paths and articulation points that stall entire engineering teams.
add Claude Code SKILL.md for automatic capability discovery
- Beads Viewer applies graph theory metrics like Betweenness Centrality to identify tasks that act as critical bottlenecks for engineering teams.
- A dedicated Robot Mode provides AI agents with mathematically ranked task lists to prevent autonomous tools from picking low-impact work.
- The tool uses a hybrid Go and Rust architecture to perform complex graph calculations with sub-100ms latency directly in the terminal.
- Local-first project management allows teams to treat issue tracking as version-controlled state that works entirely offline.
The PageRank of Productivity
The standard software development lifecycle treats project management as a flatlist. You open Jira or GitHub Issues, assign a priority label, and work from top to bottom. Beads Viewer (bv) rejects this premise entirely. Instead of a list, it treats a project as a Directed Acyclic Graph (DAG).
By applying academic graph theory to local tasks, bv calculates the "Betweenness Centrality" of every issue. It identifies articulation points: the single, seemingly minor tasks that, if delayed, split the project graph in two. This prevents the common scenario where five senior engineers are blocked by one forgotten bug fix.
A Pre-Frontal Cortex for AI Agents
As AI coding agents like Claude Code become common, the limitation is no longer writing code. The limitation is deciding what code to write next. Giving an LLM access to a standard issue tracker usually results in it picking the easiest task, not the most structurally important one.
Beads Viewer solves this with its Robot Mode. When invoked with --robot-triage, it bypasses the visual interface and outputs a Token-Optimized Output Notation (TOON). This gives the AI agent a mathematically ranked list of tasks based on structural project risk, acting as an algorithmic pre-frontal cortex for autonomous coding.
The inclusion of standardized agent blurbs ensures that any LLM dropped into the repository immediately knows how to query the graph database to find its next critical task.
The High-Performance Engine
To calculate advanced graph metrics on thousands of nodes in real-time, bv employs a hybrid architecture. The interactive Terminal User Interface (TUI) is built in Go using the Charm Bracelet ecosystem, ensuring smooth keyboard navigation and instant visual feedback.
However, the heavy mathematical lifting is offloaded to Rust. The project compiles Rust-based graph algorithms (like K-paths and Eigenvector centrality) into WebAssembly, achieving sub-100ms latency for complex DAG analysis directly in the terminal.
Added Nix flake for reproducible builds and development environment.
Escaping the Centralized Web UI
The broader philosophy behind Beads Viewer is local-first project management. By watching local .jsonl files in a .beads directory, bv treats your issue tracker as just another piece of version-controlled state. It works entirely offline and lives adjacent to your code.
| Feature | Traditional SaaS (Jira/GitHub) | Beads Viewer (bv) |
|---|---|---|
| Data Model | Flat lists and manual tag filtering | Directed Acyclic Graph (DAG) |
| Priority Assessment | Human-assigned labels (P0, P1) | Algorithmic scoring (PageRank, Impact) |
| Latency | Network bound web requests | Sub-100ms local WASM calculations |
| AI Integration | Requires complex API scraping | Native Token-Optimized Output (TOON) |
As development moves toward autonomous agents and decentralized workflows, the centralized web dashboard becomes a bottleneck. Tools like bv represent the next generation of control panels: fast, mathematical, and built equally for humans and machines.
Sources: Repository data and releases; Beads core project documentation.