A powerful terminal UI for visualizing and navigating Steve Yegge's awesome Beads issue tracking project.
Abacus transforms your Beads issue database into an interactive, hierarchical tree view right in your terminal. It provides an intuitive interface for exploring complex dependency graphs, viewing issue details, and understanding project structure at a glance.
Abacus showing a hierarchical tree view of Beads issues with the detail panel displaying comprehensive issue information.
- Hierarchical Tree View: Visualize parent-child relationships and dependencies in an expandable tree structure
- Smart Sorting: Automatically prioritizes in-progress and ready-to-work issues
- Status Indicators: Color-coded icons show issue status at a glance
◐In Progress (cyan)○Open/Ready (white)✔Closed (gray)⛔Blocked (red)
- Multi-Parent Support: Tasks can belong to multiple parent epics:
- Tasks appear under ALL their parent epics in the tree
*suffix indicates an item has multiple parents- Cross-highlighting: selecting one instance highlights all duplicates
- Expansion state is shared across all instances
- View Mode Filtering: Press
vto cycle between All/Active/Ready views to hide closed issues - Live Search: Filter issues by title with instant results
- Create Beads: Press
nfor root beads orNfor child beads with a streamlined modal - Edit Beads: Press
eto edit existing beads with pre-populated values - Quick Status Changes: Press
sto open the status overlay with single-key selection - Label Management: Press
Lto add/remove labels with chip-based UI and autocomplete - Delete with Confirmation: Press
Delto delete beads with a safety confirmation dialog - Bulk Entry Mode: Press
Ctrl+Enterin the create modal to add multiple beads quickly - Type Auto-Inference: The create modal suggests bead type based on title keywords
- 20+ Built-in Themes: Including TokyoNight (default), Dracula, Nord, Solarized, Catppuccin, Kanagawa, Gruvbox, One Dark, Rose Pine, GitHub, and more
- Easy Theme Cycling: Press
tto cycle forward,Tto cycle backward - Theme Persistence: Your selected theme is saved and restored automatically
- Rich Detail Panel: View comprehensive issue information including:
- Metadata (status, type, priority, labels, timestamps)
- Full description with markdown rendering
- Notes section with implementation details
- Relationship sections (see below)
- Comments with timestamps
- Dual-Pane Interface: Navigate the tree while viewing detailed information
- Smart Layout: Responsive design with text wrapping and viewport management
- Statistics Dashboard: Real-time counts of total, in-progress, ready, blocked, and closed issues
- Exit Summary: See session duration and bead statistics when you quit
- Beads CLI v0.24.0 or later installed and initialized in your project (
bd --version) - Go 1.25.3 or later (only required for
go installor building from source)
Option 1: Homebrew (macOS/Linux) - Recommended
brew tap ChrisEdwards/tap
brew install abacusOption 2: Install Script (Unix/macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/ChrisEdwards/abacus/main/scripts/install.sh | bashOption 3: Install Script (Windows PowerShell)
irm https://raw.githubusercontent.com/ChrisEdwards/abacus/main/install.ps1 | iexOption 4: Go Install
go install github.com/ChrisEdwards/abacus/cmd/abacus@latestOption 5: Download Binary
Download the latest release for your platform from GitHub Releases.
Option 6: Build from Source
git clone https://github.com/ChrisEdwards/abacus.git
cd abacus
make buildPrefer prebuilt binaries? Use the release assets, Brew formula, or install script.
Navigate to any directory containing a Beads project and run:
abacusThe application will automatically load all issues from your .beads/ database.
abacus [options]
Options:
--db-path string Path to the Beads database file
--auto-refresh-seconds int Auto-refresh interval in seconds (0 disables; default: 3)
--output-format string Detail panel style: rich, light, plain (default: "rich")
--skip-version-check Skip Beads CLI version validation (or set AB_SKIP_VERSION_CHECK=true)
--skip-update-check Skip checking for updates at startup (or set AB_SKIP_UPDATE_CHECK=true)Key workflows are summarized below—run abacus --help anytime for the full flag list.
The detail panel shows different types of relationships:
| Section | Meaning | Description |
|---|---|---|
| Part Of | Parent epics | Epics/tasks this issue belongs to |
| Subtasks | Child tasks | Work items underneath this issue |
| Must Complete First | Blockers | Issues that block this one from starting |
| Will Unblock | Downstream | Issues waiting on this one to complete |
| Related | Soft links | Issues related but not blocking |
| Discovered From | Origin | Issues that led to discovering this one |
Items within each section are sorted intelligently:
- Subtasks: In-progress → ready (high-impact first) → blocked (closest to ready) → closed
- Blockers: Items you can work on now appear first
- Will Unblock: Items that become ready first appear first
- Press
/to search; results update live while you type.Escclears the filter. - Collapsed nodes show
[+N]to indicate the number of hidden children. - The statistics bar (top row) always reflects the currently visible issues.
- Enabled by default at 3 seconds; change with
--auto-refresh-seconds N. - Set
0to disable background refresh if you want to control reloads manually. - Auto-refresh preserves cursor, expanded nodes, and search filters.
- If a refresh fails, an error toast appears briefly in the bottom-right corner.
Abacus checks for updates when you launch it. If a new version is available, you'll see a toast notification in the bottom-right corner:
- Homebrew users: The toast shows
brew upgrade abacuscommand - Direct download users: Press
Uto auto-update, or download from releases
To disable update checks:
abacus --skip-update-check
# or
export AB_SKIP_UPDATE_CHECK=true| Action | Keys | Description |
|---|---|---|
| Navigate | ↑/k ↓/j |
Move cursor up/down |
| Expand/Collapse | →/l ←/h or Space |
Expand/collapse nodes |
| Jump | Home/End |
Jump to first/last item |
| Page | PgUp/PgDn |
Page up/down in tree |
| Detail Panel | Enter |
Toggle detail panel |
| Switch Focus | Tab |
Switch between tree and detail |
| Action | Keys | Description |
|---|---|---|
| New Root Bead | n |
Create a new root-level bead |
| New Child Bead | N |
Create bead under selected parent |
| Edit Bead | e |
Edit selected bead |
| Change Status | s |
Open status overlay |
| Manage Labels | L |
Open labels overlay |
| Delete Bead | Del |
Delete bead (with confirmation) |
| Copy ID | c |
Copy bead ID to clipboard |
| Action | Keys | Description |
|---|---|---|
| Cycle Theme | t/T |
Cycle through themes (forward/backward) |
| Cycle View | v/V |
Cycle view modes (All/Active/Ready) |
| Refresh | r |
Manual refresh |
| Help | ? |
Show keyboard shortcuts overlay |
| Action | Keys | Description |
|---|---|---|
| Search | / |
Enter search mode |
| Clear/Cancel | Esc |
Clear search or close overlay |
| Quit | q or Ctrl+C |
Exit application |
Detail panel focused shortcuts: ↑/↓ or j/k scroll, Ctrl+F/B or PgDn/Up page, g/G or Home/End jump.
Abacus can be configured via:
- Configuration files (
~/.abacus/config.yamlor.abacus/config.yaml) - Environment variables (prefixed with
AB_) - Command-line flags
Example configuration:
auto-refresh-seconds: 3
output:
json: false
format: rich
database:
path: .beads/beads.db
skip-version-check: falseSet output.json: true, AB_OUTPUT_JSON=true, or pass --json-output to print all issues as JSON (useful for scripting) and skip the TUI entirely. In JSON mode, startup animations are disabled so output stays machine-friendly.
Abacus interfaces with the Beads CLI to:
- Load all issues from your project with
bd list --json - Fetch full details for each issue with
bd show - Build a dependency graph based on parent-child and blocking relationships
- Render an interactive TUI using Bubble Tea
- Display a short-lived, witty spinner summarizing progress while the data loads
The graph automatically identifies root nodes (issues with no parents or deepest parents in the hierarchy) and organizes the tree to minimize visual depth while accurately representing all relationships.
Internally the app follows Bubble Tea's Elm-inspired update/view cycle with domain, graph, and config layers separated for testability.
Abacus is built with:
- Bubble Tea: The Elm Architecture for Go TUIs
- Bubbles: TUI components (viewport, text input)
- Lipgloss: Style definitions and layout
- Glamour: Markdown rendering for descriptions
The codebase is organized into logical sections:
- Style definitions (colors, text styles, layout styles)
- Data structures (Issue, Node, Stats)
- Graph building logic (dependency resolution, tree construction)
- TUI logic (Bubble Tea Model/View/Update pattern)
- Rendering utilities (text wrapping, formatting, viewport management)
While the Beads CLI is powerful for managing issues, complex projects with many dependencies can be difficult to visualize. Abacus solves this by:
- Showing the full project structure at a glance
- Making dependencies and blockers immediately visible
- Providing context-aware navigation
- Offering rich, formatted issue views without leaving the terminal
Having issues? See TROUBLESHOOTING.md for quick fixes.
- Installation issues
- Database connectivity
- Display problems
- Performance tuning
- Terminal compatibility
Contributions are welcome! Areas for improvement:
- Additional filtering options (by status, priority, labels)
- Export views (to markdown, JSON, etc.)
- Bulk operations on selected issues
- Integration with git for change tracking
- Performance optimizations for very large issue sets
- Automated dependency management improvements (Dependabot is configured via
.github/dependabot.ymland PRs welcome for additional ecosystems)
See the references below for a quick map of the codebase.
# Clone the repository
git clone https://github.com/yourusername/abacus.git
cd abacus
# Run tests
make test
# Run linter
make lint
# Build
make buildFor information about creating releases, see RELEASING.md.
cmd/abacus/: CLI entrypoint and flag parsinginternal/ui/: Bubble Tea models, tree/detail rendering, search, auto-refreshinternal/config/: Viper-backed configuration (env, files, overrides)internal/graph/: Dependency graph construction and sortinginternal/beads/: Thin wrapper overbd list/show
This project is licensed under the MIT License.
Built with excellent TUI libraries from Charm. Designed for use with Beads.