5537e22174
- Hero screenshot + "who's watching your agents" hook at top - Dolt promoted from optional footnote to recommended with install commands - bb-pi section leads with vision before construction status - Agent-first framing moved higher - Trimmed to 248 lines, no duplicates, no filler Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
248 lines
9.2 KiB
Markdown
248 lines
9.2 KiB
Markdown
# BeadBoard
|
|
|
|
**A live operations console for multi-agent work. See what every agent is doing, what's blocked, and where to intervene.**
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://github.com/steveyegge/beads)
|
|
|
|
|
|
|
|
---
|
|
|
|
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.
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
```bash
|
|
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](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 <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)
|
|
|
|
```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).
|