docs: sharpen README — lead with the problem, frame Dolt as recommended
- 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>
This commit is contained in:
zenchantlive
parent
fabd748833
commit
5537e22174
1 changed files with 127 additions and 148 deletions
275
README.md
275
README.md
|
|
@ -1,48 +1,134 @@
|
|||
# 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)
|
||||
|
||||
**Local dashboard and multi-agent orchestration system built on [Beads](https://github.com/steveyegge/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](https://github.com/steveyegge/beads/blob/main/docs/COMMUNITY_TOOLS.md)? You're in the right place.
|
||||
---
|
||||
|
||||
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 18.18+ (Node 20 LTS recommended), npm 7+
|
||||
**Prerequisites:** Node.js 20 LTS, npm 7+
|
||||
|
||||
```bash
|
||||
# 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](https://github.com/badlogic/pi-mono))
|
||||
- `bd` — Beads CLI for task management (also available standalone via `npm install -g @beads/bd`)
|
||||
|
||||
```bash
|
||||
# Initialize Beads in your project
|
||||
cd ~/my-project
|
||||
bd init
|
||||
|
||||
# Start the dashboard
|
||||
beadboard start
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](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.
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
Install the `beadboard-driver` skill to give your agent the operating contract for BeadBoard coordination:
|
||||
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
|
||||
|
|
@ -55,115 +141,36 @@ Then add to your project's `AGENTS.md` or `CLAUDE.md`:
|
|||
|
||||
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.
|
||||
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.
|
||||
```
|
||||
|
||||
The full agent operating manual is at [AGENTS.md](AGENTS.md). The skill runbook is at [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md).
|
||||
Full operating manual: [AGENTS.md](AGENTS.md). Skill runbook: [skills/beadboard-driver/SKILL.md](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.
|
||||
|
||||
```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
|
||||
|
||||
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](https://github.com/badlogic/pi-mono) ([@mariozechner/pi-coding-agent](https://www.npmjs.com/package/@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](docs/plans/2026-03-05-embedded-pi-roadmap.md) for the full status breakdown.
|
||||
| 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
|
||||
|
||||
### Data flow
|
||||
|
||||
```
|
||||
.beads/issues.jsonl <-- bd CLI (sole write interface)
|
||||
|
|
||||
+-- Chokidar watcher (file + WAL + .last_touched)
|
||||
+-- Chokidar watcher (JSONL + WAL + .last_touched)
|
||||
| |
|
||||
| IssuesEventBus
|
||||
| |
|
||||
| SSE endpoint --> browser (live updates)
|
||||
| SSE /api/events --> browser (live)
|
||||
|
|
||||
+-- 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
|
||||
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 |
|
||||
|-------|-------------|
|
||||
|
|
@ -171,20 +178,8 @@ See [docs/plans/2026-03-05-embedded-pi-roadmap.md](docs/plans/2026-03-05-embedde
|
|||
| Styling | Tailwind CSS, Radix UI, Framer Motion |
|
||||
| Graph | @xyflow/react, Dagre |
|
||||
| Realtime | Chokidar, Server-Sent Events |
|
||||
| Database | Dolt (optional, version-controlled SQL) |
|
||||
| Database | Dolt (recommended, 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 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -202,20 +197,20 @@ 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
|
||||
bd dolt start
|
||||
bd dolt pull && bd dolt push
|
||||
```
|
||||
|
||||
### bb / beadboard (BeadBoard CLI)
|
||||
### bb / beadboard (Dashboard CLI)
|
||||
|
||||
```bash
|
||||
beadboard start # start the dashboard server
|
||||
beadboard start # start the dashboard
|
||||
beadboard start --dolt # start with Dolt backend
|
||||
beadboard open # open dashboard in browser
|
||||
beadboard open # open in browser
|
||||
beadboard status # check runtime status
|
||||
```
|
||||
|
||||
### npm scripts (development)
|
||||
### Development
|
||||
|
||||
```bash
|
||||
npm run dev # Next.js dev server (localhost:3000)
|
||||
|
|
@ -225,38 +220,24 @@ npm run lint # eslint
|
|||
npm run test # full test suite
|
||||
```
|
||||
|
||||
Run a single test file:
|
||||
|
||||
```bash
|
||||
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
|
||||
## Platform Support
|
||||
|
||||
BeadBoard runs on Windows, macOS, and Linux.
|
||||
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).
|
||||
- **Dolt**: Optional on all platforms. The dashboard reads `.beads/issues.jsonl` directly when Dolt is unavailable.
|
||||
- **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
|
||||
|
||||
1. Fork the repo and create a feature branch.
|
||||
2. Run quality gates before submitting:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
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`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -264,6 +245,4 @@ npm run typecheck && npm run lint && npm run test
|
|||
|
||||
[MIT](LICENSE)
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Built on [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge), inspired by [Gastown](https://github.com/steveyegge/gastown). The embedded Pi execution runtime uses [@mariozechner](https://github.com/mariozechner)'s [Pi SDK](https://github.com/badlogic/pi-mono).
|
||||
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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue