beads-ui: a local board, issues and epics view for the bd CLI

What beads-ui adds to a Beads issue database

Beads is an issue tracker driven by the `bd` command line tool. That is a reasonable fit for an agent that reads and writes issues through a shell, and a poor fit for a person who wants to see the shape of the work at a glance. beads-ui exists to close that gap: it is a local UI for the `bd` CLI, and the README frames its purpose as collaborating on issues with your coding agent.

The intended user is therefore narrow. You already have a Beads database in a project directory, you already run `bd`, and you want a second surface on the same data rather than a second source of truth. The README lists the views it provides: Issues for filtering, searching and inline editing; Epics for progress per epic with expandable rows; and a Board with Blocked, Ready, In progress and Closed columns. The Board is the piece a terminal listing does not give you, because blocked-versus-ready is a judgement you make by scanning, not by querying.

It is not a hosted service and it is not a replacement for Beads itself. The package description calls it a local UI, and the topics attached to the repository are agent, issue-tracker, local-first and ai-tools. Nothing in the README suggests a server component that several people connect to from different machines.

How the local server, websocket and views fit together

The architecture visible in the repository is a small Node server plus a browser frontend. package.json lists express and ws as runtime dependencies, which points at an HTTP server that also holds a websocket connection open to the page. The README's Live updates feature states that the tool monitors the beads database for changes, so the flow is: the `bd` CLI writes to the database, the server notices, and the browser receives the update without a manual reload.

The frontend is built from lit-html templates and bundled with esbuild, which the build script `scripts/build-frontend.js` runs. Markdown in issue bodies is rendered with marked, and dompurify is a dependency, so rendered HTML is sanitized before it reaches the page. That pairing matters if issue text can come from an agent: an agent writing Markdown into an issue is a realistic path for untrusted content.

The CLI itself lives in `bin/bdui.js`, and the server entry is `server/index.js`. The README describes the CLI as managing a daemon, with a runtime directory for PID and log files, which is why there are separate start and stop semantics rather than a foreground process only. Multi-workspace support is implemented as a dropdown in the UI that switches between projects and auto-registers workspaces, so one running instance can cover more than one repository.

Installing beads-ui and running your first board

The README gives a two-step setup. The package is installed globally from npm, and the CLI is then started from inside your project directory. Node 22 or newer is required, per the engines field in package.json.

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

The `--open` flag asks the CLI to open the UI in your browser. The README points to `bdui --help` for the remaining options rather than listing them all. If the run succeeds, you should land on the Issues view for the workspace you started it in.

The listen address and port are configurable, either through environment variables or through CLI options. The defaults are 127.0.0.1 and port 3000, so the UI is bound to loopback unless you change it.

bdui start --host 0.0.0.0 --port 8080

If the `bd` binary is not on the path the server sees, the README documents `BD_BIN` as the way to point at it. Runtime files such as the PID and logs go to `$XDG_RUNTIME_DIR/beads-ui` or the system temp directory, and `BDUI_RUNTIME_DIR` overrides that location. When something misbehaves, the debug package is wired through namespaced loggers; the README gives two ways to turn them on.

DEBUG=beads-ui:* bdui start

For the browser side, the README instructs setting `localStorage.debug = 'beads-ui:*'` in DevTools and reloading the page. Those two switches cover the server and the frontend separately, which is useful because a missing update on screen and a failed database read look identical until you check both.

Where beads-ui is the wrong tool

The clearest limitation is the one stated in the README itself: macOS and Linux are fully supported, while Windows support is described in terms of the mechanisms it relies on. The CLI uses `cmd /c start` to open URLs and depends on Node's `process.kill` semantics to stop the daemon. That is a description of how it works, not a statement that Windows is tested to the same degree, and anyone on Windows should treat the daemon lifecycle as the part most likely to behave differently.

The second limitation is scope. beads-ui is a view over a Beads database, so if your team tracks work in GitHub Issues, Jira or a shared spreadsheet, this tool has nothing to show you. It does not create a database, and the README does not describe any import path from another tracker.

The third is the local-first assumption. The default bind address is 127.0.0.1, which means one machine. The README does document `--host 0.0.0.0`, so you can expose it, but there is no mention of authentication, user accounts or access control anywhere in the README. Exposing an issue database on a network interface without those is a decision the documentation does not help you make, and the README is silent on what protects the endpoint once it is reachable.

Finally, the UI is only as current as the database it watches. If an agent writes issues through a different path than the `bd` CLI, the monitoring described in the README has nothing to observe.

beads-ui compared with a terminal client

The obvious alternative is staying in the terminal, and the related searches include a phrase for exactly that: a Beads TUI. The difference is not cosmetic. A terminal client renders one query result at a time and you re-run it to see changes; beads-ui keeps a websocket open and pushes updates as the database changes, which is the point of the Live updates feature. That matters when an agent is writing issues while you are reading them.

The second difference is the Board. A TUI can draw columns, but the reason to leave the terminal here is inline editing across a grid of cards plus a workspace dropdown for switching projects. The README's Multi-workspace feature auto-registers workspaces, so the switching cost between repositories is a dropdown selection rather than a restart.

The trade-off runs the other way too. A browser tab is a heavier thing to keep open than a shell, the server is a Node process that has to be started and stopped, and the daemon and PID file add a moving part that a pure terminal tool does not have. If your work is a single query repeated occasionally, the terminal wins on overhead. beads-ui earns its place when you are watching a board change while an agent works.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-08-11. Releases are frequent: v0.12.4 on 2026-07-26, v0.12.5 on 2026-08-01, and v0.12.6 on 2026-08-11, the same day as the last push. That cadence is visible in the release list, and it is the only maintenance signal available here; nothing in the README states a support policy or a compatibility promise.

The versioning is semver, per the badge in the README, and the release script runs the full check suite before publishing: lint, type check, tests and a prettier check are chained in the `preversion` script. For a global CLI that is a reasonable gate, though it says nothing about what a minor bump may change in the UI.

The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the code. That is a statement about the licence text as identified in the repository, not legal advice; if you embed the tool in something you ship, read the LICENSE file yourself.

The practical upgrade cost is low. It is a global npm package with a single binary and no database of its own, so upgrading means reinstalling the package and restarting the daemon. The risk to check on each upgrade is the Node engine floor, currently 22 or newer, and whether the UI's assumptions about your Beads database version still hold. The README does not document a rollback procedure, so pinning a known-good version is the only fallback the documentation supports.

Editorial conclusion

Adopt beads-ui if your project already keeps issues in a Beads database and you want a browser view that updates as the database changes, with a board that separates blocked, ready, in progress and closed work. Skip it if you do not use the bd CLI, since the README describes it purely as a UI for that CLI, or if you need a hosted tracker that several people reach over the network. Before rolling it out, verify the bd binary location your environment needs via BD_BIN, confirm the port 3000 default does not collide with something else, and check the default bind address 127.0.0.1 still matches how you intend to reach it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mantoni/beads-ui on GitHub
4. README
5. Releases