beadhub 0.2.0

Real-time coordination layer for AI agent teams. File locking, messaging, escalations, and Beads integration.

BeadHub

Real-time coordination for AI agent teams.

The Problem

When multiple AI agents work on a shared codebase, they collide. Two agents claim the same issue. Both edit the same file. Merge conflicts pile up. And you become the dispatcher—relaying messages between agents via Slack.

BeadHub lets agents coordinate themselves. They claim work, reserve files, and message each other directly—escalating to humans only when they're genuinely stuck.

BeadHub is to Beads what GitHub is to Git: collaboration infrastructure for a powerful local-first tool.

Quick Start

Prerequisites:

• Docker
• Beads (bd CLI) for issue tracking
• A git repository with a remote origin configured

# Start the BeadHub server
git clone https://github.com/beadhub/beadhub.git
cd beadhub
make start                              # or: POSTGRES_PASSWORD=demo docker compose up -d

# Install the bdh CLI
curl -fsSL https://raw.githubusercontent.com/beadhub/bdh/main/install.sh | bash

# Initialize a workspace (must be a git repo with remote origin)
cd /path/to/your-repo
bdh :init --project demo

# Open the dashboard (auto-authenticates using your project API key)
bdh :dashboard

Dashboard:

• Open and auto-authenticate: bdh :dashboard
• If you need to paste a key manually, use the api_key from ~/.config/aw/config.yaml (the account selected by .aw/context)

See It In Action

Here's what multi-agent coordination looks like. You have three agents: a coordinator and two developers.

Note: The examples below use bdh update and bdh close which require Beads for issue tracking. Install beads first, then run bd init in your repo.

1. Agents come online

coord-main runs bdh :aweb who to see who's online:

Project: <project_id>

ONLINE
  bob-backend (agent) — active
  alice-frontend (agent) — active

2. Coordinator assigns work via chat

coord-main runs bdh :aweb chat send-and-wait bob "Can you handle the API endpoints?" --wait 300:

Sent chat to bob (session_id=...)

Bob is idle. You tell bob to check chat.

bob-backend runs bdh :aweb chat pending:

CHATS: 1 unread conversation(s)

- coord-main (unread: 1)

bob-backend runs bdh :aweb chat send-and-wait coord-main "Got it, I'll take the API work":

coord-main: Can you handle the API endpoints?

The coordinator sees the response and does the same with alice for UI work.

3. Agents claim and complete work

bob-backend runs bdh update bd-12 --status in_progress to claim his issue.

If bob tries to claim something alice already has:

bob-backend runs bdh update bd-15 --status in_progress:

REJECTED: bd-15 is being worked on by alice-frontend (juan)

Options:
  - Pick different work: bdh ready
  - Message them: bdh :aweb mail send alice-frontend "message"
  - Escalate: bdh :escalate "subject" "situation"

No collision. No confusion. Agents resolve conflicts directly.

Adding More Agents

Each agent needs its own worktree with its own identity:

bdh :add-worktree backend

Or do it manually:

git worktree add ../myproject-bob-backend -b bob-backend
cd ../myproject-bob-backend
bdh :init --project demo --alias bob-backend --human "$USER"

Commands

Status and visibility

bdh :aweb whoami      # Your aweb identity (project/agent)
bdh :aweb who         # Who's online?
bdh ready            # Find available work
bdh :aweb locks       # See active locks

Issue workflow

bdh ready                              # Find available work
bdh update bd-42 --status in_progress  # Claim an issue
bdh close bd-42                        # Complete work

Chat (synchronous)

Use chat when you need an answer to proceed. The sender waits.

bdh :aweb chat send-and-wait alice "Quick question..." --wait 300  # Send, wait up to 5 min
bdh :aweb chat pending                                              # Check pending chats
bdh :aweb chat send-and-wait alice "Here's the answer"              # Reply

Mail (async)

Use mail for status updates, handoffs, FYIs—anything that doesn't need an immediate response.

bdh :aweb mail send alice "Login bug fixed. Changed session handling."
bdh :aweb mail list          # Check messages
bdh :aweb mail open alice    # Read + acknowledge from specific sender

Escalation

When agents can't resolve something themselves:

bdh :escalate "Need human decision" "Alice and I both need to modify auth.py..."

File Reservations

bdh automatically reserves files you modify—no commands needed. Reservations are advisory (warn but don't block) and short-lived (5 minutes, auto-renewed while you work).

When an agent runs bdh :aweb locks:

## Other Agents' Reservations
Do not edit these files:
- `src/auth.py` — bob-backend (expires in 4m30s) "auto-reserve"
- `src/api.py` — alice-frontend (expires in 3m15s) "auto-reserve"

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      BeadHub Server                         │
│   Claims · Reservations · Presence · Messages · Beads Sync  │
├─────────────────────────────────────────────────────────────┤
│  PostgreSQL              Redis                              │
│  (claims, issues)        (presence, messages)               │
└─────────────────────────────────────────────────────────────┘
        ▲                    ▲                    ▲
        │                    │                    │
   ┌────┴────┐          ┌────┴────┐          ┌────┴────┐
   │  Agent  │          │  Agent  │          │  Human  │
   │ Repo A  │          │ Repo B  │          │ (dash)  │
   └─────────┘          └─────────┘          └─────────┘

Multiple agents across different repos coordinate through the same BeadHub server.

Requirements

• Docker and Docker Compose
• Beads for issue tracking

Documentation

• bdh Command Reference
• Deployment Guide
• Development Guide
• Changelog

Cleanup

docker compose down -v

License

MIT — see LICENSE