beads-enhanced-ui
v0.1.4
Published
Enhanced local UI for Beads with improved epic rows, status labels, and UX refinements.
Maintainers
Readme
Features
- ✨ Zero setup – just run
bdui start --open - 📺 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 install -g beads-enhanced-ui
# Run UI in your project directory:
bdui start --openSee bdui --help for options.
Screenshots
Issues

Epics

Board

Environment variables
BD_BIN: path to thebdbinary.BDUI_RUNTIME_DIR: override runtime directory for PID/logs. Defaults to$XDG_RUNTIME_DIR/beads-uior the system temp dir.HOST: overrides the bind address (default127.0.0.1).PORT: overrides the listen port (default3050).
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 startto open URLs and relies on Node’sprocess.killsemantics for stopping the daemon.
Developer Workflow
- 🔨 Clone the repo and run
npm install. - 🚀 Start the dev server with
npm start. - 🔗 Alternatively, use
npm linkto link the package globally and runbdui startfrom any project.
Coverage Commands
npm run allruns lint, typecheck, the full Vitest suite, and the stable frontend coverage gate vianpm run test:coverage:app.npm run test:coverage:appmeasures browser-sidejsdomcoverage forapp/**/*.js.npm run test:coverageruns full-suite coverage across all Vitest projects, so it reflects repo-wide test health rather than only the frontend gate.
Debug Logging
- The codebase uses the
debugpackage with namespaces likebeads-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 startDEBUG=beads-ui:* node scripts/build-frontend.js
License
MIT
