No description
| .agent/skills/shadcn-ui | ||
| .agents/skills | ||
| .augment/skills/shadcn-ui | ||
| .beads | ||
| .claude/skills/shadcn-ui | ||
| .cline/skills/shadcn-ui | ||
| .dolt | ||
| .github/agents | ||
| .openhands/skills/shadcn-ui | ||
| assets | ||
| components/ui | ||
| docs | ||
| help | ||
| lib | ||
| out | ||
| public | ||
| reference/routes | ||
| scripts | ||
| skills | ||
| src | ||
| tests | ||
| tools | ||
| .eslintrc.json | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| agents_to_delete.txt | ||
| agents_to_delete2.txt | ||
| all_beads.txt | ||
| bb.ps1 | ||
| bd-help.txt | ||
| CLAUDE.md | ||
| components.json | ||
| eslint-report.json | ||
| eslint.config.mjs | ||
| image-1.png | ||
| image-2.png | ||
| image-3.png | ||
| image-4.png | ||
| image-5.png | ||
| image-6.png | ||
| image-7.png | ||
| image-8.png | ||
| image-9.png | ||
| image.png | ||
| LICENSE | ||
| next-env.d.ts | ||
| next.config.ts | ||
| NEXT_SESSION_PROMPT.md | ||
| package-lock.json | ||
| package.json | ||
| postcss.config.js | ||
| README.md | ||
| remotion.config.ts | ||
| sse-output.txt | ||
| tailwind.config.ts | ||
| task1.txt | ||
| task2.txt | ||
| task3.txt | ||
| test-output.txt | ||
| test-output2.txt | ||
| test-sse.mjs | ||
| test-watcher.ts | ||
| test2.txt | ||
| tmp_diff.txt | ||
| tmp_status.txt | ||
| tsconfig.json | ||
BeadBoard
Work in Progress, please contribute! BeadBoard is a multi-agent swarm coordination system built on Beads inspired by Gastown. Thanks Steve Yegge!
BB is a visual operations layer for running agent teams against real dependency-constrained work.
What This App Is
BeadBoard is not just a task board. It is an execution system for coordinating agents around shared Beads workflows:
- Agent-to-agent communication with explicit categories (
HANDOFF,BLOCKED,DECISION,INFO) - 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
Core Features
1. Agent Communication System
- Structured message lifecycle:
send,inbox,read,ack - Message states:
unread,read,acked - Per-task conversation threads combining:
- activity events
- agent mail
- local bd interactions
- Required acknowledgment semantics for high-signal categories (
HANDOFF,BLOCKED)
2. Swarm Coordination Surface
- Agent Pool Monitor with:
- Archetypes
- Templates
- Needs Agent queue
- Pre-assigned queue
- Squad roster
- Assignment workflow through the graph workspace and right panel
3. Graph + Dependency Topology
- DAG-oriented graph workspace for execution decisions
- Task/dependency tab modes for different planning lenses
- Blocker/unblock context surfaced directly in task cards
- Graph analysis support (cycle and blocked-chain context)
4. Global Project Scope + Scanner
- Project registry and scanner-backed discovery
- Single-project and aggregate modes
- Runtime scope switching without leaving the primary workspace
5. Realtime Operations Layer
- Live updates via watchers + SSE
- Activity stream integration with session/task context
- Mutation/writeback feedback integrated into the same operational surface
Runtime Surface
Active Route
/
View Modes
/?view=social/?view=graph/?view=activity
Compatibility Redirects
/graph->/?view=graph/sessions->/?view=social/timeline->/?view=activity/mockup->/
Archived Route Vault
Legacy route implementations are preserved in reference/routes/** and excluded from active runtime validation scope.
Install
Prerequisites
- Node.js
18.18+(Node20 LTSrecommended) - npm
Clone + Install
git clone https://github.com/zenchantlive/beadboard.git
cd beadboard
npm install
Quick Start
npm run dev
Open:
http://localhost:3000
Configuration
No external service is required for core local usage.
Runtime behavior is driven by:
- Local Beads project data
- Registered/scanned project roots
- URL query state (
view,task,swarm,agent,epic,graphTab, panel state)
Operating Flow
1. Coordinate through Graph + Pool
Open /?view=graph, inspect dependency topology, and drive assignment from the pool panel.
2. Communicate in Context
Open a task thread to read merged conversation context and process message acknowledgments.
3. Switch Scope as Work Expands
Use registry/scanner controls to move between local and aggregate project scope.
4. Track Live Signal
Use social/activity views to monitor execution movement and operational events.
Roadmap Notes
- Cross-view assign controls in all major views.
- Social naming/UX evolution (including possible shift toward “swim” terminology).
- Continued expansion of global project config/scanner workflows.
Scripts
npm run dev
npm run build
npm run start
npm run typecheck
npm run lint
npm run test
npm run video
npm run video:render
npm run video:thumbnail
Architecture
- Frontend: Next.js App Router + React 19 + Tailwind + Framer Motion + Radix
- Graph stack: XYFlow + Dagre
- Core domain: Beads issue model, graph/kanban/session/social builders
- Coordination layer: agent mail + session communication + swarm orchestration state
- Realtime: watchers + SSE + snapshot differ + activity persistence
- Validation/typing: strict TypeScript + Zod contracts where applicable
Project Structure
src/
app/
page.tsx # active runtime route
api/ # runtime API routes
components/
shared/ graph/ social/ activity/ sessions/ swarm/ kanban/
hooks/
lib/
reference/
routes/ # archived route implementations
Contributing
- Keep active runtime pages in
src/appminimal. - Promote reusable logic into
src/lib,src/components,src/hooks. - Archive non-runtime route experiments in
reference/routes. - Run quality gates before merge:
npm run typecheck
npm run lint
npm run test
License
MIT