Multi-Agent

Beads supports coordination between multiple AI agents and repositories.

Overview

Multi-agent features enable:

• Routing - Automatic issue routing to correct repositories
• Cross-repo dependencies - Dependencies across repository boundaries
• Agent coordination - Work assignment and handoff between agents

Key Concepts

Routing

Routing decides which repository a new bead lands in, based on your role (contributor vs maintainer) and the routing.* config keys — an explicit --repo flag always wins. See Multi-Repo Routing for the decision flow and configuration reference.

Work Assignment

Assign or atomically claim work:

bd assign bd-42 agent-1        # shorthand for bd update bd-42 --assignee agent-1
bd update bd-42 --claim        # atomically set assignee + in_progress
bd ready --claim --json        # claim the first ready match

Cross-repo Dependencies

Track dependencies across repositories:

bd dep add bd-42 external:other-repo:api-ready

Architecture

┌─────────────────┐
│   Main Repo     │
│   (coordinator) │
└────────┬────────┘
         │ routes
    ┌────┴────┐
    │         │
┌───▼───┐ ┌───▼───┐
│Frontend│ │Backend│
│ Repo   │ │ Repo  │
└────────┘ └────────┘

Getting Started

1. Single repo: Standard beads workflow
2. Multi-repo: Configure routes and cross-repo deps
3. Multi-agent: Add work assignment and handoff

Pages in this section

• Routing — automatic issue routing across repositories and BEADS_DIR resolution.
• Coordination — work assignment and handoff patterns between agents.
• Federation — peer-to-peer sharing of beads across repos and organizations.
• Bucket Federation Quickstart — federate two machines through a GCS or S3 bucket, with no server to run.
• Multi-Repo Migration — moving an existing single-repo setup to multi-repo routing.