beadboard/README.md

BeadBoard

A live operations console for multi-agent work. See what every agent is doing, what's blocked, and where to intervene.

---

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 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+

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.

---

Dolt (recommended)

BeadBoard works with Dolt for version-controlled issue history, SQL queries across projects, and reliable multi-agent sync. It's the right backend for real work.

# 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:

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.

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.

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.

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.

bd mail inbox
bd mail send --to <agent> --bead <id> --category HANDOFF --subject "Ready for review"
bd mail ack <message-id>

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. 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.

---

For AI Agents

BeadBoard is designed to be operated by agents, not just watched by humans. Give your agent the operating contract:

npx skills add zenchantlive/beadboard --skill beadboard-driver

Then add to your project's AGENTS.md or CLAUDE.md:

## 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. Skill runbook: 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)

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 <id>                                     # show bead detail
bd update <id> --status in_progress              # update a bead
bd close <id> --reason "Done"                    # close a bead
bd dep relate <parent> <child> --type parent-child
bd mail inbox
bd mail send --to <agent> --bead <id> --category HANDOFF --subject "..."
bd dolt start
bd dolt pull && bd dolt push

bb / beadboard (Dashboard CLI)

beadboard start          # start the dashboard
beadboard start --dolt   # start with Dolt backend
beadboard open           # open in browser
beadboard status         # check runtime status

Development

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.

---

Contributing

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

Built on Beads by Steve Yegge, inspired by Gastown. Embedded execution runtime uses @mariozechner's Pi SDK.