diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 3b0388d8..de074972 100644 --- 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"}]} diff --git a/AGENTS.md b/AGENTS.md index f21651fc..9ecaa3f8 100644 --- 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: diff --git a/README.md b/README.md index 877494a2..10f34062 100644 --- 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
~/.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
beads-mcp] + CLI[CLI Commands
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: diff --git a/integrations/beads-mcp/README.md b/integrations/beads-mcp/README.md index cdbbde49..389e9ffb 100644 --- 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:**