BeadBoard

Local dashboard and multi-agent orchestration system built on Beads.

BeadBoard reads .beads/issues.jsonl files directly from your repos and renders them as an agent-first operations console: a unified shell with Social, Graph, and Activity lenses for monitoring multi-agent work, managing swarms, and intervening on blockers. Found us via the Beads community tools list? You're in the right place.

---

Quick Start

Prerequisites: Node.js 18.18+ (Node 20 LTS recommended), npm 7+

# Clone and install
git clone https://github.com/zenchantlive/beadboard.git
cd beadboard
npm install
npm install -g .

This installs:

• beadboard — Dashboard launcher
• bb — Alias for beadboard, also the CLI for the built-in orchestrator agent (built on Pi)
• bd — Beads CLI for task management (also available standalone via npm install -g @beads/bd)

# Initialize Beads in your project
cd ~/my-project
bd init

# Start the dashboard
beadboard start

Open http://localhost:3000.

Dolt is optional. BeadBoard reads .beads/issues.jsonl directly when Dolt is not running. Install Dolt for version-controlled SQL history — recommended for multi-agent workflows but not required to get started.

---

For AI Agents

Install the beadboard-driver skill to give your agent the operating contract for BeadBoard coordination:

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 beadboard-driver as your entrypoint for all coordination work (tasks, context, status).
- Use it to read and update Beads via `bd`, keep work state consistent with the BeadBoard UI,
  and follow the verification rules described in this repo.
- When in doubt about what to do next or how to record progress, call beadboard-driver and
  follow its guidance rather than editing markdown ad hoc.

The full agent operating manual is at AGENTS.md. The skill runbook is at skills/beadboard-driver/SKILL.md.

Two CLIs, one system:

Command	What it is
bd	Beads CLI — task/dependency management. Also available via npm install -g @beads/bd
bb / beadboard	BeadBoard CLI — dashboard launcher + orchestrator

---

Features

Social View — grouped task cards with agent context

Task cards organized by status, with dependency chains, thread context, and agent assignment surfaced inline. Built for scanning active work across a swarm at a glance.

Graph View — dependency topology

DAG visualization of your task graph using XYFlow and Dagre layout. Shows blocked chains, execution order, and assignees on nodes. Drives assignment decisions from topology rather than gut feel.

Activity View — realtime operations feed

Live activity stream integrating session events, state transitions, and agent mail. Updates via file watchers and Server-Sent Events — no polling, no manual refresh.

Swarm Coordination

Agent pool monitor with archetypes, assignment queues, and squad roster. "Needs Agent" and pre-assigned queues let you drive work assignment without leaving the dashboard.

Agent Mail

Structured inter-agent messaging with categories (HANDOFF, BLOCKED, DECISION, INFO). High-signal categories require explicit acknowledgment. Per-task threads merge activity events, agent mail, and local interactions.

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

Multi-Project Scope

Project registry with scanner-backed discovery. Switch between single-project and aggregate modes at runtime without leaving the workspace.

---

bb-pi Orchestrator

UNDER CONSTRUCTION — The orchestrator is working but new. Use your own coding agent alongside BeadBoard for now, or help us improve it!

bb-pi is BeadBoard's embedded execution runtime. It uses Pi (@mariozechner/pi-coding-agent) as the execution substrate and exposes a long-lived orchestrator per project that can spawn typed worker agents.

What works today (Phases 1-3 complete):

• Embedded orchestrator with BeadBoard-aware tools (bb_spawn_worker, bb_worker_status, bb_create, bb_close, etc.)
• Worker spawning with numbered display names (Engineer 01, Engineer 02...)
• Agent types with capability-gated tool access (architect, engineer, reviewer, tester, investigator, shipper)
• Template-based team spawning (bb_spawn_team)
• Bead-required workflow — every worker task claims a bead, updates progress, closes with evidence
• Async worker coordination — non-blocking spawn with status polling and result reads
• Chat-style orchestrator transcript in the left panel with realtime telemetry

Known issues being actively fixed:

• Double-reply rendering in orchestrator chat
• Silent failures — errors not surfaced to UI
• Session race condition under rapid use
• Phases 4-7 (launch-anywhere UX, agent presence in views, hardening, test coverage) are not done

See docs/plans/2026-03-05-embedded-pi-roadmap.md for the full status breakdown.

---

Architecture

Data flow

.beads/issues.jsonl  <--  bd CLI (sole write interface)
        |
        +-- Chokidar watcher (file + WAL + .last_touched)
        |         |
        |    IssuesEventBus
        |         |
        |     SSE endpoint  -->  browser (live updates)
        |
        +-- Aggregate read  -->  Dolt SQL (primary, if running)
                                 issues.jsonl (fallback)

1. bd commands write to .beads/issues.jsonl. Never write to this file directly.
2. The parser (src/lib/parser.ts) normalizes JSONL into BeadIssue objects.
3. IssuesWatchManager (Chokidar) watches for changes, coalesces events, and emits through the event bus.
4. The SSE endpoint (/api/events) streams changes to the browser.
5. The read path prefers Dolt SQL when available and falls back to JSONL.

Tech stack

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 (optional, version-controlled SQL)
Agent runtime	@mariozechner/pi-coding-agent (bb-pi, under construction)
Video	Remotion

View routing

All active views live at / with query-param switching. Legacy routes redirect:

URL	View
/?view=social	Social feed
/?view=graph	Dependency graph
/?view=activity	Activity timeline
/graph, /sessions, /timeline	Redirect to unified shell equivalents

---

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                                    # start Dolt server
bd dolt pull && bd dolt push                     # sync with Dolt remote

bb / beadboard (BeadBoard CLI)

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

npm scripts (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

Run a single test file:

node --import tsx --test tests/lib/parser.test.ts

New test files must be added to the test script in package.json — the suite is explicitly enumerated, not auto-discovered.

---

Cross-Platform Support

BeadBoard runs on Windows, macOS, and Linux.

• 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.
• Dolt: Optional on all platforms. The dashboard reads .beads/issues.jsonl directly when Dolt is unavailable.

---

Contributing

1. Fork the repo and create a feature branch.
2. Run quality gates before submitting:

npm run typecheck && npm run lint && npm run test

3. Keep active runtime pages minimal under src/app. Promote shared logic to src/lib, src/components, src/hooks.
4. New tests must be registered in the test script in package.json.
5. Submit a pull request against main.

---

License

MIT

Acknowledgments

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