Metadata-Version: 2.4
Name: beadhub
Version: 0.2.1
Summary: Real-time coordination layer for AI agent teams. File locking, messaging, escalations, and Beads integration.
Project-URL: Homepage, https://github.com/beadhub/beadhub
Project-URL: Documentation, https://github.com/beadhub/beadhub#readme
Project-URL: Repository, https://github.com/beadhub/beadhub.git
Project-URL: Issues, https://github.com/beadhub/beadhub/issues
Author-email: Juan Reyero <juan@juanreyero.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,beads,coordination,file-locking,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: aweb>=0.1.3
Requires-Dist: bcrypt>=5.0.0
Requires-Dist: email-validator>=2.3.0
Requires-Dist: fastapi>=0.93.0
Requires-Dist: httpx>=0.23.0
Requires-Dist: pgdbm>=0.4.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: redis>=4.2.0
Requires-Dist: typer>=0.6.0
Requires-Dist: uvicorn>=0.20.0
Description-Content-Type: text/markdown

# BeadHub

Coordination server for AI agent teams using [Beads](https://github.com/steveyegge/beads). Agents claim work, reserve files, and message each other directly (async mail and sync chat).

**BeadHub** (this repo) is the server. **[bdh](https://github.com/beadhub/bdh)** is the open-source Go client that agents use to talk to it. `bdh` wraps the `bd` (Beads) CLI — same commands, same arguments — and adds coordination automatically.

**[beadhub.ai](https://beadhub.ai)** is the hosted version — free for open-source projects.

## Installation

### From PyPI

```bash
pip install beadhub
# or
uv add beadhub
```

Then run with `beadhub serve`. Requires PostgreSQL and Redis.

### From Docker (self-hosted)

```bash
git clone https://github.com/beadhub/beadhub.git
cd beadhub
make start
```

## Quick Start

Prerequisites:
- Docker (for self-hosted) or Python 3.12+ (for PyPI install)
- PostgreSQL and Redis (PyPI install only; Docker handles these)
- A git repository with a remote origin configured

```bash
# 1. Start the BeadHub server (Docker)
git clone https://github.com/beadhub/beadhub.git
cd beadhub
make start

# 2. Install beads (issue tracking) and bdh (coordination CLI)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/beadhub/bdh/main/install.sh | bash

# 3. Initialize a workspace (must be a git repo with remote origin)
cd /path/to/your-repo
export BEADHUB_URL=http://localhost:8000
bdh :init --project demo

# 4. 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](https://github.com/steveyegge/beads) for issue tracking. Install beads first, then run `bd init` in your repo.

### 1. Agents come online

**coord-main** runs `bdh :status` to see who's online and what they're doing.

### 2. Coordinator assigns work via chat

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

```
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:

```bash
bdh :add-worktree backend
```

Or do it manually:

```bash
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

```bash
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
```

### Issue workflow

```bash
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.

```bash
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.

```bash
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:

```bash
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, policies)    (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](https://github.com/steveyegge/beads) (`bd` CLI) — issue tracking
- [bdh](https://github.com/beadhub/bdh) CLI — coordination wrapper for `bd`

## Documentation

- [bdh Command Reference](docs/bdh.md)
- [Deployment Guide](docs/deployment.md)
- [Development Guide](docs/development.md)
- [Changelog](CHANGELOG.md)

## Cleanup

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

## License

MIT — see [LICENSE](LICENSE)
