Multi-Agent

​

Overview

• 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

​

Work Assignment

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

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.