docs: rewrite README + add under-construction banner to orchestrator panel
README.md: - Remove duplicate sections, stale info, and broken markdown - Add bb-pi orchestrator section with honest WIP status and known issues - Clarify bd vs bb/beadboard CLI distinction - Add cross-platform support section (Windows, macOS, Linux) - Note Dolt as optional, document JSONL fallback - Reference Pi SDK and community tools listing orchestrator-panel.tsx: - Add amber "Under construction" banner with link to track progress - Visible on every orchestrator panel render Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
zenchantlive
parent
d6f73ce979
commit
fabd748833
2 changed files with 172 additions and 458 deletions
621
README.md
621
README.md
|
|
@ -1,226 +1,105 @@
|
||||||
## 🚧 Fixing issues as we speak! Will be up and running again soon 🚧
|
|
||||||
|
|
||||||
# BeadBoard
|
# BeadBoard
|
||||||
|
|
||||||
[](https://opensource.org/licenses/MIT)
|
[](https://opensource.org/licenses/MIT)
|
||||||
[](https://github.com/zenchantlive/beadboard/stargazers)
|
|
||||||
|
|
||||||
**Multi-agent swarm coordination system for dependency-constrained work.**
|
**Local dashboard and multi-agent orchestration system built on [Beads](https://github.com/steveyegge/beads).**
|
||||||
|
|
||||||
Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](https://github.com/steveyegge/gastown).
|
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.
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 Add BeadBoard to Your Agent
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx skills add zenchantlive/beadboard --skill beadboard-driver
|
|
||||||
```
|
|
||||||
|
|
||||||
This one command installs the BeadBoard driver skill, enabling your AI agents to:
|
|
||||||
- Coordinate work through dependency-constrained task graphs
|
|
||||||
- Communicate with other agents via structured message passing
|
|
||||||
- Track progress with real-time updates and activity streams
|
|
||||||
- Manage work state through the `bd` CLI
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- **Node.js** 18.18+ (Node 20 LTS recommended)
|
|
||||||
- **npm** 7.0+
|
|
||||||
- **Git** (for cloning and version control)
|
|
||||||
|
|
||||||
### Install from Source
|
|
||||||
|
|
||||||
BeadBoard is installed by cloning the repository and installing locally:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone the repository
|
|
||||||
git clone https://github.com/zenchantlive/beadboard.git
|
|
||||||
cd beadboard
|
|
||||||
|
|
||||||
# Install globally (makes `beadboard` and `bd` commands available)
|
|
||||||
npm install -g .
|
|
||||||
```
|
|
||||||
|
|
||||||
This installs:
|
|
||||||
- `beadboard` - Dashboard launcher
|
|
||||||
- `bd` - Beads CLI for task management
|
|
||||||
|
|
||||||
> **Note**: BeadBoard is not published to npm yet. We may publish it in the future if there's demand. For now, install from source as shown above.
|
|
||||||
|
|
||||||
### Verify Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
beadboard --version
|
|
||||||
bd --version
|
|
||||||
```
|
|
||||||
|
|
||||||
### Development Setup
|
|
||||||
|
|
||||||
For development or contributing:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/zenchantlive/beadboard.git
|
|
||||||
cd beadboard
|
|
||||||
npm install
|
|
||||||
npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
### Update Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd beadboard
|
|
||||||
git pull origin main
|
|
||||||
npm install -g .
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Start the Dashboard
|
**Prerequisites:** Node.js 18.18+ (Node 20 LTS recommended), npm 7+
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Start with Dolt backend (recommended)
|
# Clone and install
|
||||||
beadboard start --dolt
|
git clone https://github.com/zenchantlive/beadboard.git
|
||||||
|
cd beadboard
|
||||||
|
npm install
|
||||||
|
npm install -g .
|
||||||
|
```
|
||||||
|
|
||||||
# Or start without Dolt (limited features)
|
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
|
beadboard start
|
||||||
```
|
```
|
||||||
|
|
||||||
Open [http://localhost:3000](http://localhost:3000) to access the coordination dashboard.
|
Open [http://localhost:3000](http://localhost:3000).
|
||||||
|
|
||||||
### Initialize a Project
|
> **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.
|
||||||
|
|
||||||
```bash
|
|
||||||
# Create a new project
|
|
||||||
mkdir my-project
|
|
||||||
cd my-project
|
|
||||||
bd init
|
|
||||||
|
|
||||||
# Create your first task
|
|
||||||
bd create --title "My first task" --type task --priority 0
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## For AI Agents
|
## For AI Agents
|
||||||
|
|
||||||
### Add BeadBoard to Your Agent
|
Install the `beadboard-driver` skill to give your agent the operating contract for BeadBoard coordination:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx skills add zenchantlive/beadboard --skill beadboard-driver
|
npx skills add zenchantlive/beadboard --skill beadboard-driver
|
||||||
```
|
```
|
||||||
|
|
||||||
This command installs the BeadBoard driver skill, enabling your AI agents to:
|
Then add to your project's `AGENTS.md` or `CLAUDE.md`:
|
||||||
- Coordinate work through dependency-constrained task graphs
|
|
||||||
- Communicate with other agents via structured message passing
|
|
||||||
- Track progress with real-time updates and activity streams
|
|
||||||
- Manage work state through the `bd` CLI
|
|
||||||
|
|
||||||
**[→ Full Agent Integration Guide](#agent-integration)**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
|
|
||||||
### For Human Users
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone and install from source
|
|
||||||
git clone https://github.com/zenchantlive/beadboard.git
|
|
||||||
cd beadboard
|
|
||||||
npm install -g .
|
|
||||||
beadboard start
|
|
||||||
```
|
|
||||||
|
|
||||||
Open [http://localhost:3000](http://localhost:3000) to access the coordination dashboard.
|
|
||||||
|
|
||||||
### For Agent Developers
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Install the skill to your project
|
|
||||||
npx skills add zenchantlive/beadboard --skill beadboard-driver
|
|
||||||
|
|
||||||
# Or install globally for all your projects
|
|
||||||
npx skills add zenchantlive/beadboard --skill beadboard-driver --global
|
|
||||||
```
|
|
||||||
|
|
||||||
Then add to your project's `AGENTS.md`:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## BeadBoard Integration
|
|
||||||
|
|
||||||
- Working directory: Run all `bd` commands from project root
|
|
||||||
- Source of truth: `bd` CLI manages all work state
|
|
||||||
- Evidence required: Never claim done without verification gates
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Open [http://localhost:3000](http://localhost:3000) to access the dashboard.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Agent Integration
|
|
||||||
|
|
||||||
BeadBoard is designed for AI agent coordination. Agents work in their own project repositories while humans observe and coordinate through the BeadBoard UI.
|
|
||||||
|
|
||||||
### Configuration
|
|
||||||
|
|
||||||
Add the following to your project's `AGENTS.md` or `CLAUDE.md`:
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
## BeadBoard
|
## BeadBoard
|
||||||
|
|
||||||
You have access to the **beadboard-driver** skill. [page:22]
|
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 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 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.
|
||||||
```
|
```
|
||||||
|
|
||||||
### Key Concepts
|
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).
|
||||||
|
|
||||||
| Component | Purpose |
|
**Two CLIs, one system:**
|
||||||
|-----------|---------|
|
|
||||||
| `bd` | Beads CLI - task and dependency management |
|
|
||||||
| `bb` | BeadBoard CLI - dashboard launcher |
|
|
||||||
| `beadboard-driver` skill | Agent operating contract for coordination |
|
|
||||||
|
|
||||||
See [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md) for the complete agent runbook.
|
| 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 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## What BeadBoard Does
|
## Features
|
||||||
|
|
||||||
BeadBoard is an execution system for coordinating agents around shared Beads workflows:
|
### Social View — grouped task cards with agent context
|
||||||
|
|
||||||
- **Agent-to-agent communication** with explicit categories (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`)
|
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.
|
||||||
- **Conversation threads** merged from activity events, agent messages, and local interactions
|
|
||||||
- **Graph/topology context** for deciding what should move next
|
|
||||||
- **Global project scope switching** across single and aggregate workspaces
|
|
||||||
- **Swarm orchestration** with archetypes/templates and assignment controls
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
---
|
### Graph View — dependency topology
|
||||||
|
|
||||||
## Core Features
|
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.
|
||||||
|
|
||||||
### 1. Agent Communication System
|
|
||||||
|
|
||||||
Structured message lifecycle for inter-agent coordination:
|
### Activity View — realtime operations feed
|
||||||
|
|
||||||
- **Message states**: `unread`, `read`, `acked`
|
Live activity stream integrating session events, state transitions, and agent mail. Updates via file watchers and Server-Sent Events — no polling, no manual refresh.
|
||||||
- **Required acknowledgment** for high-signal categories (`HANDOFF`, `BLOCKED`)
|
|
||||||
- **Per-task threads** combining activity events, agent mail, and local interactions
|
### 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
|
```bash
|
||||||
bd mail inbox
|
bd mail inbox
|
||||||
|
|
@ -228,326 +107,156 @@ bd mail send --to <agent> --bead <id> --category HANDOFF --subject "Ready for re
|
||||||
bd mail ack <message-id>
|
bd mail ack <message-id>
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Swarm Coordination Surface
|
### Multi-Project Scope
|
||||||
|
|
||||||
Agent Pool Monitor with:
|
Project registry with scanner-backed discovery. Switch between single-project and aggregate modes at runtime without leaving the workspace.
|
||||||
|
|
||||||
- Archetypes and templates for agent specialization
|
|
||||||
- "Needs Agent" queue for unassigned work
|
|
||||||
- Pre-assigned queue for reserved tasks
|
|
||||||
- Squad roster for active team members
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 3. Graph + Dependency Topology
|
|
||||||
|
|
||||||
DAG-oriented workspace for execution decisions:
|
|
||||||
|
|
||||||
- Task/dependency tab modes for different planning lenses
|
|
||||||
- Blocker/unblock context surfaced in task cards
|
|
||||||
- Graph analysis support (cycle detection, blocked-chain identification)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 4. Global Project Scope + Scanner
|
|
||||||
|
|
||||||
- Project registry and scanner-backed discovery
|
|
||||||
- Single-project and aggregate modes
|
|
||||||
- Runtime scope switching without leaving the workspace
|
|
||||||
|
|
||||||
### 5. Realtime Operations Layer
|
|
||||||
|
|
||||||
- Live updates via file watchers + Server-Sent Events
|
|
||||||
- Activity stream integration with session/task context
|
|
||||||
- Mutation/writeback feedback integrated into the operational surface
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Installation & Setup
|
## bb-pi Orchestrator
|
||||||
|
|
||||||
### Prerequisites
|
> **UNDER CONSTRUCTION** — The orchestrator is working but new. Use your own coding agent alongside BeadBoard for now, or help us improve it!
|
||||||
|
|
||||||
- Node.js `18.18+` (Node `20 LTS` recommended)
|
`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.
|
||||||
- npm
|
|
||||||
|
|
||||||
### Clone + Install
|
**What works today (Phases 1-3 complete):**
|
||||||
|
|
||||||
```bash
|
- Embedded orchestrator with BeadBoard-aware tools (`bb_spawn_worker`, `bb_worker_status`, `bb_create`, `bb_close`, etc.)
|
||||||
git clone https://github.com/zenchantlive/beadboard.git
|
- Worker spawning with numbered display names (Engineer 01, Engineer 02...)
|
||||||
cd beadboard
|
- Agent types with capability-gated tool access (architect, engineer, reviewer, tester, investigator, shipper)
|
||||||
npm install
|
- Template-based team spawning (`bb_spawn_team`)
|
||||||
npm install -g .
|
- 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
|
||||||
|
|
||||||
This makes `beadboard` and `bd` commands available globally.
|
**Known issues being actively fixed:**
|
||||||
|
|
||||||
**Alternative: Platform-specific wrappers**
|
- 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
|
||||||
|
|
||||||
If you prefer not to install globally via npm, you can use the platform-specific wrappers.
|
See [docs/plans/2026-03-05-embedded-pi-roadmap.md](docs/plans/2026-03-05-embedded-pi-roadmap.md) for the full status breakdown.
|
||||||
|
|
||||||
POSIX (Linux/macOS):
|
|
||||||
```bash
|
|
||||||
bash ./install/install.sh
|
|
||||||
### Development Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
Open [http://localhost:3000](http://localhost:3000)
|
|
||||||
|
|
||||||
### Production Deployment
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run build
|
|
||||||
npm run start
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Usage & Examples
|
|
||||||
|
|
||||||
### CLI Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Start BeadBoard dashboard
|
|
||||||
beadboard start
|
|
||||||
|
|
||||||
# Start with Dolt database
|
|
||||||
beadboard start --dolt
|
|
||||||
|
|
||||||
# Open dashboard in browser
|
|
||||||
beadboard open
|
|
||||||
|
|
||||||
# Check status
|
|
||||||
beadboard status
|
|
||||||
```
|
|
||||||
|
|
||||||
### Workflow Example
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Navigate to your project
|
|
||||||
cd ~/my-project
|
|
||||||
|
|
||||||
# 2. Start Dolt (if using version-controlled data)
|
|
||||||
bd dolt start
|
|
||||||
|
|
||||||
# 3. Start BeadBoard
|
|
||||||
beadboard start --dolt
|
|
||||||
|
|
||||||
# 4. Open dashboard
|
|
||||||
beadboard open
|
|
||||||
```
|
|
||||||
|
|
||||||
### Common Patterns
|
|
||||||
|
|
||||||
**Coordinate through Graph + Pool:**
|
|
||||||
```
|
|
||||||
Open /?view=graph → inspect dependency topology → drive assignment from pool panel
|
|
||||||
```
|
|
||||||
|
|
||||||
**Communicate in Context:**
|
|
||||||
```
|
|
||||||
Open task thread → read merged conversation → process message acknowledgments
|
|
||||||
```
|
|
||||||
|
|
||||||
**Switch Scope:**
|
|
||||||
```
|
|
||||||
Use registry/scanner controls → move between local and aggregate project scope
|
|
||||||
```
|
|
||||||
|
|
||||||
**Track Live Signal:**
|
|
||||||
```
|
|
||||||
Use social/activity views → monitor execution movement and operational events
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
### High-Level Design
|
### Data flow
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
.beads/issues.jsonl <-- bd CLI (sole write interface)
|
||||||
│ BeadBoard UI │
|
|
|
||||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
+-- Chokidar watcher (file + WAL + .last_touched)
|
||||||
│ │ Social │ │ Graph │ │ Activity │ │ Swarm │ │
|
| |
|
||||||
│ │ View │ │ View │ │ View │ │ Panel │ │
|
| IssuesEventBus
|
||||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
| |
|
||||||
└─────────────────────────────────────────────────────────────┘
|
| SSE endpoint --> browser (live updates)
|
||||||
│
|
|
|
||||||
┌────────────┼────────────┐
|
+-- Aggregate read --> Dolt SQL (primary, if running)
|
||||||
│ │ │
|
issues.jsonl (fallback)
|
||||||
┌─────▼─────┐ ┌────▼────┐ ┌────▼─────┐
|
|
||||||
│ SSE │ │ Dolt │ │ Watchers│
|
|
||||||
│ Events │ │ DB │ │ (Chokidar)│
|
|
||||||
└───────────┘ └─────────┘ └──────────┘
|
|
||||||
│ │ │
|
|
||||||
└────────────┼────────────┘
|
|
||||||
│
|
|
||||||
┌──────▼──────┐
|
|
||||||
│ bd │
|
|
||||||
│ (Beads CLI)│
|
|
||||||
└─────────────┘
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Tech Stack
|
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 |
|
| Layer | Technologies |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| Frontend | Next.js 15, React 19, TypeScript |
|
| Frontend | Next.js 15 (App Router), React 19, TypeScript (strict) |
|
||||||
| Styling | Tailwind CSS, Radix UI, Framer Motion |
|
| Styling | Tailwind CSS, Radix UI, Framer Motion |
|
||||||
| Graph | XYFlow, Dagre |
|
| Graph | @xyflow/react, Dagre |
|
||||||
| Database | Dolt (version-controlled SQL) |
|
| Realtime | Chokidar, Server-Sent Events |
|
||||||
| Realtime | Chokidar watchers, Server-Sent Events |
|
| Database | Dolt (optional, version-controlled SQL) |
|
||||||
| Validation | Zod schemas, strict TypeScript |
|
| Agent runtime | @mariozechner/pi-coding-agent (bb-pi, under construction) |
|
||||||
|
| Video | Remotion |
|
||||||
|
|
||||||
### Data Flow
|
### View routing
|
||||||
|
|
||||||
1. **Write Path**: `bd` commands write to `.beads/issues.jsonl` and Dolt DB
|
All active views live at `/` with query-param switching. Legacy routes redirect:
|
||||||
2. **Read Path**: UI queries Dolt SQL server (falls back to JSONL if unreachable)
|
|
||||||
3. **Realtime**: `bd` touches `.beads/last-touched` → Chokidar fires → SSE event → UI update
|
|
||||||
|
|
||||||
### Runtime Artifacts
|
|
||||||
|
|
||||||
| Directory | Purpose | Git Status |
|
|
||||||
|-----------|---------|------------|
|
|
||||||
| `.beads/` | Beads database, issues, coordination state | gitignored |
|
|
||||||
| `.agents/` | Agent skills and configuration | gitignored |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Project Structure
|
|
||||||
|
|
||||||
```text
|
|
||||||
beadboard/
|
|
||||||
├── src/
|
|
||||||
│ ├── app/
|
|
||||||
│ │ ├── page.tsx # Active runtime route
|
|
||||||
│ │ └── api/ # Runtime API routes
|
|
||||||
│ ├── components/
|
|
||||||
│ │ ├── shared/ # Reusable UI components
|
|
||||||
│ │ ├── graph/ # Dependency graph components
|
|
||||||
│ │ ├── social/ # Social/activity views
|
|
||||||
│ │ ├── swarm/ # Swarm coordination panel
|
|
||||||
│ │ └── sessions/ # Agent session components
|
|
||||||
│ ├── hooks/ # React hooks
|
|
||||||
│ └── lib/ # Core domain logic
|
|
||||||
├── skills/
|
|
||||||
│ └── beadboard-driver/ # Agent skill package
|
|
||||||
├── install/ # Platform install scripts
|
|
||||||
├── reference/
|
|
||||||
│ └── routes/ # Archived route implementations
|
|
||||||
├── docs/ # Documentation
|
|
||||||
└── tests/ # Test suite
|
|
||||||
```
|
|
||||||
|
|
||||||
### Key Files
|
|
||||||
|
|
||||||
| File | Purpose |
|
|
||||||
|------|---------|
|
|
||||||
| `src/app/page.tsx` | Main dashboard entry point |
|
|
||||||
| `src/lib/` | Core domain: Beads model, graph builders, coordination |
|
|
||||||
| `skills/beadboard-driver/SKILL.md` | Agent operating contract |
|
|
||||||
| `AGENTS.md` | Agent operating manual for this repo |
|
|
||||||
| `next.config.ts` | Route redirects and Next.js config |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Routes
|
|
||||||
|
|
||||||
### Active Route
|
|
||||||
|
|
||||||
- `/` - Main dashboard (query-driven)
|
|
||||||
|
|
||||||
### View Modes
|
|
||||||
|
|
||||||
| URL | View |
|
| URL | View |
|
||||||
|-----|------|
|
|-----|------|
|
||||||
| `/?view=social` | Agent social feed |
|
| `/?view=social` | Social feed |
|
||||||
| `/?view=graph` | Dependency graph |
|
| `/?view=graph` | Dependency graph |
|
||||||
| `/?view=activity` | Activity timeline |
|
| `/?view=activity` | Activity timeline |
|
||||||
|
| `/graph`, `/sessions`, `/timeline` | Redirect to unified shell equivalents |
|
||||||
|
|
||||||
### Compatibility Redirects
|
---
|
||||||
|
|
||||||
| Old Route | Redirects To |
|
## CLI Reference
|
||||||
|-----------|--------------|
|
|
||||||
| `/graph` | `/?view=graph` |
|
### bd (Beads CLI)
|
||||||
| `/sessions` | `/?view=social` |
|
|
||||||
| `/timeline` | `/?view=activity` |
|
```bash
|
||||||
| `/mockup` | `/` |
|
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)
|
||||||
|
|
||||||
|
```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
|
## Contributing
|
||||||
|
|
||||||
### Development Workflow
|
1. Fork the repo and create a feature branch.
|
||||||
|
2. Run quality gates before submitting:
|
||||||
1. Fork the repository
|
|
||||||
2. Create a feature branch: `git checkout -b feature/my-feature`
|
|
||||||
3. Make changes following existing patterns
|
|
||||||
4. Run quality gates:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run typecheck
|
npm run typecheck && npm run lint && npm run test
|
||||||
npm run lint
|
|
||||||
npm run test
|
|
||||||
```
|
```
|
||||||
|
|
||||||
5. Submit a pull request
|
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`.
|
||||||
### Code Guidelines
|
5. Submit a pull request against `main`.
|
||||||
|
|
||||||
- Keep active runtime pages minimal in `src/app`
|
|
||||||
- Promote reusable logic to `src/lib`, `src/components`, `src/hooks`
|
|
||||||
- Archive experimental routes in `reference/routes`
|
|
||||||
- Follow existing TypeScript and React patterns
|
|
||||||
- Add tests for new functionality
|
|
||||||
|
|
||||||
### Code of Conduct
|
|
||||||
|
|
||||||
- Be respectful and inclusive
|
|
||||||
- Focus on constructive feedback
|
|
||||||
- Support newcomers to the project
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Scripts
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run dev # Development server
|
|
||||||
npm run build # Production build
|
|
||||||
npm run start # Production server
|
|
||||||
npm run typecheck # TypeScript validation
|
|
||||||
npm run lint # ESLint
|
|
||||||
npm run test # Test suite
|
|
||||||
npm run video # Remotion video preview
|
|
||||||
npm run video:render # Render video
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Changelog
|
|
||||||
|
|
||||||
### v0.1.0 (Current)
|
|
||||||
|
|
||||||
- Initial release
|
|
||||||
- Multi-agent coordination system
|
|
||||||
- Graph-based dependency visualization
|
|
||||||
- Real-time updates via SSE
|
|
||||||
- Agent mail and communication system
|
|
||||||
- Swarm coordination panel
|
|
||||||
- Global project scope switching
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Roadmap
|
|
||||||
|
|
||||||
- Cross-view assignment controls in all major views
|
|
||||||
- Enhanced swarm UX and terminology
|
|
||||||
- Expanded global project configuration workflows
|
|
||||||
- Witness enforcement layer for agent liveness
|
|
||||||
- Additional graph analysis features
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -555,8 +264,6 @@ npm run video:render # Render video
|
||||||
|
|
||||||
[MIT](LICENSE)
|
[MIT](LICENSE)
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Acknowledgments
|
## Acknowledgments
|
||||||
|
|
||||||
Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](https://github.com/steveyegge/gastown). Thanks [Steve Yegge](https://github.com/steveyegge)!
|
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).
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
'use client';
|
'use client';
|
||||||
|
|
||||||
import { useEffect, useMemo, useState } from 'react';
|
import { useEffect, useMemo, useState } from 'react';
|
||||||
import { Send } from 'lucide-react';
|
import { Construction, Send } from 'lucide-react';
|
||||||
import type { RuntimeInstance } from '../../lib/embedded-runtime';
|
import type { RuntimeInstance } from '../../lib/embedded-runtime';
|
||||||
import type { OrchestratorChatMessage } from '../../lib/orchestrator-chat';
|
import type { OrchestratorChatMessage } from '../../lib/orchestrator-chat';
|
||||||
|
|
||||||
|
|
@ -55,6 +55,13 @@ export function OrchestratorPanel({ orchestrator, thread, projectRoot }: Orchest
|
||||||
return (
|
return (
|
||||||
<div className="flex h-full min-h-0 flex-col" data-testid="orchestrator-panel">
|
<div className="flex h-full min-h-0 flex-col" data-testid="orchestrator-panel">
|
||||||
<div className="border-b border-[var(--border-subtle)] px-4 py-3">
|
<div className="border-b border-[var(--border-subtle)] px-4 py-3">
|
||||||
|
<div className="mb-2 flex items-center gap-2 rounded-md border border-amber-500/30 bg-amber-500/10 px-3 py-2">
|
||||||
|
<Construction size={14} className="shrink-0 text-amber-400" />
|
||||||
|
<p className="text-xs text-amber-200">
|
||||||
|
Under construction — orchestrator has known issues being actively fixed.
|
||||||
|
<a href="https://github.com/zenchantlive/beadboard" target="_blank" rel="noopener noreferrer" className="ml-1 underline hover:text-amber-100">Track progress</a>
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
<p className="font-mono text-[10px] uppercase tracking-[0.14em] text-[var(--text-tertiary)]">Main Orchestrator</p>
|
<p className="font-mono text-[10px] uppercase tracking-[0.14em] text-[var(--text-tertiary)]">Main Orchestrator</p>
|
||||||
<div className="mt-2 flex items-center justify-between gap-2">
|
<div className="mt-2 flex items-center justify-between gap-2">
|
||||||
<div>
|
<div>
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue