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
• 🔀 Multi-workspace – Switch between projects via dropdown, auto-registers workspaces

Setup

npm i beads-ui -g
# In your project directory:
bdui start --open

See bdui --help for options.

Screenshots

Issues

Epics

Board

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