Abacus

A powerful terminal UI for visualizing and navigating Beads issue tracking databases.

Overview

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.

Beads Backends: bd vs br

Abacus supports two Beads backends:

Why Two Backends?

beads (bd) is Steve Yegge's original Go-based issue tracker. As Steve continues evolving beads toward GasTown and beyond — with Dolt integration, daemon-based RPC, and advanced features — the architecture has naturally diverged from the simpler SQLite + JSONL model that many tools were built around.

beads_rust (br) was created by Jeffrey Emanuel as a Rust port that freezes the "classic beads" architecture. In his words:

"Rather than ask Steve to maintain a legacy mode for my niche use case, I created this Rust port that freezes the 'classic beads' architecture I depend on... This isn't a criticism of beads; Steve's taking it in exciting directions. It's simply that my tooling needs a stable snapshot of the architecture I built around, and maintaining my own fork is the right solution for that."

Steve Yegge has given his full endorsement of the beads_rust project.

Key differences:

Which Backend Should I Use?

• New projects: We recommend br (beads_rust) for its simplicity and active development
• Existing bd projects: Continue using bd — Abacus fully supports it at v0.38.0
• Mixed usage: Different repositories can use different backends — Abacus auto-detects per project

Support Policy

• bd support is frozen at version 0.38.0 — We will continue supporting bd indefinitely at this version, but will not add support for newer bd versions or features
• br is the path forward — New features and improvements will be developed for the br backend
• 100% JSONL compatible — Both backends use the same .beads/issues.jsonl format, so your data is portable

Preview

Abacus showing a hierarchical tree view of Beads issues with the detail panel displaying comprehensive issue information.

Features

Tree View & Navigation

• 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 v to cycle between All/Active/Ready views to hide closed issues
• Live Search: Filter issues by title with instant results

Bead Management

• Create Beads: Press n for root beads or N for child beads with a streamlined modal
• Edit Beads: Press e to edit existing beads with pre-populated values
• Quick Status Changes: Press s to open the status overlay with single-key selection
• Label Management: Press L to add/remove labels with chip-based UI and autocomplete
• Delete with Confirmation: Press Del to delete beads with a safety confirmation dialog
• Bulk Entry Mode: Press Ctrl+Enter in the create modal to add multiple beads quickly
• Type Auto-Inference: The create modal suggests bead type based on title keywords

Theming

• 20+ Built-in Themes: Including TokyoNight (default), Dracula, Nord, Solarized, Catppuccin, Kanagawa, Gruvbox, One Dark, Rose Pine, GitHub, and more
• Easy Theme Cycling: Press t to cycle forward, T to cycle backward
• Theme Persistence: Your selected theme is saved and restored automatically

Detail Panel

• 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

Interface

• 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

Quick Start

Prerequisites

• Beads backend: At least one of the following must be installed and on your PATH:
• beads_rust (br) — Recommended for new projects
• beads (bd) — Supported at v0.38.0 for existing projects
• Abacus auto-detects which backend is available and prompts if both are present
• Go 1.25.3 or later (only required for go install or building from source)

Installation

Option 1: Homebrew (macOS/Linux) - Recommended

brew tap ChrisEdwards/tap
brew install abacus

Option 2: Install Script (Unix/macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/ChrisEdwards/abacus/main/scripts/install.sh | bash

Option 3: Install Script (Windows PowerShell)

irm https://raw.githubusercontent.com/ChrisEdwards/abacus/main/install.ps1 | iex

Option 4: Go Install

go install github.com/ChrisEdwards/abacus/cmd/abacus@latest

Option 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 build

Prefer prebuilt binaries? Use the release assets, Brew formula, or install script.

Usage

Navigate to any directory containing a Beads project and run:

abacus

The application will automatically load all issues from your .beads/ database.

Command-Line Options

abacus [options]

Options:
  --backend string            Backend to use: bd or br (default: auto-detect)
  --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.

Backend Selection

Abacus supports both beads (bd) and beads_rust (br) backends. See Beads Backends: bd vs br for details on choosing between them.

Auto-detection: On startup, abacus checks which binaries are available: - Only br on PATH → uses br automatically - Only bd on PATH → uses bd automatically - Both available → prompts you to choose (selection saved to .abacus/config.yaml) - Neither available → shows error with installation instructions

Manual override:

# Use --backend flag (overrides config, not saved)
abacus --backend br
abacus --backend bd

# Or configure in .abacus/config.yaml
beads:
  backend: br  # or bd

Status bar indicator: The current backend is always shown in the status bar as [bd] or [br].

CI/Non-interactive environments: Use --backend flag or pre-configure .abacus/config.yaml since the selection prompt requires an interactive terminal.

Version requirements: - br: v0.1.7 or later - bd: v0.30.0 to v0.38.0 (versions > 0.38.0 may work but are not officially supported)

Note on bd version support: If you're using bd version > 0.38.0, Abacus will display a one-time informational notice. The software may still work, but we cannot guarantee compatibility with newer bd features or breaking changes. For the best experience, we recommend migrating to br for new projects.

Detail Panel Relationship Sections

The detail panel shows different types of relationships:

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

Search & Filtering

• Press / to search; results update live while you type. Esc clears the filter.
• Collapsed nodes show [+N] to indicate the number of hidden children.
• The statistics bar (top row) always reflects the currently visible issues.

Auto-Refresh

• Enabled by default at 3 seconds; change with --auto-refresh-seconds N.
• Set 0 to 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.

Update Notifications

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 abacus command
• Direct download users: Press U to auto-update, or download from releases

To disable update checks:

abacus --skip-update-check
# or
export AB_SKIP_UPDATE_CHECK=true

Keyboard Shortcuts

Navigation

Bead Actions

Display

Search & Other

Detail panel focused shortcuts: ↑/↓ or j/k scroll, Ctrl+F/B or PgDn/Up page, g/G or Home/End jump.

Configuration

Abacus can be configured via: - Configuration files (~/.abacus/config.yaml or .abacus/config.yaml) - Environment variables (prefixed with AB_) - Command-line flags

Example configuration:

auto-refresh-seconds: 3
beads:
  backend: br  # or bd (auto-detected if not set)
output:
  format: rich
database:
  path: .beads/beads.db
skip-version-check: false

How It Works

Abacus interfaces with the Beads backend (bd or br) to:

1. Detect available backend and load preference
2. Load all issues from your project via SQLite (fast read path)
3. Perform mutations via CLI commands (create, update, delete, etc.)
4. Build a dependency graph based on parent-child and blocking relationships
5. Render an interactive TUI using Bubble Tea
6. 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 ap