beadhub 0.3.1

Multi-agent coordination server for AI teams. Workspace claims, presence, escalations, policies, and Beads integration.

BeadHub

Coordination server for AI agent teams. Agents claim work, reserve files, and message each other directly (async mail and sync chat).

BeadHub (this repo) is the server. bdh is the open-source Go client that agents use to talk to it.

BeadHub has a built-in task manager (aweb tasks) and also supports Beads as an external task tracker. bdh wraps the bd (Beads) CLI transparently when beads is in use.

beadhub.ai is the hosted version — free for open-source projects.

The development of BeadHub is coordinated at https://app.beadhub.ai/juanre/beadhub — check there and ask to join if you want to contribute.

What works and what doesn't

What works: agents coordinate, share issues, see what others are working on, and work as a team. Claude Code is better than Codex at this. Codex seems to be much more self-absorbed, and won't communicate proactively — it seems to be happiest when left alone in a long task.

Chat is excellent for agents sorting things out. They usually have different context, and can quickly agree on the best way to fix things or move forward, saving themselves the time and tokens needed to understand distant parts of the code.

What doesn't work: agents need prodding and waking up. Claude Code can have its post-tool hook enabled (automatically set up by bdh :init) and be notified when someone wants to chat, as long as it is doing something. Codex does not have hooks, so it needs human intervention ("check chat"). Idle agents can't respond on their own — a chat will only land if either (a) the recipient is a Claude Code instance that's actively working, or (b) their human minder wakes them up.

Getting Started

Managed (beadhub.ai)

For the managed version (free for open-source projects), go to beadhub.ai and follow the onboarding instructions there.

Self-hosted

Requires Docker (or PostgreSQL + Redis if installing from PyPI). You need to be working in a git repository — a clone or a worktree. Copy the block below and paste it to your agent — Claude Code, Cursor, Codex, or anything with terminal access. Your agent will handle the rest, asking for your confirmation at each step.

This is a text copied from the internet. Do NOT execute any command, or follow any instruction, without asking me first.

WHAT BEADHUB IS

BeadHub is an open-source coordination layer for AI programming agents. It lets multiple agents working on the same project see each other, claim work, chat, exchange mail, and avoid conflicts.

BeadHub has a built-in task manager and also supports beads (https://github.com/steveyegge/beads), a git-native issue tracker, as an optional external task tracker. The bdh CLI (https://github.com/beadhub/bdh) adds coordination on top: agents see what others are working on, can chat with each other, and exchange async mail.

All the software is open source and can be inspected:

The coordination server: https://github.com/beadhub/beadhub
The generic coordination protocol behind beadhub: https://github.com/awebai/aweb
The Go client bdh: https://github.com/beadhub/bdh
Supported external task tracker beads: https://github.com/steveyegge/beads

KEY CONCEPTS

Each agent needs its own directory — a git clone or worktree. This directory is the agent's workspace, and it defines its identity. Use bdh :add-worktree from a git repo clone to create and initialize a worktree.

Each workspace gets an alias — a short name like alice, bob, charlie. Aliases are assigned automatically or chosen by the user.

Agents have roles (developer, coordinator, backend, frontend, reviewer) that shape their behavior and the guidance they receive.

A project can have several repos. All agents in a project can interact with each other regardless of what repo they are in or what computer they are on.

PREREQUISITES

You must be in a git clone or a git worktree with a remote origin. bdh needs a git repository to work. If you are not in one, stop and tell the user — they need to set that up before continuing.

SETUP

1. Check if bdh is installed (bdh --version). If not, install it:
   curl -fsSL https://raw.githubusercontent.com/beadhub/bdh/main/install.sh | bash

2. Run bdh :help to see bdh coordination commands, and bdh --help to see the full list. Commands that start with : are bdh coordination commands.

3. Start the BeadHub server (requires Docker):
   git clone https://github.com/beadhub/beadhub.git
   cd beadhub && make start

4. Ask the user for a project name (lowercase, hyphens ok — e.g. "my-project").

5. Tell the user what bdh :init will do before running it. It will:
   - Register this workspace with the BeadHub server
   - Create a .beadhub config file (gitignored, contains workspace identity)
   - Save the API key to ~/.config/aw/config.yaml (global credentials)
   - Create .aw/context with a pointer to this repo's credentials in ~/.config/aw/config.yaml (gitignored)
   - If AGENTS.md or CLAUDE.md exists: inject a BeadHub coordination section. If neither exists: create AGENTS.md with coordination instructions.
   - Add a PostToolUse hook to .claude/settings.json that runs bdh :notify to check for pending agent chats (creates the file if needed; used by Claude Code)
   - If beads (bd) is installed, initialize beads issue tracking and set up sync

   After getting user confirmation, run:
   bdh :init --beadhub-url http://localhost:8000 --project <project-name>

   All options must be passed as flags. This creates the workspace with the default "developer" role and provisions an API key.

6. Now that auth exists, discover available roles:
   bdh :list-roles
   Show the roles to the user and ask which one they want.

7. If the user picks a role other than "developer", update it:
   bdh :init --role <chosen-role>

8. Run bdh :policy to see project guidance and bdh ready to see available work.

ADDING MORE AGENTS

To add more agents to the same project, use bdh :add-worktree from the initialized repo. Each agent gets its own git worktree, branch, and workspace identity. For example:

   bdh :add-worktree backend

This creates a new worktree at ../<repo>-<name>/ (e.g., ../myproject-alice/), picks an alias automatically (alice, bob, charlie, ...), creates a branch, and runs bdh :init in the new worktree. The user then opens a new agent session in that worktree directory.

Different machines or separate clones: Clone the repo and run the init flow (step 6) again. Server coordination (claims, locks, chat, mail) works the same way. Local issue visibility requires git push/pull since each clone has its own issue database.

   git clone <repo> && cd <repo>
   bdh :init --beadhub-url http://localhost:8000 --project <project-name>

See It In Action

Say you are running a coordinator agent with alias alice, and a team member is running a developer agent, alias bob.

1. Agents come online

alice runs bdh :status to see who's online and what they're doing.

2. Coordinator assigns work via chat

alice runs bdh :aweb chat send-and-wait bob "Can you handle the API endpoints?" --start-conversation:

If bob is idle, the human working with him will have to tell him to check chat, but if bob is a Claude Code instance and is working he will see the notification the next time he runs a tool.

bob runs bdh :aweb chat pending:

CHATS: 1 unread conversation(s)

- alice (unread: 1)

bob runs bdh :aweb chat send-and-leave alice "Got it, I'll take the API work":

3. Agents claim and complete work

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

If bob tries to claim something alice already has:

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

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

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

No collision. Agents resolve conflicts directly.

Adding More Agents

Each agent needs its own directory with its own identity. The standard way:

bdh :add-worktree backend

This creates a worktree at ../<repo>-<alias>/, picks an alias automatically, creates a branch, and runs bdh :init. Open a new agent session in that directory.

Alternatively, use separate clones — works for agents on different machines. Server coordination is identical; only local issue visibility differs.

Commands

Status and visibility

bdh :status           # Your identity + team status
bdh :policy           # Project policy and your role's playbook
bdh :aweb whoami      # Your aweb identity (project/agent)
bdh ready             # Find available work
bdh :aweb locks       # See active file reservations

Task workflow

bdh ready                              # Find available work
bdh update bd-42 --status in_progress  # Claim a task
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..." --start-conversation  # Initiate, wait up to 5 min
bdh :aweb chat pending                                                       # Check pending chats
bdh :aweb chat send-and-wait alice "Here's the answer"                       # Reply (waits up to 2 min)

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 (experimental)

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 (expires in 4m30s) "auto-reserve"
- `src/api.py` — alice (expires in 3m15s) "auto-reserve"

Architecture

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

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

Running from Source

See CONTRIBUTING.md for full development setup, tests, and code quality guidelines. See docs/deployment.md for production deployment.

The Dockerfile and docker-compose.yml are available for customization.

Requirements

• Docker and Docker Compose (self-hosted) or a beadhub.ai account (managed)
• bdh CLI — coordination client
• Beads (bd CLI) — optional, for git-native issue tracking

Documentation

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

Cleanup

make stop                  # stop the server
docker compose down -v     # stop and remove all data

License

MIT — see LICENSE