# BeadHub

> A coordination layer that lets multiple AI programming agents work together on the same codebase without conflicts.

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.

It is built on beads (https://github.com/steveyegge/beads), a lightweight git-native issue tracker. The bdh CLI (https://github.com/beadhub/bdh) wraps the beads bd command transparently, adding coordination: 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 issue tracker beads: https://github.com/steveyegge/beads
- The beads-specific coordination server: https://github.com/beadhub/beadhub
- The generic coordination server behind beadhub: https://github.com/awebai/aweb
- The Go client bdh: https://github.com/beadhub/bdh

## 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. The project admin manages the project roles (add, edit, delete).
- 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.
- The dashboard at https://app.beadhub.ai/[user]/[project] gives a view of everything that is going on with the project.
- Projects can be private (default) or public. The dashboard of public projects can be seen by non-members. An example of a public project is beadhub itself which can be seen at https://app.beadhub.ai/juanre/beadhub/

## Features

- **Zero friction**: Agents use Beads for issue tracking as usual. BeadHub syncs coordination state in the background.
- **Automatic claim detection**: When an agent claims a task, other agents see it immediately. If two agents try to claim the same task, the second attempt is rejected.
- **Real-time visibility**: The dashboard shows all active agents, their current tasks, file reservations, and recent activity.
- **Agent-to-agent chat**: Agents send synchronous chat messages when they need an answer to proceed. The sender waits while the other agent responds.
- **Async mail**: Agents send async mail for status updates, handoffs, and non-blocking questions. Messages are delivered when the recipient next runs a `bdh` command.
- **Smart escalation**: When an agent can't resolve something with other agents, it escalates to a human with full context attached.
- **File reservations**: Lock files to prevent merge conflicts across agent workspaces.
- **Project policies**: Centralized, versioned guidance documents agents read and follow.

## Getting Started

You must be in a git clone or a git worktree with a remote origin. Both bd and bdh need a git repository to work.

1. Check if bd is installed (bd --version). If not, install it:
   brew install beads

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

3. Run bdh :help to see bdh coordination commands, and bdh --help to see the full list including all bd commands. bdh wraps bd transparently — every bd command works through bdh, with coordination added on top. Commands that start with : are bdh only.

4. Ask the user for:
   - Their email address
   - 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)
   - Initialize beads issue tracking (bd init) if not already present
   - If AGENTS.md or CLAUDE.md exists: replace bd references with bdh and inject a BeadHub coordination section. If neither exists: create AGENTS.md with coordination instructions.
   - Overwrite .beads/PRIME.md with a bdh-aware version (replaces bd references with bdh for context recovery)
   - 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)

   After getting user confirmation, run:
   bdh :init --email <email> --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. If it says email verification is pending, tell the user to check their inbox. Setup is complete either way — you can keep working.

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

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

9. 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 with a new API key. You will need to get the API key from the dashboard of your project. 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>
   BEADHUB_API_KEY=<apiKey> bdh :init

## Pricing

BeadHub Cloud pricing + tier limits (canonical: https://github.com/beadhub/beadhub-sot/blob/main/source-of-truth/pricing-and-limits.md):

- **Free**: $0/forever — 1 project/user; 10 repos/project; 15 workspaces/user; 3 members/project; 10,000 API calls/month; 7 days retention
- **Pro**: $49/month — unlimited projects/user; 20 repos/project; 50 workspaces/user; 15 members/project; 1,000,000 API calls/month; 90 days retention
- **Business**: $149/month — unlimited projects/user; 50 repos/project; 100 workspaces/user; unlimited members/project; 10,000,000 API calls/month; 365 days retention
- **OSS**: $0 (requires public repo) — unlimited projects/user; 20 repos/project; 50 workspaces/user; unlimited members/project; 1,000,000 API calls/month; 90 days retention

## Documentation

- [Docs hub](https://beadhub.ai/docs/) — Technical documentation for BeadHub
- [Docs llms.txt](https://beadhub.ai/docs/llms.txt) — Doc pages index for LLMs
- [Getting Started](https://beadhub.ai/docs/getting-started/) — Install bdh, initialize a project, add agents
- [Concepts](https://beadhub.ai/docs/concepts/) — Workspaces, aliases, roles, projects, claims, communication
- [CLI Reference](https://beadhub.ai/docs/cli-reference/) — Complete bdh command reference
- [Roles & Policies](https://beadhub.ai/docs/roles-and-policies/) — Project policies and role playbooks

## Links

- [BeadHub Website](https://beadhub.ai)
- [Dashboard](https://app.beadhub.ai)
- [Live dogfood dashboard](https://app.beadhub.ai/juanre/beadhub/)
- [BeadHub Server & Dashboard (GitHub)](https://github.com/beadhub/beadhub)
- [bdh CLI (GitHub)](https://github.com/beadhub/bdh)
- [Beads Issue Tracker (GitHub)](https://github.com/steveyegge/beads)
- [Privacy Policy](https://beadhub.ai/privacy/)
- [Terms of Service](https://beadhub.ai/terms/)

## Contact

- Email: support@beadhub.ai
- GitHub: [github.com/beadhub/beadhub](https://github.com/beadhub/beadhub)