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:
102
README.md
102
README.md
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user