Beads UI Setup Guide

Beads UI is a local web interface for the Beads issue tracker. It gives developers a real-time browser view of what agents are working on — without polling, refreshing, or switching to the terminal.

Why Use It

When agents coordinate via Thrum and track tasks with Beads, the developer needs visibility. Running bd list in a terminal works, but Beads UI provides:

Live updates — Issues move across the board as agents claim and close them, with no manual refresh needed
Board view — Kanban columns (Blocked / Ready / In Progress / Closed) with drag-and-drop
Epics view — Expand epics to see child task progress at a glance
Issue detail — Edit titles, descriptions, priorities, dependencies, and comments directly in the browser

The UI calls bd commands under the hood and watches the database for changes, pushing updates over WebSocket. When an agent runs bd close <id>, the card moves to Done in your browser instantly.

Installation

# Install globally from npm
npm install beads-ui -g

# Verify
bdui --help

Requires Node.js 22 or later.

Quick Start

# Navigate to your project (where .beads/ exists)
cd your-project

# Start the UI and open the browser
bdui start --open

The UI is now running at http://localhost:3000. It auto-detects the nearest .beads/ directory by walking up from the current directory.

Tip: If you've just initialized beads or changed the database, run bdui restart to pick up the new state.

Views

Issues View

A filterable, searchable list of all issues. Each row shows the title, status, priority, type, and dependency counts. Click any issue to open the full detail view for inline editing.

Epics View

Shows all epics with progress indicators. Expand a row to see its child tasks and their statuses. Useful for tracking high-level project progress.

Board View

Kanban-style columns:

Blocked	Ready	In Progress	Closed
Tasks waiting on dependencies	Tasks with no blockers	Claimed by an agent	Done

Drag cards between columns to change status. Each column shows a badge with its card count.

Configuration

CLI Options

bdui start              # Start on default port 3000
bdui start --open       # Start and open browser
bdui start --port 3001  # Use a specific port
bdui stop               # Stop the server
bdui restart             # Restart the server
bdui list               # List all running instances

Environment Variables

Variable	Default	Purpose
`BD_BIN`	`bd`	Path to the Beads CLI binary
`PORT`	`3000`	Listen port
`HOST`	`127.0.0.1`	Bind address

Multi-Project Support

Run multiple instances simultaneously — one per project:

# Project A
cd ~/projects/thrum
bdui start --new-instance --open    # auto-selects port 3001

# Project B
cd ~/projects/other-project
bdui start --new-instance --open    # auto-selects port 3002

# See all running instances
bdui list

Each instance watches its own project's Beads database independently.

Worktree Support

Beads UI works from git worktrees that have a .beads/redirect file pointing to the main repo's .beads/ directory. The redirect is followed automatically — no extra configuration needed.

Sandbox Mode

Beads UI runs bd commands with --sandbox by default, which skips auto-push/pull overhead for faster responses. To disable this (e.g., if you need real-time sync), set BDUI_BD_SANDBOX=0.

Typical Developer Workflow

Start Beads UI in your project: bdui start --open
Start your Thrum agents (coordinator, implementers, etc.)
Watch the board as agents discover tasks via bd ready, claim them with bd update --status=in_progress, and close them with bd close
Use the issue detail view to add comments, adjust priorities, or edit descriptions while agents work
Check the epics view for high-level progress across the project

The board updates live — no need to refresh. When an agent sends a Thrum message saying "Completed task X", you'll see the card move to the Closed column at the same time.

Debug Logging

# Server-side debug output
DEBUG=beads-ui:* bdui start

# Browser-side (in DevTools console)
localStorage.debug = 'beads-ui:*'