Stop Drowning in Jira Clutter: Why Devs Are Switching to beads_viewer

What if your issue tracker actually understood your codebase instead of treating it like a glorified spreadsheet?

Every developer knows the pain. You open your browser, wait for Jira to load its 47 JavaScript bundles, navigate through three layers of menus, and finally stare at a flat list of tickets that tells you nothing about what actually blocks what. Your "critical" P1 bug? It might depend on a forgotten P3 schema migration that three other teams are waiting on. But you'd never know from looking at the list. Your standup becomes a guessing game. Your sprint planning? A political negotiation based on who screams loudest, not on actual dependency logic.

Meanwhile, AI coding agents are storming into our workflows. They're fast, they're capable, and they're lost. Throw raw issues.json at Claude or GPT-4, and you're asking a probabilistic language model to perform graph traversal algorithms it was never designed for. It hallucinates dependency chains. It misses circular blockers. It suggests working on tasks that are fundamentally impossible because their prerequisites don't exist yet.

Enter beads_viewer — a graph-aware Terminal User Interface for the Beads issue tracker that treats your project as what it actually is: a Directed Acyclic Graph of interdependent work. Not a list. Not a board. A graph with bottlenecks, critical paths, and structural intelligence that surfaces what matters. And it's built for the terminal, because serious developers live in the terminal.

This isn't another dashboard. This is a cognitive offloading engine for both humans and AI agents. Let's unpack why beads_viewer is quietly becoming the secret weapon of teams who ship faster than everyone else.

What is beads_viewer?

beads_viewer (command: bv) is an elegant, keyboard-driven TUI for the Beads issue tracking system, created by Dicklesworthstone and released under an MIT license with an OpenAI/Anthropic rider. It's written in Go, built on the Bubble Tea framework, and designed for developers who refuse to leave their terminal for project management.

But calling it a "TUI" undersells it dramatically. beads_viewer is a graph-theoretic analysis engine masquerading as a pleasant browsing interface. While traditional issue trackers store dependencies as foreign key relationships, beads_viewer computes on them. It runs PageRank to find foundational blockers. It calculates betweenness centrality to expose choke points. It detects cycles that represent logical impossibilities in your project plan. And it does all of this in milliseconds, locally, with zero network latency.

The project is trending now because it solves two converging crises simultaneously:

1. Human developer overwhelm: As projects scale, flat issue lists become cognitively unmanageable. beads_viewer's dependency visualization and intelligent triage cut through the noise.

2. AI agent confusion: LLMs need structured, pre-computed insights. beads_viewer's "robot mode" provides deterministic graph analysis that agents can consume without hallucinating traversal paths.

The repository has gained serious traction among Go developers, TUI enthusiasts, and teams experimenting with AI-assisted development. Its combination of performance (starts instantly, handles thousands of issues), intelligence (9 graph metrics computed on every load), and agent-readiness (structured JSON API via CLI flags) makes it uniquely positioned for modern development workflows.

Key Features That Separate beads_viewer from Everything Else

Graph-Aware Intelligence, Not Just Display

Most tools show dependencies. beads_viewer reasons about them. It computes 9 graph-theoretic metrics using algorithms borrowed from network science:

• PageRank: Recursive importance via the random surfer model — finds your project's bedrock tasks
• Betweenness Centrality: Shortest-path traffic analysis — exposes gatekeepers between teams
• HITS (Hubs & Authorities): Distinguishes epic-aggregators from utility-providers
• Critical Path: Longest dependency chain — identifies zero-slack keystones
• Eigenvector Centrality: Influence through important neighbors — strategic dependencies
• Degree Centrality: Direct connection counts — immediate blockers and blocked tasks
• Graph Density: Edge-to-node ratio — project coupling health indicator
• Cycle Detection: Tarjan's algorithm — finds logical impossibilities in your plan
• Topological Sort: Valid execution ordering — the foundation of automated planning

These aren't vanity metrics. They power actionable triage recommendations that tell you why a task matters structurally, not just who yelled about it in Slack.

Dual Interface: Human TUI + Robot API

beads_viewer operates in two distinct modes:

Interactive TUI: Vim-key navigation (j/k to move, / to search, g for graph view, b for kanban, i for insights). Split-view layout on wide terminals. Live reload when .beads/beads.jsonl changes. Markdown rendering with syntax highlighting.

Robot Mode (--robot-* flags): Structured JSON output for AI agents. No TUI launched, no blocking. Deterministic, cacheable, with data hash consistency verification across calls.

This dual design is deliberate. The same tool serves human exploration (visual, interactive, fuzzy) and agent automation (strict, parseable, fast).

Advanced Terminal Engineering

Built with Bubble Tea and Lipgloss, beads_viewer achieves 60fps rendering through:

• Viewport virtualization: Only visible rows render, even with 10,000+ issues
• Adaptive layout engine: Mobile (<100 cols), Split (>100 cols), Ultra-Wide (>140 cols) with dynamic column injection
• Custom ASCII/Unicode graph renderer: Manhattan-routed edges with proper box-drawing characters
• Semantic color system: Dracula/light themes with status-driven color coding
• Sparkline visualization: Unicode block-character bar charts for instant metric scanning

Time-Travel and Diffing

Unique among issue trackers, beads_viewer can load project state from any git revision:

bv --as-of HEAD~30 --robot-insights    # Historical point-in-time analysis
bv --diff-since v1.0.0 --robot-diff    # What changed since release?

This enables sprint retrospectives, regression detection, and release note generation from actual dependency evolution.

Use Cases: Where beads_viewer Transforms Your Workflow

1. The Daily Standup That Actually Uses Data

Instead of round-robin status updates, pull up the kanban board (b) with swimlane grouping by priority. The color-coded card borders instantly show blockers (red), ready-to-work items (green), and high-impact items that unblock others (yellow). Column statistics show critical item counts. Your standup becomes: "Why are 2 P0s stuck in Blocked? Let's look at the dependency graph."

2. Sprint Planning with Structural Awareness

Before committing to scope, run bv --robot-plan. It identifies parallel execution tracks using Union-Find on connected components. You learn that your "Auth System" track and "UI Polish" track are independent — two developers can work them simultaneously without conflict. The highest-impact starter task is explicitly identified by unblock count, not gut feel.

3. AI Agent Onboarding and Coordination

Drop the ready-made blurb into your AGENTS.md or CLAUDE.md file (auto-injectable via bv --agents-add). Your AI coding agent now has deterministic access to:

• bv --robot-triage for the complete project health snapshot
• bv --robot-next for the single top pick with claim command
• bv --robot-plan for parallel execution tracks with unblocks lists
• bv --robot-insights for full graph metrics with status flags

No more hallucinated dependency traversal. No more missed cycles. The agent gets pre-computed intelligence from a specialized graph engine.

4. Architecture Review and Technical Debt Detection

Use the Insights Dashboard (i) to spot structural problems before they become emergencies:

• Cycles panel: Circular dependencies that must be resolved (logical impossibilities)
• Bottlenecks panel: High-betweenness tasks that bridge otherwise isolated teams
• Density metric: Rising graph density signals increasing coupling — time to modularize

The Priority Hints overlay (p) flags misaligned priorities: tasks with high computed impact but low human-assigned priority get upward arrows, suggesting escalation.

5. Stakeholder Communication Without Dashboard Fatigue

Generate self-contained HTML visualizations (bv --export-graph graph.html) with force-directed interactive graphs. Pan, zoom, filter, find shortest paths between tasks. No server required, no dependencies to install. Email a single file that opens in any modern browser with full project context.

Or export management-ready Markdown reports (bv --export-md) with embedded Mermaid diagrams, automatically sorted by structural importance rather than ID sequence.

Step-by-Step Installation & Setup Guide

Prerequisites

• Go 1.21+ (for building from source, or verify for Windows install script)
• Beads issue tracker installed (br Rust version or bd Go version) to generate .beads/beads.jsonl
• Windows Terminal with a Nerd Font (Windows users, for proper glyph display)

Installation

macOS / Linux (Recommended — Homebrew)

brew install dicklesworthstone/tap/bv

This gives you automatic updates via brew upgrade, dependency management, and clean uninstallation.

Windows (Scoop)

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

Cross-Platform Install Script (Linux/macOS)

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

Cross-Platform Install Script (Windows PowerShell)

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

Note: The ?$(date +%s) cache-buster ensures you get the latest script version, not a stale CDN copy.

Direct Binary Download

For air-gapped environments or specific version pinning, download platform archives:

All links available at: https://github.com/Dicklesworthstone/beads_viewer/releases/latest/download/

Generating the Data Source

bv reads from .beads/beads.jsonl. Generate this from your Beads tracker:

Rust br users (default behavior):

br  # Automatically writes .beads/beads.jsonl

Go bd users:

bd export --no-memories -o .beads/beads.jsonl

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

First Launch

cd /your/project/root  # Must contain .beads/beads.jsonl
bv                     # Launch interactive TUI

The TUI starts instantly. Use j/k to navigate, ? for help, q to quit.

REAL Code Examples from the Repository

Example 1: Agent Triage — The Single Most Important Command

The bv --robot-triage command is designed as the one-shot entry point for AI agents. Here's exactly how it works:

# THE MEGA-COMMAND: Everything an agent needs in one call
bv --robot-triage

# Token-optimized for lower LLM context usage
bv --robot-triage --format toon
export BV_OUTPUT_FORMAT=toon
bv --robot-triage

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

What this produces: A structured JSON object containing quick_ref (at-a-glance counts + top 3 picks), recommendations (ranked actionable items with scores and unblock info), quick_wins (low-effort high-impact items), blockers_to_clear (items that unblock the most downstream work), project_health (distributions and graph metrics), and commands (copy-paste shell commands for next steps).

Critical safety rule: Never run bare bv in an agent context — it launches the interactive TUI and blocks forever. Always use --robot-* flags.

Output conventions are strict: stdout = JSON/TOON data only, stderr = diagnostics, exit 0 = success. This makes bv composable in shell pipelines and agent loops.

Example 2: Graph Export for External Visualization

beads_viewer can export your dependency graph in multiple formats for integration with other tools:

# JSON format for programmatic processing (default)
bv --robot-graph

# Graphviz DOT format for high-quality static rendering
bv --robot-graph --graph-format=dot
# Then: dot -Tpng output.dot -o graph.png

# Mermaid format for Markdown embedding
bv --robot-graph --graph-format=mermaid

# Focused subgraph: root + 3 levels of dependencies
bv --robot-graph --graph-root=bv-123 --graph-depth=3

When to use each: JSON for jq processing or custom visualizations; DOT for publication-quality printed diagrams; Mermaid for GitHub/GitLab documentation that renders automatically; subgraph extraction for large projects where full graphs are overwhelming.

Example 3: Historical Analysis and Regression Detection

Time-travel capabilities let you compare project states across git history:

# Load insights from 30 commits ago
bv --robot-insights --as-of HEAD~30

# Full diff: what changed since last release?
bv --robot-diff --diff-since v1.0.0

# Burndown for sprint "sprint-42"
bv --robot-burndown sprint-42

# Forecast completion for specific task or entire project
bv --robot-forecast bv-123
bv --robot-forecast all

The as_of and as_of_commit fields in robot output include the resolved git SHA, enabling reproducible analysis. The data_hash field fingerprints the source beads.jsonl — verify consistency across multiple agent calls to ensure you're not acting on stale data.

Example 4: Recipe-Based View Configuration

Recipes are YAML-based declarative configurations for repeatable views:

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

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

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

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

export:
  format: markdown
  include_graph: true

Invoke with:

bv --recipe sprint-review           # From .beads/recipes/
bv --recipe .beads/recipes/sprint-review.yaml  # Direct path
bv --recipe actionable              # Built-in: ready-to-work items
bv --recipe high-impact             # Built-in: top PageRank scores
bv --recipe bottlenecks             # Built-in: high betweenness nodes

Built-in recipes cover common workflows: default, actionable, recent, blocked, high-impact, stale, triage, closed, release-cut, quick-wins, bottlenecks.

Example 5: Automation Hooks for CI/CD Integration

Configure pre- and post-export hooks in .bv/hooks.yaml:

# .bv/hooks.yaml
pre-export:
  - name: validate-jsonl
    command: python scripts/validate_beads.py
    on_error: fail           # Stop export if validation fails
    env:
      STRICT: "1"

post-export:
  - name: upload-to-s3
    command: aws s3 cp "$BV_EXPORT_PATH" s3://reports/
    on_error: continue       # Log error but don't fail export
    env:
      AWS_REGION: us-east-1

  - name: notify-slack
    command: curl -X POST -d "{\"text\":\"Report ready: $BV_EXPORT_PATH\"}" "$SLACK_WEBHOOK"
    on_error: continue

Environment variables available: BV_EXPORT_PATH, BV_EXPORT_FORMAT, BV_ISSUE_COUNT, BV_TIMESTAMP, plus any custom env entries. Empty commands are ignored with a warning for safety.

Advanced Usage & Best Practices

Two-Phase Analysis Awareness

Robot mode uses two-phase computation for performance:

• Phase 1 (instant): degree, topological sort, density — always available immediately
• Phase 2 (async, 500ms timeout): PageRank, betweenness, HITS, eigenvector, critical path, cycles

Always check status flags in JSON output. For large graphs (>500 nodes), Phase 2 metrics may be approximated, timeout, or skipped. Prefer --robot-plan over --robot-insights when speed matters most.

jq Integration for Shell Workflows

# At-a-glance summary
bv --robot-triage | jq '.quick_ref'

# Top recommendation details
bv --robot-triage | jq '.recommendations[0]'

# Check for circular dependencies (must fix!)
bv --robot-insights | jq '.Cycles'

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

# Best unblock target from plan
bv --robot-plan | jq '.plan.summary.highest_impact'

Composite Impact Scoring for Priority Reconciliation

The Impact Score formula blends graph metrics with temporal signals:

Impact = 0.30·PageRank + 0.30·Betweenness + 0.20·BlockerRatio + 0.10·Staleness + 0.10·PriorityBoost

Use p in TUI to toggle Priority Hints — upward arrows (⬆) suggest under-prioritized tasks, downward arrows (⬇) suggest over-prioritized tasks. Reconcile human judgment with structural reality.

Agent File Integration

Automatically inject agent instructions into your project:

bv --agents-check      # Verify blurb presence
bv --agents-add        # Inject into AGENTS.md or CLAUDE.md
bv --agents-update     # Update to latest blurb version
bv --agents-dry-run    # Preview changes without writing

Preferences stored per-project in ~/.config/bv/agent-prompts/. The blurb uses HTML comment markers for version tracking so updates are non-destructive.

Comparison with Alternatives

The decisive advantage: beads_viewer is the only tool that combines terminal-native ergonomics with production-grade graph analytics and purpose-built AI agent integration. It's not competing with Jira's permission models or Linear's polish — it's for teams who need structural intelligence about their work, not just a prettier list.

FAQ

Is beads_viewer a replacement for Jira or Linear?

No — it's a complementary intelligence layer for teams using the Beads issue tracker. If your team is locked into Jira, beads_viewer won't directly help. But if you're adopting Beads or running a Beads-based workflow, beads_viewer provides analytics that no mainstream tracker offers.

Do I need to know graph theory to use this?

Absolutely not. The TUI presents intuitive labels: "Bottlenecks," "Keystones," "Quick Wins." The math is exposed for the curious (press e for explanations), but you can benefit immediately from the rankings without understanding eigenvectors.

How does robot mode prevent AI agent hallucination?

By cognitive offloading. Instead of asking an LLM to parse JSONL, reconstruct a graph, and compute shortest paths in its context window, you give it pre-computed, deterministic results from a specialized graph engine. The agent receives "Task X unblocks 5 tasks" as structured fact, not probabilistic inference.

Can I use beads_viewer with my existing issue tracker?

Only if you can export to Beads format (.beads/beads.jsonl). The Beads ecosystem is growing but not universal. For Jira migration, you'd need a custom converter. The Beads format itself is simple JSONL — one issue per line — so writing exporters is feasible.

What happens with very large projects (1000+ issues)?

Phase 1 metrics remain instant. Phase 2 metrics (PageRank, betweenness, etc.) may be approximated or skipped based on a 500ms timeout. Use --robot-plan for guaranteed-fast responses. The TUI uses viewport virtualization for smooth scrolling regardless of issue count.

Is the interactive HTML export secure to share?

Yes — it's completely self-contained with no external dependencies, no CDN calls, no server required. It contains your full project data though, so share appropriately. File sizes are typically 400KB-1MB.

How do I contribute or report bugs?

Visit the GitHub repository for issues, discussions, and pull requests. The project is actively maintained with automated releases via Homebrew and Scoop.

Conclusion

beads_viewer represents a fundamental rethinking of what an issue tracker interface should be. Not a database frontend. Not a colorful todo list. A structural analysis engine that surfaces the hidden geometry of your project's work graph — the bottlenecks that silently throttle your team, the cycles that make sprints impossible, the foundational tasks whose importance no priority field captures.

For human developers, it means faster triage, better planning, and less time in browser tabs. For AI agents, it means deterministic intelligence instead of hallucinated graph traversal. For teams, it means data-driven decisions about what to work on next, grounded in actual dependency structure rather than political volume.

The terminal is where serious developers live. beads_viewer brings serious project intelligence into that environment without sacrificing the speed, keyboard-driven ergonomics, and composability that make the terminal powerful.

Install it today. Run bv --robot-triage on your project. See your work graph with new eyes.

🔗 Get beads_viewer on GitHub — Star the repo, open an issue, or drop the agent blurb into your AGENTS.md and watch your AI coding assistant finally understand what it's supposed to build next.

The future of issue tracking isn't more dashboards. It's smarter structure. beads_viewer is already there.