beads-ui — Summary

beads-ui (mantoni/beads-ui) is a local web UI for Steve Yegge's Beads CLI (bd) that provides a visual kanban/issue board for AI coding agent workflows. It runs as a local Node.js server (bdui start) and serves a JavaScript single-page application at localhost:3000 that reads the .beads/ database in real time via a WebSocket connection. The UI ships three views — Issues (filter/search/inline edit), Epics (progress per epic, expandable rows), and Board (Blocked/Ready/In-progress/Closed columns) — with full keyboard navigation and multi-workspace switching. It does not embed any AI agent logic, prompts, or hooks; it is purely a visualization and editing companion for the Beads JSONL database that Gas Town and SuperBeads use for work tracking.

Differs from seeds: unlike all 11 seeds, beads-ui adds NO AI agent primitives (no commands, skills, hooks, subagents, or MCP). It is Archetype 4 (markdown scaffold) adjacent but not document-based — it is a pure local tooling companion. Closest to claude-conductor's "zero primitives, value is the tooling" philosophy, but for a specific work-tracking format rather than Claude.md templates.

beads-ui — Origin and Philosophy

Origin

beads-ui is authored by Tobias Nikkel (GitHub: mantoni), 621 stars, 13 contributors, last push April 2026. It is an independent UI companion for Steve Yegge's Beads CLI — not officially part of the gastownhall organization but directly listed in the Beads README as the recommended local UI.

Philosophy

Pure zero-friction local visualization. The project README opens with:

"Local UI for the bd CLI – Beads — Collaborate on issues with your coding agent."

The "collaborate with your coding agent" framing is key: the human uses the board UI while the AI agent uses the bd CLI. They share the same .beads/issues.jsonl file — the UI reads it and the agent writes to it. The UI provides the human-legible board view that AI tools cannot (agents should not use interactive TUIs).

Key Design Choices

• Zero setup: npm i beads-ui -g then bdui start --open — no config, no auth
• Live updates: WebSocket connection monitors Beads database for changes as the agent works
• Keyboard navigation: full keyboard control, no mouse required (CI/CD-compatible workflow)
• Multi-workspace: auto-registers workspaces; switch between projects via dropdown

Supported Beads Features

Issues view, Epics view, Board view (Blocked/Ready/In-progress/Closed columns), inline editing in all views.

beads-ui — Architecture

Distribution

npm global package: npm i beads-ui -g

Required Runtime

• Node.js (version not explicitly stated; standard npm package)
• beads bd CLI (installed separately via curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash)
• A project with .beads/ directory (initialized via bd init)

CLI Binary

bdui — installed via npm global. Key subcommands:

• bdui start — start local server
• bdui start --open — start and open browser
• bdui start --host 0.0.0.0 --port 8080 — bind/port options
• bdui --help

Server Architecture

Node.js server (bdui)
    ├── server/ — Express/HTTP server
    ├── app/    — Frontend SPA (vanilla JS)
    │   ├── main.js         — main app logic
    │   ├── router.js       — view routing
    │   ├── protocol.js     — WebSocket protocol
    │   └── data/           — local data handling
    └── bin/    — CLI entry

Frontend: Vanilla JavaScript (no React/Vue/Svelte). Tests use Vitest.

Runtime Data Flow

.beads/issues.jsonl (written by bd CLI / agent)
        ↓ file watcher
bdui Node.js server
        ↓ WebSocket
Browser SPA
        ↓ user edits
bdui server calls bd CLI to write changes
        ↓
.beads/issues.jsonl (updated)

Environment Variables

• BD_BIN: path to bd binary override
• BDUI_RUNTIME_DIR: runtime directory for PID/logs (default: $XDG_RUNTIME_DIR/beads-ui)
• HOST: bind address (default 127.0.0.1)
• PORT: listen port (default 3000)

beads-ui — Components

No AI Agent Primitives

beads-ui ships zero commands, skills, hooks, subagents, or MCP servers. It is a pure local web application.

Frontend Views

Frontend Components (JavaScript)

Server Components

Key Interactions

• Live updates: server/ watches .beads/issues.jsonl with a file watcher; pushes changes to browser via WebSocket
• Multi-workspace: server auto-registers workspaces; browser dropdown switches between registered projects
• Inline edit: Browser sends edits → server calls bd update <id> --field value via child_process

beads-ui — Uniqueness and Positioning

Differs from Seeds

beads-ui has no parallel in any of the 11 seeds. Seeds focus on agent behavior (prompts, skills, hooks, MCP servers). beads-ui is a visualization companion for a specific issue-tracking format (Beads JSONL).

The closest analogy in the seed corpus is taskmaster-ai which ships a web UI for its task.json — but taskmaster bundles its UI as part of the framework. beads-ui is standalone, built by a different author, for a different issue format (Beads vs taskmaster JSON).

Among the seeds, the least primitive-heavy is claude-conductor (15 templates, no skills/hooks/MCP). beads-ui goes further: zero framework primitives — it is purely tooling.

Positioning

beads-ui occupies the "human-facing observation layer" niche in the Beads/Gas Town ecosystem. While AI agents operate via bd CLI, humans get a browser-based board. This separation of concerns (CLI for agents, browser for humans) is architecturally clean and unusual in the AI coding agent space.

Observable Failure Modes

1. Beads version coupling: beads-ui calls bd CLI directly; breaking changes in bd can silently break the UI.
2. File watcher reliability: Large .beads/issues.jsonl files or rapid concurrent agent writes could cause WebSocket update storms.
3. No authentication: localhost:3000 is unprotected — running on a shared machine exposes all beads data.

Cross-References

• Gas Town (gastownhall/gastown) — the primary multi-agent orchestrator that uses Beads for work tracking; beads-ui is the human-facing companion
• beads (steveyegge/beads) — the underlying JSONL issue tracker that beads-ui visualizes
• SuperBeads-Wiggum — another Beads-integrated framework; can use beads-ui for visualization