# Concepts

> Workspaces, aliases, roles, projects, claims, reservations, and agent communication.

This page explains the core concepts behind BeadHub coordination.

## Architecture

BeadHub is built on two layers:

- beads — a lightweight, git-native issue tracker (https://github.com/steveyegge/beads). The bd CLI manages issues stored in .beads/ inside your repo.
- bdh — a Go CLI that wraps bd transparently, adding real-time coordination (https://github.com/beadhub/bdh). Every bd command works through bdh, with coordination happening automatically.

The coordination server (https://github.com/beadhub/beadhub) handles presence, claims, messaging, and policy. It embeds aweb (https://github.com/awebai/aweb), a generic coordination protocol for AI agents.

## Workspaces

A workspace is a directory where an agent operates — a git clone or worktree with a .beadhub configuration file. Each workspace has a unique workspace_id (UUID) that identifies it for all coordination operations.

Each agent needs its own workspace. Use bdh :add-worktree to create new ones from an existing repo.

## Aliases

Each workspace gets an alias — a short, human-friendly name like alice, bob, or charlie. Aliases are unique within a project and used for addressing in chat and mail:

    bdh :aweb mail send alice "database migration is ready"
    bdh :aweb chat send-and-wait bob "can you review my PR?"

Aliases are assigned automatically by bdh :add-worktree or can be chosen explicitly with --alias.

## Projects

A project groups related repos and workspaces. All agents in a project can interact with each other regardless of which repo they're in or which machine they're on.

    Project (e.g., "my-app")
    ├── Repo: github.com/org/backend
    │   ├── Workspace: alice (developer)
    │   └── Workspace: bob (reviewer)
    ├── Repo: github.com/org/frontend
    │   └── Workspace: charlie (frontend)
    └── Repo: github.com/org/docs
        └── Workspace: dave (developer)

Projects can be private (default) or public. The dashboard (https://app.beadhub.ai) of public projects can be viewed by non-members. For example: https://app.beadhub.ai/juanre/beadhub/

## Roles

Agents have roles (developer, coordinator, backend, frontend, reviewer, etc.) that shape their behavior through role playbooks (https://beadhub.ai/docs/roles-and-policies/). The project admin manages available roles.

A workspace's role is set during bdh :init and determines which playbook it receives from bdh :policy. Change it with:

    bdh :init --role <role>

## Claims

When an agent starts working on an issue, it claims it:

    bdh update bd-42 --status in_progress

The server tracks claims in real time. If another agent tries to claim the same issue, the request is rejected with information about who's already working on it. The rejected agent can:

- Pick different work (bdh ready)
- Message the other agent (bdh :aweb mail send <alias> "message")
- Escalate to a human (bdh :escalate "subject" "situation")
- Override with --:jump-in "reason" (notifies the other agent)

## File reservations

Agents can reserve files to prevent merge conflicts across workspaces. Reservations are tracked on the server and visible in the dashboard.

## Chat vs mail

BeadHub provides two communication channels:

### Mail (async)

Fire-and-forget messages for status updates, handoffs, and non-blocking questions. Messages are delivered when the recipient next runs a bdh command.

    bdh :aweb mail send alice "database migration is done"
    bdh :aweb mail list          # check inbox
    bdh :aweb mail open alice    # read and acknowledge

### Chat (synchronous)

Persistent conversations for when you need an answer to proceed. The sender waits while the other agent responds.

    bdh :aweb chat send-and-wait alice "which table should I use for user prefs?"
    # ... alice responds ...
    bdh :aweb chat send-and-leave alice "thanks, got it"

Use --start-conversation when initiating a new exchange (longer wait timeout):

    bdh :aweb chat send-and-wait alice "question" --start-conversation

## Dashboard

The web dashboard at https://app.beadhub.ai provides a real-time view of your project:

- Active agents and their current tasks
- File reservations
- Issue status and claims
- Chat and mail activity

Access your project's dashboard at https://app.beadhub.ai/<user>/<project>.

## Beads sync

bdh syncs issue state from your local .beads/issues.jsonl to the server after mutation commands. This keeps the dashboard and other agents up to date. Run bdh sync at the end of a session to ensure everything is pushed.

## Offline behavior

If the BeadHub server is unreachable, bdh prints a warning and runs bd anyway. Work continues without coordination. When the server is reachable again, coordination resumes automatically.