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
```sh
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
