Beadwork (bw) — a fork of Beads Viewer

A fork of beads_viewer, the terminal interface for the Beads issue tracker.

Why this fork?

The original beads_viewer by @Dicklesworthstone is an excellent piece of software. The architecture, the graph analysis engine, the robot protocol for AI agents: it's one of the best TUIs out there. Full credit goes to him for the design and implementation.

Per the project's contribution guidelines, beads_viewer does not accept external pull requests. Feature requests and bug reports are welcome and the maintainer does incorporate community feedback, but the codebase is maintained solely by its author. That's a perfectly valid approach that keeps the project focused and avoids the overhead of reviewing external code.

Beadwork exists because I'm a long-time TUI user (K9s, Emacs) with strong opinions about navigation, keybindings, and information density. Rather than filing feature requests for changes that reflect personal workflow preferences, it made more sense to maintain a fork where I can build exactly the UX I want, and share it with anyone who feels the same way.

No hard feelings toward the original project. This is simply a differentiated offering: same powerful foundation, different UX choices. The goal is to expand the overall user base of the Beads ecosystem by catering to different preferences.

What's different from the original?

• Open to contributions: PRs are welcome here
• Renamed binary: bw instead of bv, so both can coexist on the same machine
• Tree view with split pane: hierarchical issue view with a detail panel alongside
• Sort improvements: persistent sort order, sort indicator in the header
• Opinionated UX defaults: navigation and layout choices shaped by Emacs/K9s habits

What's the same?

All the core functionality from beads_viewer is preserved: list view, kanban board, graph view, insights dashboard, robot mode for AI agents, and the full graph analysis engine (PageRank, betweenness, HITS, critical path, and more). The excellent architecture and design are entirely @Dicklesworthstone's work.

Main split view: fast list + rich details	Kanban board (`b`) for flow at a glance
Insights panel: PageRank, critical path, cycles	Graph view (`g`): navigate the dependency DAG

Installation

Homebrew (macOS/Linux)

brew install vanderheijden86/tap/bw

From source

Requires Go 1.22+.

git clone https://github.com/vanderheijden86/beadwork.git
cd beadwork
make install

This installs the bw binary to your $GOPATH/bin. Make sure that directory is on your PATH.

For best display, use a terminal with a Nerd Font.

---

Feature Highlights

• Instant browsing: zero-latency navigation with Vim keys (j/k), split-view dashboard, Markdown rendering, live reload
• Graph intelligence: 9 graph-theoretic metrics (PageRank, betweenness, HITS, critical path, eigenvector, degree, density, cycles, topo sort) surface hidden project dynamics
• Multiple views: list, tree, kanban board, insights dashboard, graph visualizer, history, plan, flow matrix, attention, and label analytics
• AI-ready robot mode: structured JSON output for AI coding agents with pre-computed graph analysis (--robot-triage, --robot-plan, --robot-insights)
• Time-travel: compare project state across any two git revisions, detect regressions, track progress
• Recipe system: YAML-based view configurations for saved, shareable filter presets
• Static site export: self-contained HTML visualization with force-directed graphs
• Sprint & label analytics: burndown charts, label health scoring, cross-label flow analysis

---

Documentation

Document	Description
User Guide	Complete guide to all views, features, keyboard shortcuts, configuration, and troubleshooting
Architecture & Technical Design	System architecture, algorithm deep-dives, performance specs, and design philosophy
Robot Mode: AI Agent Protocol	AI agent integration, CLI reference, JSON schemas, and the AGENTS.md blurb

---

Quick Start

Interactive TUI

Navigate to any project initialized with bd init and run:

bw

Press ? for keyboard shortcuts or ` (backtick) for the interactive tutorial.

AI Agent Mode

bw --robot-triage          # Full triage: ranked recommendations + project health
bw --robot-next            # Minimal: just the top pick + claim command
bw --robot-triage --format toon   # Token-optimized output for LLMs
bw --robot-help            # Full robot help

See the Robot Mode guide for the complete protocol.

---

Keyboard Quick Reference

Key	Action	Key	Action
j / k	Next / Previous	q / Esc	Quit / Back
g / G	Top / Bottom	Tab	Switch focus
/	Fuzzy search	s	Cycle sort mode
o / c / r / a	Filter: Open / Closed / Ready / All	l	Label picker

Key	View
b	Kanban board
i	Insights dashboard
g	Graph visualizer
E	Tree view
h	History view
a	Actionable plan
f	Flow matrix
t / T	Time-travel / Quick time-travel (HEAD~5)

Full keyboard reference in the User Guide.

---

Acknowledgments & Credits

bv stands on the shoulders of giants. We're deeply grateful to the maintainers and contributors of these exceptional open source projects:

Foundation

Project	Author	Description
Beads	Steve Yegge	The elegant git-native issue tracking system that bv was built to complement

Go Libraries (TUI & CLI)

Library	Author	What We Use It For
Bubble Tea	Charm	The Elm-inspired TUI framework powering all interactive views
Lip Gloss	Charm	Beautiful terminal styling—colors, borders, layouts
Bubbles	Charm	Ready-made components: lists, text inputs, spinners, viewports
Huh	Charm	Interactive forms and prompts for the deployment wizard
Glamour	Charm	Markdown rendering with syntax highlighting in terminal
modernc.org/sqlite	modernc.org	Pure-Go SQLite with FTS5 full-text search for static site export
Gonum	Gonum Authors	Graph algorithms: PageRank, betweenness centrality, SCC
fsnotify	fsnotify	File system watching for live reload
clipboard	atotto	Cross-platform clipboard for copy-to-clipboard features

JavaScript Libraries (Static Viewer)

Library	Author	What We Use It For
force-graph	Vasco Asturiano	Beautiful interactive force-directed graph visualization
D3.js	Mike Bostock / Observable	Data visualization foundation and graph physics
Alpine.js	Caleb Porzio	Lightweight reactive UI framework
sql.js	sql.js contributors	SQLite compiled to WebAssembly for client-side queries
Chart.js	Chart.js contributors	Interactive charts: burndown, priority distribution, heatmaps
Mermaid	Knut Sveidqvist	Dependency graph diagrams in Markdown
DOMPurify	cure53	XSS-safe HTML sanitization
Marked	marked contributors	Fast Markdown parsing
Tailwind CSS	Tailwind Labs	Utility-first CSS framework

Special Thanks

• The entire Charm team for creating the most delightful terminal UI ecosystem in existence. Their libraries make building beautiful CLI tools a joy.
• Vasco Asturiano for the incredible force-graph library and the broader ecosystem of visualization tools.
• Steve Yegge for the vision behind Beads—a refreshingly simple approach to issue tracking that respects developers' workflows.

---

License

MIT License. See LICENSE for details.