beads-ui: A Local Browser UI for the bd Issue CLI

The gap beads-ui fills: a browser over a CLI-only tracker

Beads is a command line issue tracker, invoked as bd. The README describes beads-ui as a "Local UI for the bd CLI" whose purpose is to "Collaborate on issues with your coding agent." That framing matters. The tool does not store issues itself and does not define an issue format. It reads what bd already wrote and renders it. If bd is not installed and has not created a database in your project, beads-ui has nothing to show. The audience is therefore narrow and specific: developers who have already adopted bd, and who want to filter, search, and edit those issues in a browser instead of typing CLI commands for every change. The multi-workspace feature suggests a second audience, people running several Beads projects on one machine who want a dropdown to switch between them rather than a separate terminal per project.

What the three views actually do

The README lists three views. The Issues view supports filtering and searching, with inline editing. The Epics view shows progress per epic, expandable rows, and inline editing. The Board view organises issues into four columns: Blocked, Ready, In progress, and Closed. Live updates are listed as a feature: the UI "Monitors the beads database for changes," so an edit made by your coding agent through bd should appear in the browser without a manual refresh. Keyboard navigation is also claimed, described as navigating and editing "without touching the mouse." What the README does not state is how the board columns are derived. Whether Blocked and Ready are computed from dependency links inside the Beads data model or from status fields is not explained in the supplied material, and that distinction changes how much the board view can be trusted as a planning surface. Treat the board as a view to verify against your own data before relying on it.

Install and first run

Setup is two commands. Install globally:

npm i beads-ui -g

Then, from your project directory:

bdui start --open

The README points to bdui --help for the remaining options. Configuration is available through environment variables or equivalent CLI flags. BD_BIN sets the path to the bd binary, which is the hook you need if bd is not on your PATH. BDUI_RUNTIME_DIR overrides the runtime directory for PID and log files, defaulting to $XDG_RUNTIME_DIR/beads-ui or the system temp directory. HOST overrides the bind address and defaults to 127.0.0.1. PORT overrides the listen port and defaults to 3000. The README gives this example of the flag form: bdui start --host 0.0.0.0 --port 8080. Because the tool runs a daemon, there is a runtime directory holding a PID file, and stopping the daemon relies on Node process.kill semantics on Windows. That is the kind of detail that bites people who expect a service manager.

Where it breaks: platform quirks and the bind address

The platform notes are the most honest part of the README. macOS and Linux are "fully supported." Windows is described as working through cmd /c start for opening URLs and Node process.kill for stopping the daemon. That is a weaker guarantee than the macOS and Linux statement, and it is the first thing to test if your team is mixed. The second constraint is the default bind address. HOST defaults to 127.0.0.1, which keeps the UI on the local machine. The README shows how to widen it to 0.0.0.0. Doing so exposes an interface that can edit your issue database to anything that can reach the port, and the material says nothing about authentication. There is no mention of a token, a password, or TLS. If you set --host 0.0.0.0, you are making that decision yourself. The third limitation is structural: beads-ui is a view over bd, so any capability bd does not record cannot appear here. There is no mention of importing issues from GitHub, Jira, or a CSV file, and no mention of notifications, sprints, or reporting beyond epic progress.

Debugging a UI that shows nothing

When the browser opens but the issue list is empty, the failure is almost always upstream of the UI: bd is not found, or it is pointed at a different database than the one you expect. The README documents the diagnostic path. The codebase uses the debug package with namespaces like beads-ui:*. For server and CLI logs, set the environment variable when starting: DEBUG=beads-ui:* bdui start. For browser-side logs, run localStorage.debug = 'beads-ui:*' in DevTools and reload the page. If BD_BIN is wrong, setting it explicitly is the direct fix. The runtime directory, configurable through BDUI_RUNTIME_DIR, is where PID and log files land, so that is the place to look when the daemon appears to be running but the port is unresponsive. This is a reasonable debugging story for a small tool, and it is documented rather than left to guesswork.

How it compares to a self-hosted tracker

The obvious alternative is a self-hosted issue tracker such as a local Redmine, Gitea, or GitLab instance. The difference in approach is where the data lives and who owns the schema. Those systems are the system of record: issues are created in their database, and every integration reads from them. beads-ui is the opposite. It owns no data. It reads the Beads database that bd maintains and renders it. That means no migration, no backup policy for a second datastore, and no divergence between what the CLI sees and what the browser shows, because they are the same source. It also means you inherit every limitation of the bd data model with no way to extend it from the UI. A second alternative is simply not using a UI at all and staying in the terminal with bd. For a single developer on a single project, that is a defensible choice, and beads-ui is a convenience rather than a requirement. The multi-workspace dropdown is the feature that tilts the decision, because switching projects in a browser is faster than opening a new terminal per repository.

Maintenance, licensing, and what to verify before adopting

The project is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and licence text are preserved. That is a permissive, low-friction choice, and nothing in the supplied material suggests dual licensing or a contributor agreement that would complicate it. This is not legal advice; check the LICENSE file in the repository for the binding terms. On maintenance, the release history shows a steady cadence: v0.12.4 on 2026-07-26, v0.12.5 on 2026-08-01, and v0.12.6 on 2026-08-11, with the last push matching the most recent release. The version numbers remain in the 0.x range, which under semantic versioning conventions signals that the API and CLI surface may still change between minor releases. The upgrade cost is low in practice: the package is installed globally, so an upgrade is a single npm command, and the configuration surface is four environment variables. The risk is not upgrade effort but coupling. beads-ui tracks the bd CLI, so a change in bd's database format or command behaviour is a change beads-ui has to follow. Before adopting, confirm that bd is installed and that a database exists in your project, decide whether 127.0.0.1 is sufficient or whether you need --host, and verify that the Board view's Blocked and Ready columns match how your team actually classifies work.

Editorial conclusion

Adopt beads-ui if your project already tracks issues through the bd CLI and you want a browser view of the same database without a hosted service. Skip it if you do not use Beads, since there is no import path from other trackers and nothing to display without a bd database. Before committing, run bdui start --open in one project, set DEBUG=beads-ui:* to confirm the server is finding the database, and check that the default bind address 127.0.0.1 matches your threat model rather than widening it with --host 0.0.0.0.

Official sources

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