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:
Steve Yegge
2025-10-17 22:49:22 -07:00
parent 958bbc0853
commit 0795797bac
4 changed files with 220 additions and 2 deletions

102
README.md
View File

@@ -916,6 +916,7 @@ bd daemon --auto-push # Auto-push commits (requires auto-commit)
bd daemon --log /var/log/bd.log # Custom log file path
bd daemon --status # Show daemon status
bd daemon --stop # Stop running daemon
bd daemon --global # Run as global daemon (see below)
```
The daemon is ideal for:
@@ -926,6 +927,104 @@ The daemon is ideal for:
The daemon gracefully shuts down on SIGTERM and maintains a PID file at `.beads/daemon.pid` for process management.
#### Global Daemon for Multiple Projects
**New in v0.9.11:** Run a single daemon to serve all your projects system-wide:
```bash
# Start global daemon (serves all repos)
bd daemon --global
# Check global daemon status
bd daemon --status --global
# Stop global daemon
bd daemon --stop --global
```
**Local vs Global Daemon:**
| Mode | Socket Location | Use Case |
|------|----------------|----------|
| **Local** (default) | `.beads/bd.sock` | Single project, per-repo daemon |
| **Global** (`--global`) | `~/.beads/bd.sock` | Multiple projects, system-wide daemon |
**When to use global daemon:**
- ✅ Working on multiple beads-enabled projects
- ✅ Want one daemon process for all repos
- ✅ Better resource usage (one daemon vs many)
- ✅ Automatic fallback for CLI commands
**How it works:**
1. Global daemon creates socket at `~/.beads/bd.sock`
2. CLI commands check local socket first, then fall back to global
3. Daemon serves requests from any repository
4. Each repo still has its own database at `.beads/*.db`
**Architecture:**
```mermaid
graph TB
subgraph "Global Daemon Setup"
GD[bd daemon --global<br/>~/.beads/bd.sock]
subgraph "Project 1: webapp"
P1DB[.beads/webapp.db]
P1JSON[.beads/issues.jsonl]
end
subgraph "Project 2: api"
P2DB[.beads/api.db]
P2JSON[.beads/issues.jsonl]
end
subgraph "Project 3: docs"
P3DB[.beads/docs.db]
P3JSON[.beads/issues.jsonl]
end
MCP[MCP Server<br/>beads-mcp]
CLI[CLI Commands<br/>bd ready, bd create, etc.]
MCP -->|Unix Socket| GD
CLI -->|Unix Socket| GD
GD -->|cwd: ~/projects/webapp| P1DB
GD -->|cwd: ~/projects/api| P2DB
GD -->|cwd: ~/projects/docs| P3DB
P1DB -.->|export| P1JSON
P2DB -.->|export| P2JSON
P3DB -.->|export| P3JSON
end
style GD fill:#1a1a2e,stroke:#16c5c5,stroke-width:3px,color:#fff
style MCP fill:#0f3460,stroke:#16c5c5,stroke-width:2px,color:#fff
style CLI fill:#0f3460,stroke:#16c5c5,stroke-width:2px,color:#fff
style P1DB fill:#16213e,stroke:#16c5c5,color:#fff
style P2DB fill:#16213e,stroke:#16c5c5,color:#fff
style P3DB fill:#16213e,stroke:#16c5c5,color:#fff
style P1JSON fill:#16213e,stroke:#e94560,color:#fff
style P2JSON fill:#16213e,stroke:#e94560,color:#fff
style P3JSON fill:#16213e,stroke:#e94560,color:#fff
```
**Example: Multi-repo workflow**
```bash
# Start global daemon once
bd daemon --global --auto-commit --auto-push
# Work on different projects - daemon handles all of them
cd ~/projects/webapp && bd create "Fix navigation bug" -p 1
cd ~/projects/api && bd create "Add rate limiting" -p 1
cd ~/projects/docs && bd create "Update API guide" -p 2
# All commands use the same global daemon automatically
cd ~/projects/webapp && bd ready # Uses global daemon
cd ~/projects/api && bd ready # Uses global daemon
```
**Note:** Global daemon doesn't require git repos, making it suitable for non-git projects or multi-repo setups.
### Optional: Git Hooks for Immediate Sync
Create `.git/hooks/pre-commit`:
@@ -1039,6 +1138,7 @@ Each project gets its own `.beads/` directory with its own database and JSONL fi
- Multiple agents working on different projects simultaneously → No conflicts
- Same machine, different repos → Each finds its own `.beads/*.db` automatically
- Agents in subdirectories → bd walks up to find the project root (like git)
- **Global daemon** → One daemon process serves all projects (v0.9.11+)
**Limitation:** Issues cannot reference issues in other projects. Each database is isolated by design. If you need cross-project tracking, initialize bd in a parent directory that contains both projects.
@@ -1053,6 +1153,8 @@ cd ~/work/api && bd ready --json # Uses ~/work/api/.beads/api.db
# No conflicts! Completely isolated databases.
```
**Recommended for multi-project setups:** Use the global daemon (`bd daemon --global`) to serve all projects with a single daemon process. See [Global Daemon for Multiple Projects](#global-daemon-for-multiple-projects) above.
### How do I migrate from GitHub Issues / Jira / Linear?
We don't have automated migration tools yet, but you can: