beads/docs/multi-agent/index.md
Chris Sells 69e33099b8 docs: apply PR #4722 review feedback to user docs
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
2026-07-12 11:06:57 -07:00

2.2 KiB

title description
Multi-Agent Coordinate beads across multiple agents and repositories with routing, cross-repo dependencies, and work handoff

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.
  • Multi-Repo Migration — moving an existing single-repo setup to multi-repo routing.