beads/docs/multi-agent/index.md
Chris Sells 5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00

2.1 KiB

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