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>
2025-10-17 22:49:22 -07:00
parent 958bbc0853
commit 0795797bac
4 changed files with 220 additions and 2 deletions
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@@ -23,7 +23,7 @@
 {"id":"bd-119","title":"Issue in repo1","description":"This should go to repo1 database","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-17T16:35:02.535742-07:00","updated_at":"2025-10-17T18:13:19.394276-07:00","closed_at":"2025-10-17T18:13:19.394276-07:00"}
 {"id":"bd-12","title":"Implement reference scoring algorithm","description":"Count references for each colliding issue: text mentions in descriptions/notes/design fields + dependency references. Sort collisions by score ascending (fewest refs first). This minimizes total updates during renumbering.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-17T01:32:00.634423-07:00","closed_at":"2025-10-14T02:51:52.198288-07:00","dependencies":[{"issue_id":"bd-12","depends_on_id":"bd-48","type":"parent-child","created_at":"2025-10-16T21:51:08.913972-07:00","created_by":"renumber"}]}
 {"id":"bd-120","title":"Fix nil pointer crash in bd export command","description":"When running `bd export -o .beads/issues.jsonl`, the command crashes with a nil pointer dereference.\n\n## Error\n```\npanic: runtime error: invalid memory address or nil pointer dereference\n[signal SIGSEGV: segmentation violation code=0x2 addr=0x108 pc=0x1034456fc]\n\ngoroutine 1 [running]:\nmain.init.func14(0x103c24380, {0x1034a9695?, 0x4?, 0x1034a95c9?})\n        /Users/stevey/src/vc/adar/beads/cmd/bd/export.go:74 +0x15c\n```\n\n## Context\n- This happened after closing bd-105, bd-114, bd-115\n- Auto-export from daemon still works fine\n- Only the manual `bd export` command crashes\n- Data was already synced via auto-export, so no data loss\n\n## Location\nFile: `cmd/bd/export.go` line 74","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-17T17:34:05.014619-07:00","updated_at":"2025-10-17T17:35:41.414218-07:00","closed_at":"2025-10-17T17:35:41.414218-07:00"}
-{"id":"bd-121","title":"Add --global flag to daemon for multi-repo support","description":"Currently daemon creates socket at .beads/bd.sock in each repo. For multi-repo support, add --global flag to create socket in ~/.beads/bd.sock that can serve requests from any repository.\n\nImplementation:\n- Add --global flag to daemon command\n- When --global is set, use ~/.beads/bd.sock instead of ./.beads/bd.sock  \n- Don't require being in a git repo when --global is used\n- Update daemon discovery logic to check ~/.beads/bd.sock as fallback\n- Document that global daemon can serve multiple repos simultaneously\n\nBenefits:\n- Single daemon serves all repos on the system\n- No need to start daemon per-repo\n- Better resource usage\n- Enables system-wide task tracking\n\nContext: Per-request context routing (bd-115) already implemented - daemon can handle multiple repos. This issue is about making the UX better.\n\nRelated: bd-73 (parent issue for multi-repo support)","status":"open","priority":1,"issue_type":"feature","created_at":"2025-10-17T20:43:47.080685-07:00","updated_at":"2025-10-17T20:43:47.080685-07:00","dependencies":[{"issue_id":"bd-121","depends_on_id":"bd-73","type":"parent-child","created_at":"2025-10-17T20:44:02.2335-07:00","created_by":"daemon"}]}
+{"id":"bd-121","title":"Add --global flag to daemon for multi-repo support","description":"Currently daemon creates socket at .beads/bd.sock in each repo. For multi-repo support, add --global flag to create socket in ~/.beads/bd.sock that can serve requests from any repository.\n\nImplementation:\n- Add --global flag to daemon command\n- When --global is set, use ~/.beads/bd.sock instead of ./.beads/bd.sock  \n- Don't require being in a git repo when --global is used\n- Update daemon discovery logic to check ~/.beads/bd.sock as fallback\n- Document that global daemon can serve multiple repos simultaneously\n\nBenefits:\n- Single daemon serves all repos on the system\n- No need to start daemon per-repo\n- Better resource usage\n- Enables system-wide task tracking\n\nContext: Per-request context routing (bd-115) already implemented - daemon can handle multiple repos. This issue is about making the UX better.\n\nRelated: bd-73 (parent issue for multi-repo support)","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-10-17T20:43:47.080685-07:00","updated_at":"2025-10-17T22:45:42.411986-07:00","closed_at":"2025-10-17T22:45:42.411986-07:00","dependencies":[{"issue_id":"bd-121","depends_on_id":"bd-73","type":"parent-child","created_at":"2025-10-17T20:44:02.2335-07:00","created_by":"daemon"}]}
 {"id":"bd-122","title":"Document multi-repo workflow with daemon","description":"The daemon already supports multi-repo via per-request context routing (bd-115), but this isn't documented. Users need to know how to use beads across multiple projects.\n\nAdd documentation for:\n1. How daemon serves multiple repos simultaneously\n2. Starting daemon in one repo, using from others\n3. MCP server multi-repo configuration\n4. Example: tracking work across a dozen projects\n5. Comparison to workspace/global instance approaches\n\nDocumentation locations:\n- README.md (Multi-repo section)\n- AGENTS.md (MCP multi-repo config)\n- integrations/beads-mcp/README.md (working_dir parameter)\n\nInclude:\n- Architecture diagram showing one daemon, many repos\n- Example MCP config with BEADS_WORKING_DIR\n- CLI workflow example\n- Reference to test_multi_repo.py as proof of concept\n\nContext: Feature already works (proven by test_multi_repo.py), just needs user-facing docs.","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-17T20:43:48.91315-07:00","updated_at":"2025-10-17T20:43:48.91315-07:00","dependencies":[{"issue_id":"bd-122","depends_on_id":"bd-73","type":"parent-child","created_at":"2025-10-17T20:44:03.261924-07:00","created_by":"daemon"}]}
 {"id":"bd-123","title":"Add 'bd repos' command for multi-repo aggregation","description":"When using daemon in multi-repo mode, users need commands to view/manage work across all active repositories.\n\nAdd 'bd repos' subcommand with:\n\n1. bd repos list\n   - Show all repositories daemon has cached\n   - Display: path, prefix, issue count, last activity\n   - Example output:\n     ~/src/project1  [p1-]   45 issues  (active)\n     ~/src/project2  [p2-]   12 issues  (2m ago)\n\n2. bd repos ready --all  \n   - Aggregate ready work across all repos\n   - Group by repo or show combined list\n   - Support priority/assignee filters\n\n3. bd repos stats\n   - Combined statistics across all repos\n   - Total issues, breakdown by status/priority\n   - Per-repo breakdown\n\n4. bd repos clear-cache\n   - Close all cached storage connections\n   - Useful for freeing resources\n\nImplementation notes:\n- Requires daemon to track active storage instances\n- May need RPC protocol additions for multi-repo queries\n- Should gracefully handle repos that no longer exist\n\nDepends on: Global daemon flag (makes this more useful)\n\nContext: This provides the UX layer on top of existing multi-repo support. The daemon can already serve multiple repos - this makes it easy to work with them.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-10-17T20:43:49.816998-07:00","updated_at":"2025-10-17T20:43:49.816998-07:00","dependencies":[{"issue_id":"bd-123","depends_on_id":"bd-73","type":"parent-child","created_at":"2025-10-17T20:44:04.407138-07:00","created_by":"daemon"},{"issue_id":"bd-123","depends_on_id":"bd-121","type":"blocks","created_at":"2025-10-17T20:44:13.681626-07:00","created_by":"daemon"}]}
 {"id":"bd-124","title":"Add daemon auto-start on first use","description":"Currently users must manually start daemon with 'bd daemon'. For better UX, auto-start daemon when first bd command is run.\n\nImplementation:\n\n1. In PersistentPreRun, check if daemon is running\n2. If not, check if auto-start is enabled (default: true)\n3. Start daemon with appropriate flags (--global if configured)\n4. Wait for socket to be ready (with timeout)\n5. Retry connection to newly-started daemon\n6. Silently fail back to direct mode if daemon won't start\n\nConfiguration:\n- BEADS_AUTO_START_DAEMON env var (default: true)\n- --no-auto-daemon flag to disable\n- Config file option: auto_start_daemon = true\n\nSafety considerations:\n- Don't auto-start if daemon failed recently (exponential backoff)\n- Log auto-start to daemon.log\n- Clear error messages if auto-start fails\n- Never auto-start if --no-daemon flag is set\n\nBenefits:\n- Zero-configuration experience\n- Daemon benefits (speed, multi-repo) automatic\n- Still supports direct mode as fallback\n\nDepends on: Global daemon flag would make this more useful","status":"open","priority":2,"issue_type":"feature","created_at":"2025-10-17T20:43:50.961453-07:00","updated_at":"2025-10-17T20:43:50.961453-07:00","dependencies":[{"issue_id":"bd-124","depends_on_id":"bd-73","type":"parent-child","created_at":"2025-10-17T20:44:05.502634-07:00","created_by":"daemon"},{"issue_id":"bd-124","depends_on_id":"bd-121","type":"blocks","created_at":"2025-10-17T20:44:14.987308-07:00","created_by":"daemon"}]}
--- a/AGENTS.md
+++ b/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:
--- a/README.md
+++ b/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:
--- a/integrations/beads-mcp/README.md
+++ b/integrations/beads-mcp/README.md
@@ -59,11 +59,73 @@ Then use in Claude Desktop config:
 - `BEADS_USE_DAEMON` - Use daemon RPC instead of CLI (default: `1`, set to `0` to disable)
 - `BEADS_PATH` - Path to bd executable (default: `~/.local/bin/bd`)
 - `BEADS_DB` - Path to beads database file (default: auto-discover from cwd)
- `BEADS_WORKING_DIR` - Working directory for bd commands (default: `$PWD` or current directory)
+- `BEADS_WORKING_DIR` - Working directory for bd commands (default: `$PWD` or current directory). Used for multi-repo setups - see below
 - `BEADS_ACTOR` - Actor name for audit trail (default: `$USER`)
 - `BEADS_NO_AUTO_FLUSH` - Disable automatic JSONL sync (default: `false`)
 - `BEADS_NO_AUTO_IMPORT` - Disable automatic JSONL import (default: `false`)

+## Multi-Repository Setup
+
+**New in v0.9.11:** Work across multiple beads projects seamlessly!
+
+### Option 1: Global Daemon (Recommended)
+
+Start a single daemon to serve all your projects:
+
+```bash
+# Start global daemon (serves all repos)
+bd daemon --global
+```
+
+The MCP server automatically detects the global daemon and routes requests based on your working directory. No configuration changes needed!
+
+**How it works:**
+1. MCP server checks for local daemon socket (`.beads/bd.sock`)
+2. Falls back to global daemon socket (`~/.beads/bd.sock`)
+3. Routes requests to correct database based on working directory
+4. Each project keeps its own database at `.beads/*.db`
+
+**Simple config - works for all projects:**
+```json
+{
+  "mcpServers": {
+    "beads": {
+      "command": "beads-mcp"
+    }
+  }
+}
+```
+
+### Option 2: Per-Project MCP Instances
+
+Configure separate MCP servers for specific projects using `BEADS_WORKING_DIR`:
+
+```json
+{
+  "mcpServers": {
+    "beads-webapp": {
+      "command": "beads-mcp",
+      "env": {
+        "BEADS_WORKING_DIR": "/Users/yourname/projects/webapp"
+      }
+    },
+    "beads-api": {
+      "command": "beads-mcp",
+      "env": {
+        "BEADS_WORKING_DIR": "/Users/yourname/projects/api"
+      }
+    }
+  }
+}
+```
+
+Each instance will discover and use the database in its `BEADS_WORKING_DIR` path.
+
+**Which should you use?**
+- ✅ **Global daemon**: 3+ projects, better resource usage, automatic routing
+- ✅ **Per-project instances**: 1-2 main projects, explicit control
+- ✅ **Hybrid**: Run global daemon for convenience + per-project for main projects
+
 ## Features

 **Resource:**