# BeadBoard **A live operations console for multi-agent work. See what every agent is doing, what's blocked, and where to intervene.** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Built on Beads](https://img.shields.io/badge/built%20on-Beads-blue)](https://github.com/steveyegge/beads) ![BeadBoard social view — grouped task cards with agent context and dependency chains](docs/screenshots/image-9.png) --- Your agents are doing work. Who's watching? BeadBoard gives you eyes on multi-agent swarms: which tasks are in flight, which are blocked and why, what the dependency topology looks like, and where you need to step in. It reads [Beads](https://github.com/steveyegge/beads) issue files from your repos and renders them as a unified shell — Social, Graph, and Activity lenses — that updates in realtime as agents work. It's designed agents-first. Agents use the `bd` CLI to claim tasks, post progress, and send structured mail to each other. You watch from the dashboard and intervene when needed. --- ## Quick Start **Prerequisites:** Node.js 20 LTS, npm 7+ ```bash git clone https://github.com/zenchantlive/beadboard.git cd beadboard npm install npm install -g . cd ~/my-project bd init beadboard start ``` Open [http://localhost:3000](http://localhost:3000). --- ## Dolt (recommended) BeadBoard works with [Dolt](https://github.com/dolthub/dolt) for version-controlled issue history, SQL queries across projects, and reliable multi-agent sync. It's the right backend for real work. ```bash # macOS brew install dolt # Linux / Windows go install github.com/dolthub/dolt/go/cmd/dolt@latest # or: curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash ``` Then start the dashboard with Dolt: ```bash beadboard start --dolt # or manage Dolt separately: bd dolt start ``` Without Dolt, BeadBoard reads `.beads/issues.jsonl` directly — enough to explore, but you'll want Dolt for anything serious. --- ## Features ### Social View — your swarm at a glance Task cards organized by status, with dependency chains, thread context, and agent assignments surfaced inline. Built for scanning active work across many agents without losing the thread. ![Social view showing grouped task cards with agent threads and dependency context](docs/screenshots/image-9.png) ### Graph View — see the blockers before they block you DAG visualization of your task graph using XYFlow and Dagre layout. Blocked chains are highlighted. Assignees appear on nodes. Use topology to drive assignment decisions, not gut feel. ![Dependency graph showing task DAG with blocker highlighting](docs/screenshots/image-8.png) ### Activity View — realtime operations feed Live stream of session events, state transitions, and agent mail. Updates via file watchers and Server-Sent Events — no polling, no manual refresh. ### Swarm Coordination — agent pools and assignment queues Monitor your agent pool with archetypes and a squad roster. "Needs Agent" and pre-assigned queues let you drive work assignment from the dashboard. ![Swarm coordination panel showing agent pool, archetypes, and assignment queues](docs/screenshots/image-7.png) ### Agent Mail — structured inter-agent messaging `HANDOFF`, `BLOCKED`, `DECISION`, `INFO` categories. High-signal categories require explicit acknowledgment. Per-task threads merge activity events, agent mail, and manual notes. ```bash bd mail inbox bd mail send --to --bead --category HANDOFF --subject "Ready for review" bd mail ack ``` ### Multi-Project Scope Scanner-backed project registry. Switch between single-project and aggregate views at runtime without leaving the workspace. --- ## bb-pi Orchestrator > **Under active construction.** The orchestrator works, but it's new and has rough edges. For now: run your own coding agent alongside BeadBoard and use the dashboard to coordinate. Help improving it is welcome. BeadBoard doesn't just watch your agents — it can run them. `bb-pi` is BeadBoard's embedded execution runtime, built on [Pi](https://github.com/badlogic/pi-mono). It exposes a long-lived orchestrator per project that spawns typed worker agents, tracks their bead claims, and streams a live transcript into the left panel. **Working today (Phases 1-3):** - Embedded orchestrator with BeadBoard-aware tools (`bb_spawn_worker`, `bb_worker_status`, `bb_create`, `bb_close`, and more) - Worker spawning with numbered display names (Engineer 01, Engineer 02...) - Capability-gated agent types: architect, engineer, reviewer, tester, investigator, shipper - Template-based team spawning (`bb_spawn_team`) - Bead-required workflow — every worker task claims a bead, posts progress, closes with evidence - Async coordination — non-blocking spawn with status polling and result reads - Chat-style orchestrator transcript with realtime telemetry **Known issues being fixed:** - Double-reply rendering in orchestrator chat - Silent failures — errors not yet surfaced to UI - Session race condition under rapid use **Phases 4-7** (launch-anywhere UX, agent presence in views, hardening, full test coverage) are on the roadmap. See [docs/plans/2026-03-05-embedded-pi-roadmap.md](docs/plans/2026-03-05-embedded-pi-roadmap.md). --- ## For AI Agents BeadBoard is designed to be operated by agents, not just watched by humans. Give your agent the operating contract: ```bash npx skills add zenchantlive/beadboard --skill beadboard-driver ``` Then add to your project's `AGENTS.md` or `CLAUDE.md`: ```markdown ## BeadBoard You have access to the **beadboard-driver** skill. Use it as your entrypoint for all coordination work: claiming tasks, posting progress, reading context, and following verification rules. When in doubt about what to do next or how to record state, call beadboard-driver rather than editing markdown ad hoc. ``` Full operating manual: [AGENTS.md](AGENTS.md). Skill runbook: [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md). | Command | Role | |---------|------| | `bd` | Beads CLI — task and dependency management. Also: `npm install -g @beads/bd` | | `bb` / `beadboard` | BeadBoard CLI — dashboard launcher and orchestrator interface | --- ## Architecture ``` .beads/issues.jsonl <-- bd CLI (sole write interface) | +-- Chokidar watcher (JSONL + WAL + .last_touched) | | | IssuesEventBus | | | SSE /api/events --> browser (live) | +-- Aggregate read --> Dolt SQL (primary, if running) issues.jsonl (fallback) ``` All views live at `/` with query-param switching (`?view=social|graph|activity`). The `bd` CLI is the only write path — BeadBoard never writes to `.beads/issues.jsonl` directly. | Layer | Technologies | |-------|-------------| | Frontend | Next.js 15 (App Router), React 19, TypeScript (strict) | | Styling | Tailwind CSS, Radix UI, Framer Motion | | Graph | @xyflow/react, Dagre | | Realtime | Chokidar, Server-Sent Events | | Database | Dolt (recommended, version-controlled SQL) | | Agent runtime | @mariozechner/pi-coding-agent (bb-pi, under construction) | --- ## CLI Reference ### bd (Beads CLI) ```bash bd init # initialize Beads in a project bd create --title "Task title" --type task -p 1 # create a task bead bd ready # list unblocked work bd show # show bead detail bd update --status in_progress # update a bead bd close --reason "Done" # close a bead bd dep relate --type parent-child bd mail inbox bd mail send --to --bead --category HANDOFF --subject "..." bd dolt start bd dolt pull && bd dolt push ``` ### bb / beadboard (Dashboard CLI) ```bash beadboard start # start the dashboard beadboard start --dolt # start with Dolt backend beadboard open # open in browser beadboard status # check runtime status ``` ### Development ```bash npm run dev # Next.js dev server (localhost:3000) npm run build # production build npm run typecheck # tsc --noEmit npm run lint # eslint npm run test # full test suite ``` --- ## Platform Support Runs on macOS, Linux, and Windows. - **macOS / Linux:** Use `install/install.sh` to install `beadboard` and `bb` shims to `~/.beadboard/bin`. - **Windows:** Path handling canonicalizes drive letter casing and backslash normalization. Mixed WSL2 + Windows setups require mirrored networking — see [AGENTS.md](AGENTS.md). --- ## Contributing ```bash npm run typecheck && npm run lint && npm run test ``` Run that before submitting. Keep new features in `src/lib`, `src/components`, and `src/hooks` — not in `src/app` unless it's a route. New test files must be registered in the `test` script in `package.json` (the suite is explicit, not auto-discovered). PR against `main`. --- ## License [MIT](LICENSE) Built on [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge), inspired by [Gastown](https://github.com/steveyegge/gastown). Embedded execution runtime uses [@mariozechner](https://github.com/mariozechner)'s [Pi SDK](https://github.com/badlogic/pi-mono).