ContextQMD
Back to Beads

Multi-Repo Patterns for AI Agents

docs/MULTI_REPO_AGENTS.md

1.0.310.0 KB
Original Source

Multi-Repo Patterns for AI Agents

This guide covers multi-repo workflow patterns specifically for AI agents working with beads.

For humans, see MULTI_REPO_MIGRATION.md for interactive wizards and detailed setup.

Quick Reference

Single MCP Server (Recommended)

AI agents should use one MCP server instance that automatically routes to per-project Dolt servers:

json
{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

The MCP server automatically:

  • Detects current workspace from working directory
  • Routes to correct per-project Dolt server
  • Auto-starts Dolt server if not running
  • Maintains complete database isolation

Architecture (default):

MCP Server (one instance)
    ↓
Per-Project Dolt Servers (one per workspace)
    ↓
Dolt Databases (complete isolation)

With shared server mode enabled (BEADS_DOLT_SHARED_SERVER=1), all projects use a single Dolt server at ~/.beads/shared-server/. Database isolation is maintained via per-project database names (based on project prefix).

Multi-Repo Config Options

Agents can configure multi-repo behavior via bd config:

bash
# Auto-routing (detects role: maintainer vs contributor)
bd config set routing.mode auto
bd config set routing.maintainer "."
bd config set routing.contributor "~/.beads-planning"

# Explicit routing (always use default)
bd config set routing.mode explicit
bd config set routing.default "."

# Multi-repo aggregation (hydration)
bd config set repos.primary "."
bd config set repos.additional "~/repo1,~/repo2,~/repo3"

Check current config:

bash
bd config get routing.mode
bd config get repos.additional
bd info --json  # Shows all config

Routing Behavior

Auto-Routing (OSS Contributor Pattern)

When routing.mode=auto, beads detects user role and routes new issues automatically:

Maintainer (SSH push access):

bash
# Git remote: [email protected]:user/repo.git
bd create "Fix bug" -p 1
# → Creates in current repo (source_repo = ".")

Contributor (HTTPS or no push access):

bash
# Git remote: https://github.com/fork/repo.git
bd create "Fix bug" -p 1
# → Creates in planning repo (source_repo = "~/.beads-planning")

Role detection priority:

  1. Explicit git config: git config beads.role maintainer|contributor
  2. Git remote URL inspection (SSH = maintainer, HTTPS = contributor)
  3. Fallback: contributor

Explicit Override

Always available regardless of routing mode:

bash
# Force creation in specific repo
bd create "Issue" -p 1 --repo /path/to/repo
bd create "Issue" -p 1 --repo ~/my-planning

Discovered Issue Inheritance

Issues with discovered-from dependencies automatically inherit parent's source_repo:

bash
# Parent in current repo
bd create "Implement auth" -p 1
# → Created as bd-abc (source_repo = ".")

# Discovered issue inherits parent's repo
bd create "Found bug" -p 1 --deps discovered-from:bd-abc
# → Created with source_repo = "." (same as parent)

Override if needed:

bash
bd create "Issue" -p 1 --deps discovered-from:bd-abc --repo /different/repo

Multi-Repo Hydration

Agents working in multi-repo mode see aggregated issues from multiple repositories:

bash
# View all issues (current + additional repos)
bd ready --json
bd list --json

# Filter by source repository
bd list --json | jq '.[] | select(.source_repo == ".")'
bd list --json | jq '.[] | select(.source_repo == "~/.beads-planning")'

How it works:

  1. Beads reads from all configured Dolt databases
  2. Aggregates into unified view
  3. Maintains source_repo field for provenance
  4. Routes issues back to correct databases

Common Patterns

OSS Contributor Workflow

Setup: Human runs bd init --contributor (wizard handles config)

Agent workflow:

bash
# All planning issues auto-route to separate repo
bd create "Investigate implementation" -p 1
bd create "Draft RFC" -p 2
# → Created in ~/.beads-planning (never appears in PRs)

# View all work (upstream + planning)
bd ready
bd list --json

# Complete work
bd close plan-42 --reason "Done"

# Git commit/push - no .beads/ pollution in PR ✅

Team Workflow

Setup: Human runs bd init --team (wizard handles config)

Agent workflow:

bash
# Shared team planning (committed to repo)
bd create "Implement feature X" -p 1
# → Created in current repo (visible to team)

# Optional: Personal experiments in separate repo
bd create "Try alternative" -p 2 --repo ~/.beads-planning-personal
# → Created in personal repo (private)

# View all
bd ready --json

Multi-Phase Development

Setup: Multiple repos for different phases

Agent workflow:

bash
# Phase 1: Planning repo
cd ~/projects/myapp-planning
bd create "Design auth" -p 1 -t epic

# Phase 2: Implementation repo (views planning + impl)
cd ~/projects/myapp-implementation
bd ready  # Shows both repos
bd create "Implement auth backend" -p 1
bd dep add impl-42 plan-10 --type blocks  # Link across repos

Troubleshooting

Issues appearing in wrong repository

Symptom: bd create routes to unexpected repo

Check:

bash
bd config get routing.mode
bd config get routing.maintainer
bd config get routing.contributor
bd info --json | jq '.role'

Fix:

bash
# Use explicit flag
bd create "Issue" -p 1 --repo .

# Or reconfigure routing
bd config set routing.mode explicit
bd config set routing.default "."

Can't see issues from other repos

Symptom: bd list only shows current repo

Check:

bash
bd config get repos.additional

Fix:

bash
# Add missing repos
bd config set repos.additional "~/repo1,~/repo2"

# Force sync
bd dolt push
bd list --json

Discovered issues in wrong repository

Symptom: Issues with discovered-from appear in wrong repo

Explanation: This is intentional - discovered issues inherit parent's source_repo

Override if needed:

bash
bd create "Issue" -p 1 --deps discovered-from:bd-42 --repo /different/repo

Planning repo polluting PRs

Symptom: ~/.beads-planning changes appear in upstream PRs

Verify:

bash
# Planning repo should be separate
ls -la ~/.beads-planning/.git  # Should exist

# Fork should NOT contain planning issues
cd ~/projects/fork
bd list --json | jq '.[] | select(.source_repo == "~/.beads-planning")'
# Should be empty

# Check routing
bd config get routing.contributor  # Should be ~/.beads-planning

Server routing to wrong database

Symptom: MCP operations affect wrong project

Cause: Using multiple MCP server instances (not recommended)

Fix:

json
// RECOMMENDED: Single MCP server
{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

The single MCP server automatically routes based on workspace directory.

Version mismatch after upgrade

Symptom: Commands fail right after a bd upgrade

Fix:

bash
bd version      # Confirm active CLI version
bd doctor quick # Validate local installation health

Best Practices for Agents

OSS Contributors

  • ✅ Planning issues auto-route to ~/.beads-planning
  • ✅ Never commit .beads/ in PRs to upstream
  • ✅ Use bd ready to see all work (upstream + planning)
  • ❌ Don't manually override routing without good reason

Teams

  • ✅ Use bd dolt push to sync the shared Dolt database
  • ✅ Use bd dolt push to ensure changes are committed/pushed
  • ✅ Link related issues across repos with dependencies
  • ❌ Don't delete .beads/ - you lose all issue data

Multi-Phase Projects

  • ✅ Use clear repo names (planning, impl, maint)
  • ✅ Link issues across phases with blocks dependencies
  • ✅ Use bd list --json to filter by source_repo
  • ❌ Don't duplicate issues across repos

General

  • ✅ Always use single MCP server (per-project Dolt servers)
  • ✅ Check routing config before filing issues
  • ✅ Use bd info --json to verify workspace state
  • ✅ Run bd dolt push at end of session
  • ❌ Don't assume routing behavior - check config

Backward Compatibility

Multi-repo mode is fully backward compatible:

Without multi-repo config:

bash
bd create "Issue" -p 1
# → Creates in local Dolt database (single-repo mode)

With multi-repo config:

bash
bd create "Issue" -p 1
# → Auto-routed based on config
# → Old issues in local database still work

Disabling multi-repo:

bash
bd config unset routing.mode
bd config unset repos.additional
# → Back to single-repo mode

Configuration Reference

Routing Config

bash
# Auto-detect role (maintainer vs contributor)
bd config set routing.mode auto
bd config set routing.maintainer "."              # Where maintainer issues go
bd config set routing.contributor "~/.beads-planning"  # Where contributor issues go

# Explicit mode (always use default)
bd config set routing.mode explicit
bd config set routing.default "."                 # All issues go here

# Check settings
bd config get routing.mode
bd config get routing.maintainer
bd config get routing.contributor
bd config get routing.default

Multi-Repo Hydration

bash
# Set primary repo (optional, default is current)
bd config set repos.primary "."

# Add additional repos to aggregate
bd config set repos.additional "~/repo1,~/repo2,~/repo3"

# Check settings
bd config get repos.primary
bd config get repos.additional

Verify Configuration

bash
# Show all config + database path + server status
bd info --json

# Sample output:
{
  "database_path": "/Users/you/projects/myapp/.beads/dolt",
  "config": {
    "routing": {
      "mode": "auto",
      "maintainer": ".",
      "contributor": "~/.beads-planning"
    },
    "repos": {
      "primary": ".",
      "additional": ["~/repo1", "~/repo2"]
    }
  },
  "server": {
    "running": true,
    "pid": 12345,
    "mode": "server"
  }
}