beads/docs/multi-agent/index.md
Steve Yegge 4ad99760b8 docs(federation): GCS/S3 BYO-bucket federation quickstart (wy-jpd3.8)
The gs:// remote path works — full clone of a 115k-chunk production DB in
5 seconds, incremental syncs in ~4s, ADC auth, zero servers — but nothing
in the docs said "point two machines at a bucket and you have a
federation", so discovering it meant reading Dolt internals.

New page docs/multi-agent/bucket-federation.md walks the whole path:
create the bucket path -> bd dolt remote add + bd dolt push to seed ->
bd init --remote to birth the second replica -> bd sync on a timer, with
the exit-code table a timer branches on and the three rules that set the
interval (staleness is the interval; lease TTL and reclaim grace must
exceed it; a longer interval means more conflicts, because updated_at is
touched by every mutation).

Carries the measured cost from a production two-machine deployment
(28s cold push, 5s clone, ~4s incremental push, ~1s pull+merge at ~1.3k
issues / ~115k chunks) and the failure modes that path actually hits:
raw `dolt remote add` leaving the SQL server blind to the remote, a
fresh machine with no Dolt commit identity failing even a no-op merge,
server-mode credentials being whatever the server inherited at startup
(GH#6), remote-name drift between replicas, conflict resolution through
the dolt_conflicts tables, and one bucket path per database.

Registered in the Mintlify nav and cross-linked from the multi-agent
index and from the federation guide, which keeps DoltHub as the
zero-config default and points here for the BYO-cloud story.
2026-08-12 04:15:56 -07:00

2.4 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.
  • 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.