docs: Document multi-repo workflow with global daemon
Implements bd-122: Document how to use beads across multiple projects Added comprehensive multi-repo documentation: - README.md: Global daemon section with architecture diagram - AGENTS.md: MCP multi-repo configuration (global daemon + per-project) - integrations/beads-mcp/README.md: BEADS_WORKING_DIR usage - Mermaid diagram showing one daemon serving multiple repos Documentation covers: - Global daemon (bd daemon --global) for system-wide usage - Per-project MCP instances with BEADS_WORKING_DIR - Comparison table (local vs global) - When to use each approach - Example workflows for multi-project setups Benefits of global daemon: - One daemon process for all repos - Automatic socket discovery (local -> global fallback) - Better resource usage - Per-request context routing to correct database Amp-Thread-ID: https://ampcode.com/threads/T-ea606216-b886-4af0-bba8-56d000362d01 Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
54
AGENTS.md
54
AGENTS.md
@@ -40,6 +40,60 @@ pip install beads-mcp
|
||||
|
||||
See `integrations/beads-mcp/README.md` for complete documentation.
|
||||
|
||||
### Multi-Repo Configuration (MCP Server)
|
||||
|
||||
**Working on multiple projects?** You can configure beads MCP to work across multiple repositories.
|
||||
|
||||
**Option 1: Global Daemon (Recommended - v0.9.11+)**
|
||||
Start a single daemon to serve all your projects:
|
||||
```bash
|
||||
# Start global daemon
|
||||
bd daemon --global
|
||||
|
||||
# MCP server automatically discovers and uses the global daemon
|
||||
```
|
||||
|
||||
Your MCP config stays simple:
|
||||
```json
|
||||
{
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The MCP server will:
|
||||
1. Check for local daemon socket (`.beads/bd.sock`)
|
||||
2. Fall back to global daemon socket (`~/.beads/bd.sock`)
|
||||
3. Automatically route requests to the correct database based on your current working directory
|
||||
|
||||
**Option 2: Multiple MCP Server Instances**
|
||||
Configure separate MCP servers for each major project:
|
||||
```json
|
||||
{
|
||||
"beads-webapp": {
|
||||
"command": "beads-mcp",
|
||||
"env": {
|
||||
"BEADS_WORKING_DIR": "/Users/you/projects/webapp"
|
||||
}
|
||||
},
|
||||
"beads-api": {
|
||||
"command": "beads-mcp",
|
||||
"env": {
|
||||
"BEADS_WORKING_DIR": "/Users/you/projects/api"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Each MCP instance will use its specified working directory to find the correct `.beads/*.db` database.
|
||||
|
||||
**Which approach should you use?**
|
||||
- ✅ **Global daemon**: Best for 3+ projects, better resource usage, automatic routing
|
||||
- ✅ **Multiple instances**: Best for 1-2 projects you switch between frequently
|
||||
- ✅ **Hybrid**: Run global daemon + use MCP instances for convenience
|
||||
|
||||
### CLI Quick Reference
|
||||
|
||||
If you're not using the MCP server, here are the CLI commands:
|
||||
|
||||
Reference in New Issue
Block a user