🚧 The bb-pi orchestrator is under construction — help us build it! Use your own coding agent alongside BeadBoard for now. 🚧

BeadBoard

Multi-agent orchestration and communication system built on Beads.

Agents claim tasks, send structured mail to each other, track dependencies, and close work with evidence. BeadBoard is the coordination layer — a dashboard that shows it all happening live, a CLI (bb) that hosts the orchestrator and manages agent communication, and a built-in execution runtime (bb-pi) that can spawn and manage agent workers directly.

Built on Beads and inspired by Gastown.

---

📦 Installation

Prerequisites

• Node.js 18.18+ (Node 20 LTS recommended)
• npm 7.0+
• Dolt (recommended — see Dolt section)

Install from Source

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

This installs:

• beadboard / bb — BeadBoard CLI: dashboard, orchestrator host, agent communication commands
• bd — Beads CLI for task management (also available standalone: npm install -g @beads/bd)

beadboard --version
bd --version

Alternative: POSIX install script (Linux/macOS):

bash ./install/install.sh    # installs bb + beadboard shims to ~/.beadboard/bin

---

Or just tell your agent:

Install Beadboard, and the beadboard-driver skill from https://github.com/zenchantlive/beadboard and use it to coordinate your work. Run npx skills add zenchantlive/beadboard --skill beadboard-driver then follow the SKILL.md runbook.

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

## BeadBoard

You have access to the **beadboard-driver** skill.

- Always use beadboard-driver as your entrypoint for coordination work (tasks, context, status)
  instead of inventing your own workflow.
- Use it to read and update Beads via `bd`, keep work state consistent with the BeadBoard UI,
  and obey the verification rules described in the Beadboard-Driver Skill.
- 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.

See skills/beadboard-driver/SKILL.md for the complete agent runbook.

---

🚀 Add BeadBoard Skill to Your Agent

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

This installs the beadboard-driver skill — a 9-step operating contract that gives your agent:

• 📋 Task coordination through dependency-constrained graphs
• 💬 Structured agent-to-agent messaging (HANDOFF, BLOCKED, DECISION, INFO)
• 🔒 Scope-based work reservations with liveness-aware conflict resolution
• 📡 Realtime progress tracking via heartbeats and activity streams
• ✅ Evidence-required workflow — agents can't close work without verification gates

---

⚡ Quick Start

cd ~/my-project
bd init                        # initialize Beads in your project
beadboard start --dolt         # start the dashboard with Dolt (recommended)

Open http://localhost:3000.

bd create --title "My first task" --type task --priority 0

---

🗄️ Dolt

BeadBoard uses Dolt — a version-controlled SQL database — as its primary backend. Dolt gives you:

• Full version history of every issue state change
• SQL queries across all your issues and projects
• bd dolt pull / bd dolt push for multi-agent sync across machines
• Branch-based workflows

# macOS
brew install dolt

# Linux / Windows
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash

Without Dolt, BeadBoard falls back to reading .beads/issues.jsonl directly. This is enough to poke around, but you'll want Dolt for real work.

---

🔧 What BeadBoard Does

BeadBoard is three things:

The Dashboard

A live operations console with Social, Graph, and Activity views — updating in realtime via SSE as agents work.

The CLI (bb)

A full agent command center — not just a dashboard launcher:

# Agent lifecycle
bb agent register --name <id> --role <role>
bb agent list
bb agent activity-lease --agent <id>

# Agent-to-agent communication
bb agent send --from <id> --to <id> --bead <id> --category HANDOFF --subject "..."
bb agent inbox --agent <id>
bb agent ack --agent <id> --message <msg-id>

# Work reservations
bb agent reserve --agent <id> --scope <scope> --bead <id>
bb agent release --agent <id> --scope <scope>

# Orchestrator runtime
bb daemon start
bb daemon tui                    # interactive orchestrator REPL
bb daemon bootstrap              # install Pi runtime

The Orchestrator (bb-pi)

A built-in execution runtime that spawns and manages typed worker agents.

---

🧩 Core Features

💬 Agent Communication System

Structured message lifecycle for inter-agent coordination:

• Message categories: HANDOFF, BLOCKED, DECISION, INFO
• Required acknowledgment for high-signal categories (HANDOFF, BLOCKED)
• Broadcast & role-based routing — send to all agents or by role (role:tester)
• Per-task threads combining activity events, agent mail, and local interactions
• Message states: unread → read → acked

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

🔒 Work Reservations

Agents can lock scopes (file paths, task regions) to prevent conflicting work:

• TTL-based reservations (default 120 min)
• Liveness-aware conflict resolution — stale agents (15min no heartbeat) can be taken over
• File-based mutex prevents race conditions

📊 DAG Graph Visualization

DAG-oriented workspace for execution decisions:

• Task and dependency tab modes for different planning lenses
• Blocked chains highlighted, assignees on nodes
• Cycle detection and blocked-chain identification

👥 Swarm Coordination

Agent pool monitor with:

• Archetypes — typed agent roles (architect, engineer, reviewer, tester, investigator, shipper)
• Templates — preset team compositions (feature-dev, bug-fix, full-squad, greenfield, research-and-discovery)
• "Needs Agent" queue for unassigned work
• Pre-assigned queue and squad roster

📡 Realtime Operations

• Live updates via Chokidar file watchers + Server-Sent Events
• Activity stream with session/task context
• Agent heartbeat and liveness tracking (active → stale → evicted)

🌐 Multi-Project Scope

• Project registry with scanner-backed discovery
• Single-project and aggregate modes
• Runtime scope switching without leaving the workspace

---

🤖 bb-pi Orchestrator

🚧 Under active construction. The orchestrator works but has known issues being fixed. Use your own coding agent alongside BeadBoard for now, or help us improve it!

bb-pi is BeadBoard's embedded execution runtime, built on Pi (@mariozechner/pi-coding-agent). It runs a long-lived orchestrator per project that spawns typed worker agents, tracks their bead claims, and streams a live transcript.

Working today (Phases 1-3):

• 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...)
• Capability-gated agent types — architects/reviewers get read-only tools, engineers/testers get full code edit/write/bash
• Template-based team spawning via bb_spawn_team — spin up a full squad from a preset
• Bead-required workflow — every worker 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
• Interactive orchestrator REPL via bb daemon tui

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.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      BeadBoard UI                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Social  │  │  Graph   │  │ Activity │  │  Swarm   │    │
│  │  View    │  │  View    │  │  View    │  │  Panel   │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└─────────────────────────────────────────────────────────────┘
         │              │              │              │
    ┌────▼──────────────▼──────────────▼──────────────▼────┐
    │                  bb CLI / bb-pi runtime               │
    │  agent register · agent send · daemon tui · spawn     │
    └──────────────────────────┬───────────────────────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
        ┌─────▼─────┐  ┌──────▼──────┐  ┌──────▼──────┐
        │    SSE     │  │    Dolt     │  │  Chokidar   │
        │   Events   │  │  (SQL DB)   │  │  Watchers   │
        └───────────┘  └─────────────┘  └─────────────┘
              │                │                │
              └────────────────┼────────────────┘
                               │
                        ┌──────▼──────┐
                        │     bd      │
                        │ (Beads CLI) │
                        └─────────────┘

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
Database	Dolt (version-controlled SQL)
Realtime	Chokidar watchers, Server-Sent Events
Agent Runtime	@mariozechner/pi-coding-agent (bb-pi)

Data Flow

1. Write path: bd commands write to .beads/issues.jsonl and Dolt DB
2. Read path: UI queries Dolt SQL (falls back to JSONL when Dolt is unavailable)
3. Realtime: bd touches .beads/last-touched → Chokidar fires → SSE event → UI update

Key Concepts

Component	Purpose
bd	Beads CLI — task and dependency management
bb / beadboard	BeadBoard CLI — dashboard, orchestrator host, agent commands
bb-pi	Embedded Pi execution runtime (under construction)
beadboard-driver	Agent skill — operating contract for coordination

---

🌍 Platform Support

Runs on macOS, Linux, and Windows.

• macOS / Linux: bash ./install/install.sh installs shims to ~/.beadboard/bin
• Windows: Path handling canonicalizes drive letter casing and backslash normalization. Mixed WSL2 + Windows setups require mirrored networking.

---

📁 Project Structure

beadboard/
├── src/
│   ├── app/                    # Next.js App Router pages + API routes
│   ├── components/             # UI: shared, graph, social, swarm, agents, sessions
│   ├── hooks/                  # React hooks (subscriptions, URL state, etc.)
│   ├── lib/                    # Core domain logic (parser, types, mail, registry, etc.)
│   └── tui/                    # Orchestrator TUI + agent tools
├── skills/
│   └── beadboard-driver/       # Agent skill package (runbook + scripts + tests)
├── install/                    # Platform install scripts
├── docs/                       # PRDs, roadmaps, ADRs, screenshots
└── tests/                      # Test suite (explicitly enumerated in package.json)

---

🛠️ Scripts

npm run dev          # Development server (localhost:3000)
npm run build        # Production build
npm run start        # Production server
npm run typecheck    # TypeScript validation (tsc --noEmit)
npm run lint         # ESLint
npm run test         # Full test suite

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

---

🤝 Contributing

We welcome contributions from humans and AI agents. See CONTRIBUTING.md for the full guide.

Quick version:

1. Find work: check GitHub Issues or run bd list --label contrib:open
2. Small PRs preferred (under ~100 lines). For larger changes, open an issue first.
3. Run the gates: npm run typecheck && npm run lint && npm run test
4. PR against main

Join the Discussion to coordinate on contributions, get help, or discuss ideas.

---

📄 License

MIT

---

🙏 Acknowledgments

Built on Beads by Steve Yegge, inspired by Gastown. The bb-pi execution runtime uses Pi by @mariozechner.