# BeadBoard [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) **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. --- ## Quick Start **Prerequisites:** Node.js 18.18+ (Node 20 LTS recommended), 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. --- ## For AI Agents Install the `beadboard-driver` skill to give your agent the operating contract for BeadBoard coordination: ```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 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](AGENTS.md). The skill runbook is at [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. ![Social view showing grouped task cards with agent threads and dependency context](docs/screenshots/image-9.png) ### 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. ![Dependency graph view showing task DAG with blocker highlighting](docs/screenshots/image-8.png) ### 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. ![Swarm coordination panel showing agent pool, archetypes, and assignment queues](docs/screenshots/image-7.png) ### 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 --bead --category HANDOFF --subject "Ready for review" bd mail ack ``` ### 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. --- ## 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) ```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 # show bead detail bd update --status in_progress # update a bead bd close --reason "Done" # close a bead bd dep relate --type parent-child bd mail inbox bd mail send --to --bead --category HANDOFF --subject "..." bd dolt start # start Dolt server bd dolt pull && bd dolt push # sync with Dolt remote ``` ### bb / beadboard (BeadBoard CLI) ```bash 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) ```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 ``` 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 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](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: ```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`. --- ## License [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).