BeadsBoard

Standalone Kanban web UI for the Beads (bd) issue tracker with Dolt backend.

┌────────────────────────────────────────────────────────────┐
│  BB BeadsBoard    [FlowInCash ▾]              ● Connected  │
├────────────────────────────────────────────────────────────┤
│  🔍 Search...  [P0][P1][P2][P3]  Labels▾  Projects▾       │
├──────────────┬───────────────┬──────────┬──────────────────┤
│  Open   (4)  │ In Progress(2)│Review (1)│   Done    (8)   │
│ ┌──────────┐ │ ┌──────────┐  │┌────────┐│ ┌──────────┐    │
│ │PROJ-12   │ │ │PROJ-8    │  ││PROJ-5  ││ │PROJ-1    │    │
│ │P0 🔴    │ │ │P1 🟠    │  ││P2 🟡  ││ │P3        │    │
│ │Fix login │ │ │Add OAuth │  ││Review  ││ │Init      │    │
│ └──────────┘ │ └──────────┘  ││deploy  ││ └──────────┘    │
└──────────────┴───────────────┴──────────┴──────────────────┘

Features

• Kanban columns by status with drag-and-drop
• Database switcher — connects to any Dolt database on the local sql-server
• Project discovery — auto-scans for .beads/ dirs under your projects root
• Priority color coding — P0 red, P1 orange, P2 yellow, P3 gray
• Issue detail panel — click any card to view/edit inline
• Inline quick-edit — click title or description to edit in place
• Dependency visualization — see blocked-by and blocks relationships
• Label & priority filters, full-text search
• Activity feed — recent changes panel + per-issue history tab
• Dark mode (default, only mode)
• Localhost only, no auth required

Quick Start

Prerequisites

1. Dolt installed — install dolt
2. Node.js 22+ and npm

Setup

# Clone / copy the repo
cd /media/bob/I/AI_Projects/BeadsBoard

# Install all dependencies (monorepo)
npm install

# Configure environment
cp .env.example .env

Start a Dolt sql-server

In any project that uses Beads:

cd /media/bob/I/AI_Projects/FlowInCash
dolt sql-server
# Dolt starts on port 3306 (MySQL-compatible)

Run BeadsBoard

# From BeadsBoard root
npm run dev

Open http://localhost:5173 — click the database picker in the header to connect.

Environment Variables

Variable	Default	Description
PORT	3001	API server port
HOST	127.0.0.1	Bind host (localhost only)
DOLT_HOST	127.0.0.1	Dolt server host
DOLT_PORT	3306	Dolt server port
DOLT_USER	root	Dolt user
DOLT_PASSWORD	``	Dolt password (usually empty locally)
DOLT_DATABASE	``	Auto-connect to this DB on startup
PROJECTS_ROOT	/media/bob/I/AI_Projects	Root dir for .beads discovery

Architecture

packages/
├── server/          Express 5 API (port 3001)
│   ├── config/      Dolt pool + env
│   ├── services/    Issue CRUD, project discovery, activity
│   ├── routes/      REST endpoints
│   └── middleware/  Error handling
└── client/          React 19 + Vite (port 5173)
    ├── types/       Shared types + constants
    ├── services/    Fetch API client
    ├── store/       React state (no external store)
    ├── hooks/       Data loading + polling
    └── components/  Board, filters, detail panel, layout

How it Connects to Dolt

BeadsBoard talks to the standard bd-managed Dolt database directly via MySQL protocol (mysql2 driver). It reads bd's native tables:

• issues — the issue list
• dependencies — blocked_by/blocks relationships
• events / activity — audit log (whichever table exists)

The bd CLI and BeadsBoard share the same database — run bd list and the board shows the same data.

Dolt sql-server Tips

# Start with specific config
dolt sql-server --port 3306 --user root

# List available databases from MySQL client
mysql -u root -h 127.0.0.1 -e "SHOW DATABASES"

# The db name is usually the directory name of your project