Beads UI

Local UI for the bd CLI – Beads

Collaborate on issues with your coding agent.

Features

- ✨ Zero setup – just run bdui start
- 📺 Live updates – Monitors the beads database for changes
- 🔎 Issues view – Filter and search issues, edit inline
- ⛰️ Epics view – Show progress per epic, expand rows, edit inline
- 🏂 Board view – Blocked / Ready / In progress / Closed columns
- ⌨️ Keyboard navigation – Navigate and edit without touching the mouse

Setup

``sh
npm i beads-ui -g


In your project directory:

See bdui --help for options.

Screenshots

Issues

!Issues view

Epics

!Epics view

Board

!Board view

Environment variables

- BD_BIN: path to the bd binary.
- BDUI_RUNTIME_DIR: override runtime directory for PID/logs. Defaults to
$XDG_RUNTIME_DIR/beads-ui or the system temp dir.
- HOST: overrides the bind address (default 127.0.0.1).
- PORT: overrides the listen port (default 3000).

These can also be set via CLI options: bdui start --host 0.0.0.0 --port 8080

Platform notes

- macOS/Linux are fully supported. On Windows, the CLI uses cmd /c start to
open URLs and relies on Node’s process.kill semantics for stopping the
daemon.

Developer Workflow

- 🔨 Clone the repo and run npm install.
- 🚀 Start the dev server with npm start.
- 🔗 Alternatively, use npm link to link the package globally and run
bdui start from any project.

Debug Logging

- The codebase uses the debug package with namespaces like beads-ui:*.
- Enable logs in the browser by running in DevTools:
- localStorage.debug = 'beads-ui:*' then reload the page
- Enable logs for Node/CLI (server, build scripts) by setting DEBUG:
- DEBUG=beads-ui:* bdui start
- DEBUG=beads-ui:* node scripts/build-frontend.js`

License

MIT