refactor: Remove legacy MCP Agent Mail integration (bd-6gd)
Remove the external MCP Agent Mail server integration that required running a separate HTTP server and configuring environment variables. The native `bd mail` system (stored as git-synced issues) remains unchanged and is the recommended approach for inter-agent messaging. Files removed: - cmd/bd/message.go - Legacy `bd message` command - integrations/beads-mcp/src/beads_mcp/mail.py, mail_tools.py - lib/beads_mail_adapter.py - Python adapter library - examples/go-agent/ - Agent Mail-focused example - examples/python-agent/agent_with_mail.py, AGENT_MAIL_EXAMPLE.md - docs/AGENT_MAIL*.md, docs/adr/002-agent-mail-integration.md - tests/integration/test_agent_race.py, test_mail_failures.py, etc. - tests/benchmarks/ - Agent Mail benchmarks Updated documentation to remove Agent Mail references while keeping native `bd mail` documentation intact. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
@@ -1,525 +0,0 @@
|
||||
# Agent Mail Integration Guide
|
||||
|
||||
**Status:** Optional Enhancement
|
||||
**Minimum bd Version:** 0.21.0
|
||||
**Related ADR:** [002-agent-mail-integration.md](adr/002-agent-mail-integration.md)
|
||||
|
||||
## Overview
|
||||
|
||||
MCP Agent Mail provides real-time coordination for multi-agent beads workflows, reducing latency from 2-5 seconds (git sync) to <100ms (HTTP API) and preventing work collisions through file reservations.
|
||||
|
||||
**Key Benefits:**
|
||||
- **20-50x latency reduction**: <100ms vs 2000-5000ms for status updates
|
||||
- **Collision prevention**: Exclusive file reservations prevent duplicate work
|
||||
- **Lightweight**: <50MB memory, simple HTTP API
|
||||
- **100% optional**: Git-only mode works identically without it
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- Python 3.11+
|
||||
- bd 0.21.0+
|
||||
- Multi-agent workflow (2+ AI agents working on same repository)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Install Agent Mail server
|
||||
git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git
|
||||
cd mcp_agent_mail
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
pip install -e .
|
||||
|
||||
# Start server
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
# Server runs on http://127.0.0.1:8765
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Enable Agent Mail by setting environment variables before running bd commands:
|
||||
|
||||
```bash
|
||||
# Agent 1
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=assistant-alpha
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
|
||||
# Agent 2
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=assistant-beta
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
|
||||
# Now run bd commands normally
|
||||
bd ready
|
||||
bd update bd-42 --status in_progress
|
||||
```
|
||||
|
||||
**All configuration is via environment variables** - no changes to `.beads/` or git required.
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Check if Agent Mail is active
|
||||
bd info --json | grep agent_mail
|
||||
|
||||
# View reservations in web UI
|
||||
open http://127.0.0.1:8765/mail
|
||||
|
||||
# Test collision prevention
|
||||
# Terminal 1 (Agent A):
|
||||
bd update bd-123 --status in_progress
|
||||
|
||||
# Terminal 2 (Agent B):
|
||||
bd update bd-123 --status in_progress
|
||||
# Expected: Error - bd-123 reserved by assistant-alpha
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ bd (Beads CLI) │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────────┐ │
|
||||
│ │ Git Sync │ │ Agent Mail │ │
|
||||
│ │ (required) │ │ (optional) │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ - Export │ │ - Reservations │ │
|
||||
│ │ - Import │ │ - Notifications │ │
|
||||
│ │ - Commit │ │ - Status updates│ │
|
||||
│ │ - Push/Pull │ │ │ │
|
||||
│ └─────────────┘ └─────────────────┘ │
|
||||
│ │ │ │
|
||||
└─────────┼──────────────────────┼────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ .beads/ │ │ Agent Mail │
|
||||
│ issues.jsonl │ │ Server │
|
||||
│ (git) │ │ (HTTP) │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**Git remains the source of truth.** Agent Mail provides ephemeral coordination state only.
|
||||
|
||||
### Coordination Flow
|
||||
|
||||
**Without Agent Mail (git-only):**
|
||||
```
|
||||
Agent A: bd update bd-123 --status in_progress
|
||||
↓ (30s debounce)
|
||||
↓ export to JSONL
|
||||
↓ git commit + push (1-2s)
|
||||
↓
|
||||
Agent B: git pull (1-2s)
|
||||
↓ import from JSONL
|
||||
↓ sees bd-123 is taken (TOO LATE - work already started!)
|
||||
|
||||
Total latency: 2000-5000ms
|
||||
Risk: Both agents work on same issue
|
||||
```
|
||||
|
||||
**With Agent Mail:**
|
||||
```
|
||||
Agent A: bd update bd-123 --status in_progress
|
||||
↓
|
||||
├─ Agent Mail: POST /api/reservations (5ms)
|
||||
│ └─ Reserve bd-123 for Agent A
|
||||
├─ Local: Update .beads/beads.db
|
||||
└─ Background: Export to JSONL (30s debounce)
|
||||
|
||||
Agent B: bd update bd-123 --status in_progress
|
||||
↓
|
||||
└─ Agent Mail: POST /api/reservations (5ms)
|
||||
└─ HTTP 409 Conflict: "bd-123 reserved by Agent A"
|
||||
└─ bd exits with clear error
|
||||
|
||||
Total latency: <100ms
|
||||
Risk: Zero - collision prevented at reservation layer
|
||||
```
|
||||
|
||||
### Integration Points
|
||||
|
||||
Agent Mail integrates at 4 key points in the bd workflow:
|
||||
|
||||
1. **Issue Reservation** (`bd update --status in_progress`)
|
||||
- Check if issue already reserved
|
||||
- Create reservation if available
|
||||
- Error 409 if conflict
|
||||
|
||||
2. **Issue Release** (`bd close`)
|
||||
- Release reservation automatically
|
||||
- Notify other agents (optional)
|
||||
|
||||
3. **Ready Work Query** (`bd ready`)
|
||||
- Filter out reserved issues (future enhancement)
|
||||
- Show only truly available work
|
||||
|
||||
4. **Status Updates** (`bd update --priority`, etc.)
|
||||
- No reservation required for non-status changes
|
||||
- Graceful degradation if server unavailable
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `BEADS_AGENT_MAIL_URL` | Yes | None | Agent Mail server URL (e.g., `http://127.0.0.1:8765`) |
|
||||
| `BEADS_AGENT_NAME` | Yes | None | Unique agent identifier (e.g., `assistant-alpha`) |
|
||||
| `BEADS_PROJECT_ID` | Yes | None | Project namespace (e.g., `my-project`) |
|
||||
| `BEADS_AGENT_MAIL_TOKEN` | No | None | Bearer token for authentication (future) |
|
||||
|
||||
### Example Configurations
|
||||
|
||||
**Local Development (Single Machine):**
|
||||
```bash
|
||||
# ~/.bashrc or ~/.zshrc
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=$(whoami)-$(hostname)
|
||||
export BEADS_PROJECT_ID=$(basename $(pwd))
|
||||
```
|
||||
|
||||
**Multi-Machine Setup:**
|
||||
```bash
|
||||
# Machine 1 (runs server)
|
||||
export BEADS_AGENT_MAIL_URL=http://192.168.1.100:8765
|
||||
export BEADS_AGENT_NAME=dev-machine-1
|
||||
export BEADS_PROJECT_ID=beads
|
||||
|
||||
# Machine 2 (client only)
|
||||
export BEADS_AGENT_MAIL_URL=http://192.168.1.100:8765
|
||||
export BEADS_AGENT_NAME=dev-machine-2
|
||||
export BEADS_PROJECT_ID=beads
|
||||
```
|
||||
|
||||
**Docker Compose:**
|
||||
```yaml
|
||||
services:
|
||||
agent-mail:
|
||||
image: ghcr.io/dicklesworthstone/mcp_agent_mail:latest
|
||||
ports:
|
||||
- "8765:8765"
|
||||
|
||||
agent-1:
|
||||
image: my-beads-agent
|
||||
environment:
|
||||
BEADS_AGENT_MAIL_URL: http://agent-mail:8765
|
||||
BEADS_AGENT_NAME: worker-1
|
||||
BEADS_PROJECT_ID: my-project
|
||||
```
|
||||
|
||||
## When to Use Agent Mail
|
||||
|
||||
### ✅ Use Agent Mail When:
|
||||
|
||||
1. **Multiple AI agents** working on the same repository simultaneously
|
||||
2. **Frequent status updates** (multiple agents claiming/releasing work)
|
||||
3. **Collision-sensitive workflows** (duplicate work is expensive)
|
||||
4. **Real-time coordination needed** (latency matters)
|
||||
5. **CI/CD integration** (agents triggered by webhooks/events)
|
||||
|
||||
**Example Scenario:**
|
||||
- Team has 3 AI agents (Claude, GPT-4, Gemini)
|
||||
- Agents pull from work queue every 5 minutes
|
||||
- Repository has 50+ open issues
|
||||
- Duplicate work costs 30+ minutes to resolve
|
||||
|
||||
### ❌ Skip Agent Mail When:
|
||||
|
||||
1. **Single agent** workflows (no collision risk)
|
||||
2. **Infrequent updates** (once per day/week)
|
||||
3. **Git-only infrastructure** (no external services allowed)
|
||||
4. **Offline workflows** (no network connectivity)
|
||||
5. **Low issue volume** (<10 open issues)
|
||||
|
||||
**Example Scenario:**
|
||||
- Solo developer using beads for personal task tracking
|
||||
- Updates happen once per session
|
||||
- No concurrent work
|
||||
- Simplicity over latency
|
||||
|
||||
## Graceful Degradation
|
||||
|
||||
**Agent Mail failure NEVER breaks beads.** If the server is unavailable:
|
||||
|
||||
1. bd logs a warning: `Agent Mail unavailable, falling back to git-only mode`
|
||||
2. All operations proceed normally
|
||||
3. Git sync handles coordination (with higher latency)
|
||||
4. No errors, no crashes
|
||||
|
||||
**Test graceful degradation:**
|
||||
```bash
|
||||
# Stop Agent Mail server
|
||||
pkill -f "mcp_agent_mail.cli"
|
||||
|
||||
# bd commands work identically
|
||||
bd ready # Success
|
||||
bd update bd-42 --status in_progress # Success (git-only mode)
|
||||
```
|
||||
|
||||
**Automatic fallback conditions:**
|
||||
- Server not responding (connection refused)
|
||||
- Server returns 500+ errors
|
||||
- Network timeout (>5s)
|
||||
- Invalid/missing environment variables
|
||||
|
||||
## Multi-Machine Deployment
|
||||
|
||||
### Centralized Server Pattern (Recommended)
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Agent A │────▶│ Agent Mail │◀────│ Agent B │
|
||||
│ (Machine 1) │ │ Server │ │ (Machine 2) │
|
||||
└─────────────┘ │ (Machine 3) │ └─────────────┘
|
||||
└─────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ PostgreSQL │ (optional)
|
||||
│ Storage │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
**Steps:**
|
||||
1. Deploy Agent Mail on dedicated server/container
|
||||
2. Configure firewall to allow port 8765 from agent machines
|
||||
3. Set `BEADS_AGENT_MAIL_URL` to server IP on all agents
|
||||
4. (Optional) Configure PostgreSQL backend for persistence
|
||||
|
||||
### Peer-to-Peer Pattern (Advanced)
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ Agent A │────▶│ Agent B │
|
||||
│ + Server │ │ + Server │
|
||||
└─────────────┘ └─────────────┘
|
||||
│ │
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Shared DB │ (e.g., Redis)
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
**Use case:** High-availability setups where server can't be single point of failure.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: "Agent Mail unavailable" warnings
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
WARN Agent Mail unavailable, falling back to git-only mode
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. Check server is running: `curl http://127.0.0.1:8765/health`
|
||||
2. Verify `BEADS_AGENT_MAIL_URL` is set correctly
|
||||
3. Check firewall allows connections to port 8765
|
||||
4. Review server logs: `tail -f ~/.mcp_agent_mail/logs/server.log`
|
||||
|
||||
### Issue: "Reservation conflict" errors
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
Error: bd-123 already reserved by assistant-alpha
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Expected behavior** - another agent claimed the issue first
|
||||
2. Find different work: `bd ready`
|
||||
3. If reservation is stale (agent crashed), release manually:
|
||||
```bash
|
||||
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-123
|
||||
```
|
||||
4. Configure reservation TTL to auto-expire stale locks (future)
|
||||
|
||||
### Issue: Reservations persist after agent crashes
|
||||
|
||||
**Symptoms:**
|
||||
- Agent crashes mid-work
|
||||
- Reservation not released
|
||||
- Other agents can't claim the issue
|
||||
|
||||
**Solutions:**
|
||||
1. **Manual release** via web UI: http://127.0.0.1:8765/mail
|
||||
2. **API release**: `curl -X DELETE http://127.0.0.1:8765/api/reservations/<issue-id>`
|
||||
3. **Restart server** (clears all ephemeral state): `pkill -f mcp_agent_mail; python -m mcp_agent_mail.cli serve-http`
|
||||
4. **Future:** Configure TTL to auto-expire (not yet implemented)
|
||||
|
||||
### Issue: Two agents have different project IDs
|
||||
|
||||
**Symptoms:**
|
||||
- Agents don't see each other's reservations
|
||||
- Collisions still happen
|
||||
|
||||
**Solutions:**
|
||||
1. Ensure all agents use **same** `BEADS_PROJECT_ID`
|
||||
2. Check environment: `echo $BEADS_PROJECT_ID`
|
||||
3. Set globally in shell profile:
|
||||
```bash
|
||||
# ~/.bashrc
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
```
|
||||
|
||||
### Issue: Server uses too much memory
|
||||
|
||||
**Symptoms:**
|
||||
- Agent Mail process grows to 100+ MB
|
||||
- Server becomes slow
|
||||
|
||||
**Solutions:**
|
||||
1. **Normal for in-memory mode** (<50MB baseline + reservation data)
|
||||
2. Use PostgreSQL backend for large-scale deployments
|
||||
3. Configure reservation expiry to prevent unbounded growth
|
||||
4. Restart server periodically (ephemeral state is OK to lose)
|
||||
|
||||
## Migration from Git-Only Mode
|
||||
|
||||
**Good news:** Zero migration required! Agent Mail is purely additive.
|
||||
|
||||
### Step 1: Test with Single Agent
|
||||
```bash
|
||||
# Start server
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
|
||||
# Configure one agent
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=test-agent
|
||||
export BEADS_PROJECT_ID=test
|
||||
|
||||
# Run normal workflow
|
||||
bd ready
|
||||
bd update bd-42 --status in_progress
|
||||
bd close bd-42 "Done"
|
||||
|
||||
# Verify in web UI
|
||||
open http://127.0.0.1:8765/mail
|
||||
```
|
||||
|
||||
### Step 2: Add Second Agent
|
||||
```bash
|
||||
# In separate terminal/machine
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=test-agent-2
|
||||
export BEADS_PROJECT_ID=test
|
||||
|
||||
# Try claiming same issue (should fail)
|
||||
bd update bd-42 --status in_progress
|
||||
# Expected: Error - reservation conflict
|
||||
```
|
||||
|
||||
### Step 3: Roll Out to Production
|
||||
1. Deploy Agent Mail server to production environment
|
||||
2. Add environment variables to agent deployment configs
|
||||
3. Monitor logs for "Agent Mail unavailable" warnings
|
||||
4. Gradually enable for all agents
|
||||
|
||||
### Rollback Plan
|
||||
Simply **unset environment variables** - agents immediately fall back to git-only mode:
|
||||
```bash
|
||||
unset BEADS_AGENT_MAIL_URL
|
||||
unset BEADS_AGENT_NAME
|
||||
unset BEADS_PROJECT_ID
|
||||
|
||||
# bd works identically without Agent Mail
|
||||
bd ready
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: Do I need Agent Mail for single-agent workflows?
|
||||
**A:** No. Agent Mail is only useful for multi-agent coordination. Single agents get no benefit from it.
|
||||
|
||||
### Q: Can I use Agent Mail with the MCP server (beads-mcp)?
|
||||
**A:** Yes! Set the environment variables before starting beads-mcp, and it will use Agent Mail for all operations.
|
||||
|
||||
### Q: What happens if Agent Mail and git get out of sync?
|
||||
**A:** Git is the source of truth. If Agent Mail has stale reservation data, worst case is a 409 error. Agent can manually release and retry.
|
||||
|
||||
### Q: Does Agent Mail require changes to .beads/ or git?
|
||||
**A:** No. Agent Mail is 100% external. No changes to database schema, JSONL format, or git workflow.
|
||||
|
||||
### Q: Can I use Agent Mail for multiple projects on the same server?
|
||||
**A:** Yes. Set different `BEADS_PROJECT_ID` for each project. Agent Mail provides namespace isolation.
|
||||
|
||||
### Q: Is Agent Mail required for beads 1.0?
|
||||
**A:** No. Agent Mail is an optional enhancement. Git-only mode is fully supported indefinitely.
|
||||
|
||||
### Q: How does Agent Mail handle authentication?
|
||||
**A:** Currently, no authentication (local network only). Bearer token support planned for future release.
|
||||
|
||||
### Q: Can I self-host Agent Mail on corporate infrastructure?
|
||||
**A:** Yes. Agent Mail is open source (MIT license) and can be deployed anywhere Python runs.
|
||||
|
||||
### Q: What's the performance impact of Agent Mail?
|
||||
**A:** ~5ms overhead per reservation API call. Negligible compared to 2000-5000ms git sync.
|
||||
|
||||
### Q: Does Agent Mail work with protected branches?
|
||||
**A:** Yes. Agent Mail operates independently of git workflow. Use with `bd config set sync.branch beads-metadata` as normal.
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Custom Reservation TTL
|
||||
```bash
|
||||
# Future feature (not yet implemented)
|
||||
export BEADS_RESERVATION_TTL=3600 # 1 hour in seconds
|
||||
```
|
||||
|
||||
### PostgreSQL Backend
|
||||
```bash
|
||||
# For production deployments with persistence
|
||||
export AGENT_MAIL_DB_URL=postgresql://user:pass@localhost/agentmail
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
```
|
||||
|
||||
### Monitoring & Observability
|
||||
```bash
|
||||
# Server exposes Prometheus metrics (future)
|
||||
curl http://127.0.0.1:8765/metrics
|
||||
|
||||
# Health check
|
||||
curl http://127.0.0.1:8765/health
|
||||
```
|
||||
|
||||
### Integration with CI/CD
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
jobs:
|
||||
agent-workflow:
|
||||
runs-on: ubuntu-latest
|
||||
services:
|
||||
agent-mail:
|
||||
image: ghcr.io/dicklesworthstone/mcp_agent_mail:latest
|
||||
ports:
|
||||
- 8765:8765
|
||||
env:
|
||||
BEADS_AGENT_MAIL_URL: http://localhost:8765
|
||||
BEADS_AGENT_NAME: github-actions-${{ github.run_id }}
|
||||
BEADS_PROJECT_ID: ${{ github.repository }}
|
||||
steps:
|
||||
- run: bd ready | head -1 | xargs -I {} bd update {} --status in_progress
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [ADR 002: Agent Mail Integration](adr/002-agent-mail-integration.md)
|
||||
- [Agent Mail Repository](https://github.com/Dicklesworthstone/mcp_agent_mail)
|
||||
- [Python Agent Example](../examples/python-agent/)
|
||||
|
||||
## Contributing
|
||||
|
||||
Found a bug or want to improve Agent Mail integration? See:
|
||||
- [CONTRIBUTING.md](../CONTRIBUTING.md) for beads contribution guidelines
|
||||
- [Agent Mail Issues](https://github.com/Dicklesworthstone/mcp_agent_mail/issues) for server-side issues
|
||||
|
||||
## License
|
||||
|
||||
Beads: Apache 2.0
|
||||
MCP Agent Mail: MIT
|
||||
@@ -1,643 +0,0 @@
|
||||
# Agent Mail Deployment - Last Mile Steps
|
||||
|
||||
Complete step-by-step guide to deploy Agent Mail across all 12 beads-enabled workspaces.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- ✅ MCP Agent Mail package installed at `~/src/mcp_agent_mail/`
|
||||
- ✅ beads integration code completed (just finished)
|
||||
- ✅ Helper scripts created in `scripts/`
|
||||
- ✅ direnv installed (`brew install direnv`)
|
||||
- ✅ direnv hook added to shell config
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
**One Server, Three Channels:**
|
||||
- **Agent Mail Server**: Single instance on `http://127.0.0.1:8765`
|
||||
- **beads.dev**: 5 beads workers communicate here
|
||||
- **vc.dev**: 5 vc workers communicate here
|
||||
- **wyvern.dev**: 3 wyvern workers communicate here
|
||||
|
||||
**Total: 13 workspaces** (12 repos + main beads for version bump)
|
||||
|
||||
## Step 1: Version Bump (5 minutes)
|
||||
|
||||
Since Agent Mail integration is brand new, bump beads version first.
|
||||
|
||||
```bash
|
||||
cd ~/src/fred/beads
|
||||
|
||||
# Determine new version (check current first)
|
||||
./bd --version
|
||||
# Example output: bd version 0.16.0
|
||||
|
||||
# Bump to next version
|
||||
./scripts/bump-version.sh 0.23.0 --commit
|
||||
|
||||
# Push to trigger release
|
||||
git push origin main
|
||||
git push origin v0.23.0
|
||||
```
|
||||
|
||||
**Rationale:** All workspaces should use the new version with Agent Mail support.
|
||||
|
||||
## Step 2: Start Agent Mail Server (2 minutes)
|
||||
|
||||
```bash
|
||||
cd ~/src/fred/beads
|
||||
|
||||
# Start server in background
|
||||
./scripts/start-agent-mail-server.sh
|
||||
|
||||
# Expected output:
|
||||
# ✅ Agent Mail server started successfully!
|
||||
# PID: 12345
|
||||
# Health: http://127.0.0.1:8765/health
|
||||
# Web UI: http://127.0.0.1:8765/mail
|
||||
|
||||
# Verify server health
|
||||
curl http://127.0.0.1:8765/health
|
||||
# Expected: {"status": "healthy"}
|
||||
```
|
||||
|
||||
**Troubleshooting:**
|
||||
- If port 8765 in use: `lsof -i :8765` then `kill <PID>`
|
||||
- If server fails: Check `~/agent-mail.log` for errors
|
||||
- If venv missing: See installation steps in `docs/AGENT_MAIL_QUICKSTART.md`
|
||||
|
||||
## Step 3: Configure All Workspaces (10 minutes)
|
||||
|
||||
Run setup script in each workspace to create `.envrc` files.
|
||||
|
||||
### 3a. Configure 5 beads repos
|
||||
|
||||
```bash
|
||||
# Main beads repo
|
||||
cd ~/src/beads
|
||||
../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# cino/beads fork
|
||||
cd ~/src/cino/beads
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# dave/beads fork
|
||||
cd ~/src/dave/beads
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# emma/beads fork
|
||||
cd ~/src/emma/beads
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# fred/beads fork (current repo)
|
||||
cd ~/src/fred/beads
|
||||
./scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
```
|
||||
|
||||
**Expected .envrc content:**
|
||||
```bash
|
||||
# Agent Mail Configuration
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=fred-beads-macbook # (varies by workspace/hostname)
|
||||
export BEADS_PROJECT_ID=beads.dev
|
||||
```
|
||||
|
||||
### 3b. Configure 5 vc repos
|
||||
|
||||
```bash
|
||||
# Main vc repo (if standalone exists)
|
||||
cd ~/src/vc
|
||||
../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# cino/vc
|
||||
cd ~/src/cino/vc
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# dave/vc
|
||||
cd ~/src/dave/vc
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# fred/vc
|
||||
cd ~/src/fred/vc
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# (One more standalone vc if it exists - adjust path as needed)
|
||||
```
|
||||
|
||||
**Expected PROJECT_ID:** `vc.dev`
|
||||
|
||||
### 3c. Configure 3 wyvern repos
|
||||
|
||||
```bash
|
||||
# Main wyvern repo
|
||||
cd ~/src/wyvern
|
||||
../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# cino/wyvern
|
||||
cd ~/src/cino/wyvern
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
|
||||
# fred/wyvern
|
||||
cd ~/src/fred/wyvern
|
||||
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
direnv allow
|
||||
```
|
||||
|
||||
**Expected PROJECT_ID:** `wyvern.dev`
|
||||
|
||||
## Step 4: Upgrade beads Binary Everywhere (5 minutes)
|
||||
|
||||
After version bump in Step 1, upgrade all workspaces to new version.
|
||||
|
||||
```bash
|
||||
# Wait for GitHub release to build (check https://github.com/steveyegge/beads/releases)
|
||||
# Or build locally if impatient
|
||||
|
||||
# Option 1: Install from release (when ready)
|
||||
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
|
||||
|
||||
# Option 2: Build locally and copy to all repos
|
||||
cd ~/src/fred/beads
|
||||
go build -o bd ./cmd/bd
|
||||
|
||||
# Copy to other repos (example for beads repos)
|
||||
cp bd ~/src/beads/bd
|
||||
cp bd ~/src/cino/beads/bd
|
||||
cp bd ~/src/dave/beads/bd
|
||||
cp bd ~/src/emma/beads/bd
|
||||
|
||||
# Verify new version includes Agent Mail support
|
||||
cd ~/src/fred/beads
|
||||
./bd --version
|
||||
# Expected: bd version 0.23.0 (or whatever you bumped to)
|
||||
|
||||
./bd info --json | grep -i agent
|
||||
# Expected: JSON output showing agent_mail config
|
||||
```
|
||||
|
||||
## Step 5: Document Configuration (2 minutes)
|
||||
|
||||
Add Agent Mail config to each workspace's AGENTS.md (if applicable). Agents need these instructions before testing.
|
||||
|
||||
Example for vc repos:
|
||||
|
||||
```bash
|
||||
cd ~/src/fred/vc
|
||||
|
||||
# Add to AGENTS.md (or create if missing)
|
||||
cat >> AGENTS.md <<'EOF'
|
||||
|
||||
## Agent Mail Configuration
|
||||
|
||||
This workspace participates in multi-agent coordination via MCP Agent Mail.
|
||||
|
||||
**Channel**: vc.dev (shared with all vc workers)
|
||||
**Server**: http://127.0.0.1:8765
|
||||
**Agent Name**: fred-vc-<hostname>
|
||||
|
||||
**Configuration**: Loaded automatically via `.envrc` (direnv)
|
||||
|
||||
**Tightly coupled workers**:
|
||||
- ~/src/vc
|
||||
- ~/src/cino/vc
|
||||
- ~/src/dave/vc
|
||||
- ~/src/fred/vc
|
||||
- (one more standalone)
|
||||
|
||||
All vc workers coordinate issue reservations in real-time (<100ms latency).
|
||||
|
||||
**Cross-project coordination**: vc → beads bugs filed via git/PRs (not Agent Mail messaging)
|
||||
|
||||
See `docs/AGENT_MAIL_MULTI_WORKSPACE_SETUP.md` for details.
|
||||
EOF
|
||||
```
|
||||
|
||||
Repeat for beads and wyvern workspaces with appropriate channel names.
|
||||
|
||||
## Step 6: Test Same-Channel Coordination (5 minutes)
|
||||
|
||||
Verify agents in same channel can see each other's reservations.
|
||||
|
||||
### 6a. Test vc.dev channel (2 vc repos)
|
||||
|
||||
**Terminal 1 - fred/vc:**
|
||||
```bash
|
||||
cd ~/src/fred/vc
|
||||
|
||||
# Verify env vars
|
||||
echo $BEADS_PROJECT_ID # Expected: vc.dev
|
||||
echo $BEADS_AGENT_NAME # Expected: fred-vc-<hostname>
|
||||
|
||||
# Create test issue and reserve it
|
||||
bd create "Test Agent Mail coordination" -p 2 -t task
|
||||
# Example output: bd-test42
|
||||
|
||||
bd update bd-test42 --status in_progress
|
||||
# Expected: ✅ Reserved bd-test42 for fred-vc-macbook
|
||||
```
|
||||
|
||||
**Terminal 2 - cino/vc:**
|
||||
```bash
|
||||
cd ~/src/cino/vc
|
||||
|
||||
# Verify env vars
|
||||
echo $BEADS_PROJECT_ID # Expected: vc.dev
|
||||
echo $BEADS_AGENT_NAME # Expected: cino-vc-<hostname>
|
||||
|
||||
# Try to claim same issue
|
||||
bd update bd-test42 --status in_progress
|
||||
# Expected: ❌ Error - bd-test42 already reserved by fred-vc-macbook
|
||||
```
|
||||
|
||||
**Success!** Collision prevented across different repos in same channel.
|
||||
|
||||
**Terminal 1 - Cleanup:**
|
||||
```bash
|
||||
cd ~/src/fred/vc
|
||||
bd close bd-test42 "Test complete"
|
||||
# Expected: ✅ Reservation released
|
||||
```
|
||||
|
||||
### 6b. Test channel isolation
|
||||
|
||||
Verify agents in different channels DON'T interfere.
|
||||
|
||||
**Terminal 1 - fred/beads (beads.dev):**
|
||||
```bash
|
||||
cd ~/src/fred/beads
|
||||
bd create "Test channel isolation" -p 2
|
||||
# Example: Created bd-test1
|
||||
|
||||
bd update bd-test1 --status in_progress
|
||||
# Expected: Success
|
||||
```
|
||||
|
||||
**Terminal 2 - fred/vc (vc.dev):**
|
||||
```bash
|
||||
cd ~/src/fred/vc
|
||||
bd create "Test channel isolation" -p 2
|
||||
# Example: Created bd-test2
|
||||
|
||||
bd update bd-test2 --status in_progress
|
||||
# Expected: Success (no conflict - different channel!)
|
||||
```
|
||||
|
||||
**Both reservations succeed** because they're in different channels.
|
||||
|
||||
## Step 7: Monitor All Channels (2 minutes)
|
||||
|
||||
```bash
|
||||
cd ~/src/fred/beads
|
||||
|
||||
# Check overall status
|
||||
./scripts/agent-mail-status.sh
|
||||
|
||||
# Expected output:
|
||||
# === Agent Mail Status ===
|
||||
# Server Process: ✅ Running (PID: 12345)
|
||||
# Server Health: ✅ OK
|
||||
# Active Projects:
|
||||
# • beads.dev
|
||||
# • vc.dev
|
||||
# • wyvern.dev
|
||||
# Active File Reservations:
|
||||
# (list of current reservations across all channels)
|
||||
|
||||
# Open Web UI for visual monitoring
|
||||
open http://127.0.0.1:8765/mail
|
||||
```
|
||||
|
||||
## Step 8: Make Server Auto-Start on Reboot (Optional, 5 minutes)
|
||||
|
||||
Use macOS launchd for automatic server startup.
|
||||
|
||||
```bash
|
||||
# Create launchd plist
|
||||
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.user.mcp-agent-mail</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
|
||||
<string>-m</string>
|
||||
<string>mcp_agent_mail.cli</string>
|
||||
<string>serve-http</string>
|
||||
<string>--host</string>
|
||||
<string>127.0.0.1</string>
|
||||
<string>--port</string>
|
||||
<string>8765</string>
|
||||
</array>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/Users/stevey/src/mcp_agent_mail</string>
|
||||
<key>StandardOutPath</key>
|
||||
<string>/Users/stevey/agent-mail.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/Users/stevey/agent-mail-error.log</string>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
|
||||
# Load service
|
||||
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||
|
||||
# Verify loaded
|
||||
launchctl list | grep mcp-agent-mail
|
||||
# Expected: Shows PID and status
|
||||
|
||||
# Test restart
|
||||
sudo reboot # (or just log out/in)
|
||||
# After reboot, verify server auto-started:
|
||||
curl http://127.0.0.1:8765/health
|
||||
```
|
||||
|
||||
## Step 9: Auto-Start on Reboot (Optional, 5 minutes)
|
||||
|
||||
Use macOS launchd for automatic server startup.
|
||||
|
||||
```bash
|
||||
# Create launchd plist
|
||||
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.user.mcp-agent-mail</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
|
||||
<string>-m</string>
|
||||
<string>mcp_agent_mail.cli</string>
|
||||
<string>serve-http</string>
|
||||
<string>--host</string>
|
||||
<string>127.0.0.1</string>
|
||||
<string>--port</string>
|
||||
<string>8765</string>
|
||||
</array>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/Users/stevey/src/mcp_agent_mail</string>
|
||||
<key>StandardOutPath</key>
|
||||
<string>/Users/stevey/agent-mail.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/Users/stevey/agent-mail-error.log</string>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
|
||||
# Load service
|
||||
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||
|
||||
# Verify loaded
|
||||
launchctl list | grep mcp-agent-mail
|
||||
# Expected: Shows PID and status
|
||||
|
||||
# Test restart
|
||||
sudo reboot # (or just log out/in)
|
||||
# After reboot, verify server auto-started:
|
||||
curl http://127.0.0.1:8765/health
|
||||
```
|
||||
|
||||
## Step 10: Verification Checklist
|
||||
|
||||
Run through this checklist to confirm deployment success.
|
||||
|
||||
### ✅ Server Health
|
||||
- [ ] `curl http://127.0.0.1:8765/health` returns `{"status": "healthy"}`
|
||||
- [ ] PID file exists: `cat ~/agent-mail.pid`
|
||||
- [ ] Process running: `ps -p $(cat ~/agent-mail.pid)`
|
||||
- [ ] Logs clean: `tail ~/agent-mail.log` (no errors)
|
||||
|
||||
### ✅ Workspace Configuration
|
||||
- [ ] All 13 workspaces have `.envrc` files
|
||||
- [ ] All `.envrc` files have correct `BEADS_PROJECT_ID`:
|
||||
- 5 beads repos → `beads.dev`
|
||||
- 5 vc repos → `vc.dev`
|
||||
- 3 wyvern repos → `wyvern.dev`
|
||||
- [ ] All workspaces allowed: `direnv allow` in each
|
||||
- [ ] Env vars load automatically when `cd`-ing into workspace
|
||||
|
||||
### ✅ beads Binary
|
||||
- [ ] All workspaces using new version with Agent Mail support
|
||||
- [ ] `bd --version` shows 0.23.0+ everywhere
|
||||
- [ ] `bd info --json | grep agent_mail` shows config
|
||||
|
||||
### ✅ Multi-Agent Coordination
|
||||
- [ ] Same channel: Reservation conflict works (tested in Step 6a)
|
||||
- [ ] Different channels: No interference (tested in Step 6b)
|
||||
- [ ] Web UI shows all 3 channels: http://127.0.0.1:8765/mail
|
||||
- [ ] Status script works: `./scripts/agent-mail-status.sh`
|
||||
|
||||
### ✅ Persistence
|
||||
- [ ] Server survives reboot (if launchd configured in Step 8)
|
||||
- [ ] Reservations cleared on server restart (expected behavior)
|
||||
- [ ] Agents re-register automatically after server restart
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: direnv not loading .envrc
|
||||
|
||||
**Symptoms:**
|
||||
```bash
|
||||
cd ~/src/fred/beads
|
||||
echo $BEADS_PROJECT_ID
|
||||
# (empty output)
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check direnv hook installed
|
||||
grep direnv ~/.zshrc
|
||||
# Should see: eval "$(direnv hook zsh)"
|
||||
|
||||
# If missing, add it
|
||||
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
|
||||
# Allow .envrc
|
||||
cd ~/src/fred/beads
|
||||
direnv allow
|
||||
```
|
||||
|
||||
### Issue: Agent names collide
|
||||
|
||||
**Symptoms:** Two workspaces use same `BEADS_AGENT_NAME`
|
||||
|
||||
**Fix:** Edit `.envrc` to make agent names unique:
|
||||
```bash
|
||||
# Bad (collision!)
|
||||
export BEADS_AGENT_NAME=fred-beads-macbook # Same in fred/beads and fred/vc
|
||||
|
||||
# Good (unique)
|
||||
export BEADS_AGENT_NAME=fred-beads-macbook # In fred/beads
|
||||
export BEADS_AGENT_NAME=fred-vc-macbook # In fred/vc
|
||||
```
|
||||
|
||||
The `setup-agent-mail-workspace.sh` script already handles this by including workspace name.
|
||||
|
||||
### Issue: Server not accessible
|
||||
|
||||
**Symptoms:**
|
||||
```bash
|
||||
bd update bd-42 --status in_progress
|
||||
# WARN Agent Mail unavailable, falling back to git-only mode
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check server health
|
||||
curl http://127.0.0.1:8765/health
|
||||
# If unreachable, restart server:
|
||||
./scripts/stop-agent-mail-server.sh
|
||||
./scripts/start-agent-mail-server.sh
|
||||
```
|
||||
|
||||
### Issue: Old reservations stuck
|
||||
|
||||
**Symptoms:** Agent crashed but reservation persists
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Option 1: Release via API
|
||||
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-stuck
|
||||
|
||||
# Option 2: Restart server (clears all)
|
||||
./scripts/stop-agent-mail-server.sh
|
||||
./scripts/start-agent-mail-server.sh
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Daily Operations
|
||||
|
||||
**Start/stop server manually:**
|
||||
```bash
|
||||
cd ~/src/fred/beads
|
||||
./scripts/start-agent-mail-server.sh
|
||||
./scripts/stop-agent-mail-server.sh
|
||||
```
|
||||
|
||||
**Check status:**
|
||||
```bash
|
||||
./scripts/agent-mail-status.sh
|
||||
```
|
||||
|
||||
**View logs:**
|
||||
```bash
|
||||
tail -f ~/agent-mail.log
|
||||
```
|
||||
|
||||
**Monitor Web UI:**
|
||||
```bash
|
||||
open http://127.0.0.1:8765/mail
|
||||
```
|
||||
|
||||
### Upgrading beads
|
||||
|
||||
When you bump beads version in the future:
|
||||
|
||||
```bash
|
||||
cd ~/src/fred/beads
|
||||
|
||||
# Bump version
|
||||
./scripts/bump-version.sh 0.24.0 --commit
|
||||
git push origin main
|
||||
git push origin v0.24.0
|
||||
|
||||
# Wait for release, then upgrade all workspaces
|
||||
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
|
||||
|
||||
# Or rebuild locally and distribute
|
||||
go build -o bd ./cmd/bd
|
||||
# ... copy to other repos
|
||||
```
|
||||
|
||||
### Adding New Workspaces
|
||||
|
||||
To add a new workspace to Agent Mail coordination:
|
||||
|
||||
```bash
|
||||
# Example: Adding ~/src/gina/beads
|
||||
cd ~/src/gina/beads
|
||||
|
||||
# Run setup script
|
||||
~/src/fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||
|
||||
# Allow direnv
|
||||
direnv allow
|
||||
|
||||
# Verify configuration
|
||||
echo $BEADS_PROJECT_ID
|
||||
# Expected: beads.dev (or vc.dev/wyvern.dev)
|
||||
|
||||
# Test reservation
|
||||
bd ready | head -1 | xargs -I {} bd update {} --status in_progress
|
||||
# Should work immediately
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
You've successfully deployed Agent Mail when:
|
||||
|
||||
1. ✅ **Server running**: `curl http://127.0.0.1:8765/health` returns healthy
|
||||
2. ✅ **All workspaces configured**: 13 `.envrc` files created and allowed
|
||||
3. ✅ **Three channels active**: beads.dev, vc.dev, wyvern.dev visible in Web UI
|
||||
4. ✅ **Coordination works**: Reservation conflict test passes (Step 6a)
|
||||
5. ✅ **Isolation works**: Different channels don't interfere (Step 6b)
|
||||
6. ✅ **Monitoring works**: Status script shows all active projects
|
||||
7. ✅ **Auto-start works**: Server survives reboot (if Step 8 completed)
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful deployment:
|
||||
|
||||
1. **Start using bd normally** - Agent Mail coordination happens automatically
|
||||
2. **Monitor reservations** via Web UI during concurrent work
|
||||
3. **File issues** for any coordination bugs (rare with hash-based IDs)
|
||||
4. **Consider MCP integration** for Claude Desktop (see `docs/AGENT_MAIL_QUICKSTART.md`)
|
||||
5. **Wait for cross-project messaging** (planned in Agent Mail roadmap)
|
||||
|
||||
## Reference
|
||||
|
||||
- **Main Guide**: [AGENT_MAIL_MULTI_WORKSPACE_SETUP.md](AGENT_MAIL_MULTI_WORKSPACE_SETUP.md)
|
||||
- **Quick Start**: [AGENT_MAIL_QUICKSTART.md](AGENT_MAIL_QUICKSTART.md)
|
||||
- **Architecture**: [AGENT_MAIL.md](AGENT_MAIL.md)
|
||||
- **ADR**: [adr/002-agent-mail-integration.md](adr/002-agent-mail-integration.md)
|
||||
|
||||
## Timeline Estimate
|
||||
|
||||
- **Step 1** (Version bump): 5 minutes
|
||||
- **Step 2** (Start server): 2 minutes
|
||||
- **Step 3** (Configure 13 workspaces): 10 minutes
|
||||
- **Step 4** (Upgrade binaries): 5 minutes
|
||||
- **Step 5** (Document): 2 minutes
|
||||
- **Step 6** (Same-channel test): 5 minutes
|
||||
- **Step 7** (Channel isolation test): 5 minutes
|
||||
- **Step 8** (Monitor): 2 minutes
|
||||
- **Step 9** (Auto-start, optional): 5 minutes
|
||||
- **Step 10** (Verify checklist): 5 minutes
|
||||
|
||||
**Total: ~46 minutes** (or ~41 minutes if skipping auto-start)
|
||||
|
||||
You're ready to deploy! 🚀
|
||||
@@ -1,345 +0,0 @@
|
||||
# Multi-Workspace Agent Mail Setup
|
||||
|
||||
Guide for running Agent Mail across multiple beads repositories.
|
||||
|
||||
## Service Management
|
||||
|
||||
### Start Agent Mail Server (One Instance for All Projects)
|
||||
|
||||
```bash
|
||||
# Start in background with nohup
|
||||
cd ~/src/mcp_agent_mail
|
||||
source .venv/bin/activate
|
||||
nohup python -m mcp_agent_mail.cli serve-http --host 127.0.0.1 --port 8765 > ~/agent-mail.log 2>&1 &
|
||||
echo $! > ~/agent-mail.pid
|
||||
```
|
||||
|
||||
### Check Server Status
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://127.0.0.1:8765/health
|
||||
|
||||
# View logs
|
||||
tail -f ~/agent-mail.log
|
||||
|
||||
# Check process
|
||||
ps aux | grep mcp_agent_mail
|
||||
# Or use saved PID
|
||||
ps -p $(cat ~/agent-mail.pid) || echo "Server not running"
|
||||
```
|
||||
|
||||
### Restart Server
|
||||
|
||||
```bash
|
||||
# Kill old server
|
||||
kill $(cat ~/agent-mail.pid) 2>/dev/null || pkill -f mcp_agent_mail
|
||||
|
||||
# Start fresh
|
||||
cd ~/src/mcp_agent_mail
|
||||
source .venv/bin/activate
|
||||
nohup python -m mcp_agent_mail.cli serve-http --host 127.0.0.1 --port 8765 > ~/agent-mail.log 2>&1 &
|
||||
echo $! > ~/agent-mail.pid
|
||||
```
|
||||
|
||||
### Auto-Start on Reboot (macOS launchd)
|
||||
|
||||
```bash
|
||||
# Create ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.user.mcp-agent-mail</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
|
||||
<string>-m</string>
|
||||
<string>mcp_agent_mail.cli</string>
|
||||
<string>serve-http</string>
|
||||
<string>--host</string>
|
||||
<string>127.0.0.1</string>
|
||||
<string>--port</string>
|
||||
<string>8765</string>
|
||||
</array>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/Users/stevey/src/mcp_agent_mail</string>
|
||||
<key>StandardOutPath</key>
|
||||
<string>/Users/stevey/agent-mail.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/Users/stevey/agent-mail-error.log</string>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
|
||||
# Load service
|
||||
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||
|
||||
# Check status
|
||||
launchctl list | grep mcp-agent-mail
|
||||
```
|
||||
|
||||
## Project Configuration Strategy
|
||||
|
||||
**Three team channels** for tightly-coupled workers:
|
||||
|
||||
```bash
|
||||
beads.dev → All beads workers (5 repos)
|
||||
vc.dev → All vc workers (5 repos)
|
||||
wyvern.dev → All wyvern workers (3 repos)
|
||||
```
|
||||
|
||||
**Why this design:**
|
||||
- Each team's workers are tightly coupled and need frequent coordination
|
||||
- Simple namespace strings (no filesystem paths required)
|
||||
- Usenet-style naming for clarity
|
||||
- Cross-project filing handled via git/PRs for now (until Agent Mail adds cross-project messaging)
|
||||
|
||||
### Configuration by Workspace
|
||||
|
||||
```bash
|
||||
# All beads repos use same project
|
||||
~/src/beads → BEADS_PROJECT_ID=beads.dev
|
||||
~/src/cino/beads → BEADS_PROJECT_ID=beads.dev
|
||||
~/src/dave/beads → BEADS_PROJECT_ID=beads.dev
|
||||
~/src/emma/beads → BEADS_PROJECT_ID=beads.dev
|
||||
~/src/fred/beads → BEADS_PROJECT_ID=beads.dev
|
||||
|
||||
# All vc repos use same project
|
||||
~/src/cino/vc → BEADS_PROJECT_ID=vc.dev
|
||||
~/src/dave/vc → BEADS_PROJECT_ID=vc.dev
|
||||
~/src/fred/vc → BEADS_PROJECT_ID=vc.dev
|
||||
~/src/vc → BEADS_PROJECT_ID=vc.dev
|
||||
(standalone at ~/src/vc if exists)
|
||||
|
||||
# All wyvern repos use same project
|
||||
~/src/cino/wyvern → BEADS_PROJECT_ID=wyvern.dev
|
||||
~/src/fred/wyvern → BEADS_PROJECT_ID=wyvern.dev
|
||||
~/src/wyvern → BEADS_PROJECT_ID=wyvern.dev
|
||||
```
|
||||
|
||||
## Per-Directory Configuration
|
||||
|
||||
Create `.envrc` or `.env` file in each workspace:
|
||||
|
||||
### Example: ~/src/fred/vc/.envrc
|
||||
|
||||
```bash
|
||||
# Agent Mail Configuration for fred's vc
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=fred-vc-$(hostname)
|
||||
export BEADS_PROJECT_ID=vc.dev
|
||||
|
||||
# Load with direnv
|
||||
# Install direnv: brew install direnv
|
||||
# Then: direnv allow
|
||||
```
|
||||
|
||||
### Example: ~/src/cino/beads/.envrc
|
||||
|
||||
```bash
|
||||
# Agent Mail Configuration for cino's beads fork
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=cino-beads-$(hostname)
|
||||
export BEADS_PROJECT_ID=beads.dev
|
||||
```
|
||||
|
||||
### Quick Setup Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# setup-agent-mail.sh - Run in each workspace
|
||||
|
||||
WORKSPACE=$(pwd)
|
||||
WORKSPACE_NAME=$(basename $WORKSPACE)
|
||||
PARENT=$(basename $(dirname $WORKSPACE))
|
||||
|
||||
# Determine project ID based on coupling
|
||||
case "$WORKSPACE_NAME" in
|
||||
vc|wyvern)
|
||||
# Tightly coupled - use parent coordination project
|
||||
PROJECT_ID="/Users/stevey/src/${PARENT}/coordination"
|
||||
;;
|
||||
beads)
|
||||
# Loosely coupled - use workspace as project
|
||||
PROJECT_ID="$WORKSPACE"
|
||||
;;
|
||||
*)
|
||||
# Default - use workspace
|
||||
PROJECT_ID="$WORKSPACE"
|
||||
;;
|
||||
esac
|
||||
|
||||
cat > .envrc <<EOF
|
||||
# Agent Mail Configuration
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=${PARENT}-${WORKSPACE_NAME}-\$(hostname)
|
||||
export BEADS_PROJECT_ID=$PROJECT_ID
|
||||
EOF
|
||||
|
||||
echo "Created .envrc with PROJECT_ID=$PROJECT_ID"
|
||||
echo "Run: direnv allow"
|
||||
```
|
||||
|
||||
## Project Relationship Matrix
|
||||
|
||||
| Workspace | Project Channel | Agent Name | Can Message |
|
||||
|-----------|----------------|------------|-------------|
|
||||
| ~/src/beads | beads.dev | main-beads-* | All beads workers ✅ |
|
||||
| ~/src/cino/beads | beads.dev | cino-beads-* | All beads workers ✅ |
|
||||
| ~/src/dave/beads | beads.dev | dave-beads-* | All beads workers ✅ |
|
||||
| ~/src/emma/beads | beads.dev | emma-beads-* | All beads workers ✅ |
|
||||
| ~/src/fred/beads | beads.dev | fred-beads-* | All beads workers ✅ |
|
||||
| ~/src/cino/vc | vc.dev | cino-vc-* | All vc workers ✅ |
|
||||
| ~/src/dave/vc | vc.dev | dave-vc-* | All vc workers ✅ |
|
||||
| ~/src/fred/vc | vc.dev | fred-vc-* | All vc workers ✅ |
|
||||
| ~/src/vc | vc.dev | main-vc-* | All vc workers ✅ |
|
||||
| ~/src/cino/wyvern | wyvern.dev | cino-wyvern-* | All wyvern workers ✅ |
|
||||
| ~/src/fred/wyvern | wyvern.dev | fred-wyvern-* | All wyvern workers ✅ |
|
||||
| ~/src/wyvern | wyvern.dev | main-wyvern-* | All wyvern workers ✅ |
|
||||
|
||||
## Monitoring Multiple Projects
|
||||
|
||||
### Web UI
|
||||
|
||||
View all projects and agents:
|
||||
```bash
|
||||
open http://127.0.0.1:8765/mail
|
||||
```
|
||||
|
||||
### API Queries
|
||||
|
||||
```bash
|
||||
# List all projects
|
||||
curl http://127.0.0.1:8765/api/projects | jq
|
||||
|
||||
# View agents in specific project
|
||||
curl "http://127.0.0.1:8765/api/projects/$(urlencode /Users/stevey/src/fred/coordination)/agents" | jq
|
||||
|
||||
# Check file reservations across all projects
|
||||
curl http://127.0.0.1:8765/api/file_reservations | jq
|
||||
```
|
||||
|
||||
### Unified Dashboard Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# agent-mail-status.sh - View all active agents and reservations
|
||||
|
||||
echo "=== Agent Mail Status ==="
|
||||
echo
|
||||
|
||||
echo "Server Health:"
|
||||
curl -s http://127.0.0.1:8765/health | jq -r '.status // "UNREACHABLE"'
|
||||
echo
|
||||
|
||||
echo "Active Projects:"
|
||||
curl -s http://127.0.0.1:8765/api/projects | jq -r '.[] | "\(.slug) - \(.human_key)"'
|
||||
echo
|
||||
|
||||
echo "Active Reservations:"
|
||||
curl -s http://127.0.0.1:8765/api/file_reservations | jq -r '.[] | "\(.agent_name) → \(.resource_id) (\(.project_id))"'
|
||||
```
|
||||
|
||||
## Future: Cross-Project Messaging
|
||||
|
||||
When Agent Mail adds cross-project support (planned), you'll be able to:
|
||||
|
||||
```bash
|
||||
# Send message from fred/vc to cino/vc
|
||||
bd agent-mail send \
|
||||
--from fred-vc \
|
||||
--to cino-vc \
|
||||
--to-project /Users/stevey/src/cino/coordination \
|
||||
--subject "API changes in shared library"
|
||||
```
|
||||
|
||||
For now, use git commits/PRs for cross-project coordination.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: Different agents step on each other
|
||||
|
||||
**Symptom:** Two agents in same project both claim same issue
|
||||
|
||||
**Cause:** Agents using different `BEADS_AGENT_NAME` but same project
|
||||
|
||||
**Fix:** Ensure unique agent names per workspace:
|
||||
```bash
|
||||
export BEADS_AGENT_NAME=$(whoami)-$(basename $PWD)-$(hostname)
|
||||
```
|
||||
|
||||
### Problem: Agents can't see each other
|
||||
|
||||
**Symptom:** Agent sends message but recipient doesn't receive it
|
||||
|
||||
**Cause:** Agents in different `BEADS_PROJECT_ID`
|
||||
|
||||
**Fix:** Verify both agents use same project ID:
|
||||
```bash
|
||||
# In each workspace
|
||||
echo $BEADS_PROJECT_ID
|
||||
```
|
||||
|
||||
### Problem: Reservation persists after crash
|
||||
|
||||
**Symptom:** Issue stays reserved after agent died
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Release via API
|
||||
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-stuck-issue
|
||||
|
||||
# Or restart server (clears all)
|
||||
kill $(cat ~/agent-mail.pid)
|
||||
cd ~/src/mcp_agent_mail
|
||||
source .venv/bin/activate
|
||||
nohup python -m mcp_agent_mail.cli serve-http --host 127.0.0.1 --port 8765 > ~/agent-mail.log 2>&1 &
|
||||
echo $! > ~/agent-mail.pid
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use direnv for automatic env loading**
|
||||
```bash
|
||||
brew install direnv
|
||||
# Add to ~/.zshrc: eval "$(direnv hook zsh)"
|
||||
# Then create .envrc in each workspace
|
||||
```
|
||||
|
||||
2. **Descriptive agent names**
|
||||
```bash
|
||||
# Bad: export BEADS_AGENT_NAME=agent1
|
||||
# Good: export BEADS_AGENT_NAME=fred-vc-macbook
|
||||
```
|
||||
|
||||
3. **Monitor server logs**
|
||||
```bash
|
||||
tail -f ~/agent-mail.log
|
||||
```
|
||||
|
||||
4. **Health check in scripts**
|
||||
```bash
|
||||
if ! curl -sf http://127.0.0.1:8765/health > /dev/null; then
|
||||
echo "WARNING: Agent Mail unavailable (falling back to git-only)"
|
||||
fi
|
||||
```
|
||||
|
||||
5. **Document project relationships**
|
||||
- Keep this file updated when adding workspaces
|
||||
- Add comments in .envrc explaining project coupling
|
||||
|
||||
## Summary
|
||||
|
||||
- **One server** handles all projects (lightweight HTTP API)
|
||||
- **Project ID = namespace** for agent isolation
|
||||
- **Tight coupling** → shared project (vc + wyvern)
|
||||
- **Loose coupling** → separate projects (beads forks)
|
||||
- **Auto-restart** via launchd recommended
|
||||
- **Per-directory .envrc** for automatic config loading
|
||||
@@ -1,477 +0,0 @@
|
||||
# Agent Mail Quick Start Guide
|
||||
|
||||
Get started with Agent Mail for multi-agent bd coordination in 5 minutes.
|
||||
|
||||
## What is Agent Mail?
|
||||
|
||||
Agent Mail is an **optional** coordination layer for bd that reduces latency from 2-5 seconds (git sync) to <100ms (HTTP API) and prevents work collisions through file reservations.
|
||||
|
||||
**When to use it:**
|
||||
- ✅ Multiple AI agents working concurrently
|
||||
- ✅ Frequent status updates (high collision risk)
|
||||
- ✅ Real-time coordination needed
|
||||
|
||||
**When to skip it:**
|
||||
- ❌ Single agent workflows
|
||||
- ❌ Infrequent updates (low collision risk)
|
||||
- ❌ Simplicity preferred over latency
|
||||
|
||||
## 5-Minute Setup
|
||||
|
||||
### Step 1: Install Agent Mail Server (30 seconds)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git ~/mcp_agent_mail
|
||||
cd ~/mcp_agent_mail
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Step 2: Start the Server (5 seconds)
|
||||
|
||||
```bash
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
# ✅ Server running on http://127.0.0.1:8765
|
||||
```
|
||||
|
||||
Leave this terminal open. Open a new terminal for Step 3.
|
||||
|
||||
### Step 3: Configure Your Agent (10 seconds)
|
||||
|
||||
```bash
|
||||
# Set environment variables
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=my-agent
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
```
|
||||
|
||||
### Step 4: Use bd Normally (30 seconds)
|
||||
|
||||
```bash
|
||||
# Find ready work
|
||||
bd ready
|
||||
|
||||
# Claim an issue
|
||||
bd update bd-42 --status in_progress
|
||||
# ✅ Reserved bd-42 for my-agent in <100ms
|
||||
|
||||
# Complete work
|
||||
bd close bd-42 "Done"
|
||||
# ✅ Reservation released automatically
|
||||
```
|
||||
|
||||
**That's it!** bd now uses Agent Mail for coordination.
|
||||
|
||||
### Step 5: Test Multi-Agent (1 minute)
|
||||
|
||||
Open a second terminal:
|
||||
|
||||
```bash
|
||||
# Terminal 2 - Different agent
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=other-agent
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
|
||||
# Try claiming same issue
|
||||
bd update bd-42 --status in_progress
|
||||
# ❌ Error: bd-42 already reserved by my-agent
|
||||
```
|
||||
|
||||
**Success!** Agent Mail prevented collision.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Use Case 1: Claude Desktop + Command Line Agent
|
||||
|
||||
**Terminal 1 - Agent Mail Server:**
|
||||
```bash
|
||||
cd ~/mcp_agent_mail
|
||||
source .venv/bin/activate
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
```
|
||||
|
||||
**Terminal 2 - Command Line:**
|
||||
```bash
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=cli-user
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
|
||||
bd ready
|
||||
bd update bd-100 --status in_progress
|
||||
```
|
||||
|
||||
**Claude Desktop:**
|
||||
```
|
||||
# In Claude's MCP settings, add env vars:
|
||||
{
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"env": {
|
||||
"BEADS_AGENT_MAIL_URL": "http://127.0.0.1:8765",
|
||||
"BEADS_AGENT_NAME": "claude",
|
||||
"BEADS_PROJECT_ID": "my-project"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now Claude and your command line won't step on each other!
|
||||
|
||||
### Use Case 2: Multiple Python Agents
|
||||
|
||||
**Terminal 1 - Server:**
|
||||
```bash
|
||||
cd ~/mcp_agent_mail
|
||||
source .venv/bin/activate
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
```
|
||||
|
||||
**Terminal 2 - Agent A:**
|
||||
```bash
|
||||
cd ~/myproject/examples/python-agent
|
||||
./agent_with_mail.py \
|
||||
--agent-name alice \
|
||||
--project-id myproject \
|
||||
--agent-mail-url http://127.0.0.1:8765
|
||||
```
|
||||
|
||||
**Terminal 3 - Agent B:**
|
||||
```bash
|
||||
cd ~/myproject/examples/python-agent
|
||||
./agent_with_mail.py \
|
||||
--agent-name bob \
|
||||
--project-id myproject \
|
||||
--agent-mail-url http://127.0.0.1:8765
|
||||
```
|
||||
|
||||
Watch them coordinate in real-time!
|
||||
|
||||
### Use Case 3: Team Workflow
|
||||
|
||||
**Shared Server (runs on dev machine):**
|
||||
```bash
|
||||
# Machine 192.168.1.100
|
||||
python -m mcp_agent_mail.cli serve-http --host 0.0.0.0
|
||||
```
|
||||
|
||||
**Team Member 1:**
|
||||
```bash
|
||||
export BEADS_AGENT_MAIL_URL=http://192.168.1.100:8765
|
||||
export BEADS_AGENT_NAME=alice
|
||||
export BEADS_PROJECT_ID=team-project
|
||||
|
||||
bd ready
|
||||
```
|
||||
|
||||
**Team Member 2:**
|
||||
```bash
|
||||
export BEADS_AGENT_MAIL_URL=http://192.168.1.100:8765
|
||||
export BEADS_AGENT_NAME=bob
|
||||
export BEADS_PROJECT_ID=team-project
|
||||
|
||||
bd ready
|
||||
```
|
||||
|
||||
Entire team shares one coordination server!
|
||||
|
||||
### Use Case 4: CI/CD Pipeline
|
||||
|
||||
**GitHub Actions Example:**
|
||||
|
||||
```yaml
|
||||
name: AI Agent Workflow
|
||||
on: [push]
|
||||
|
||||
jobs:
|
||||
agent-work:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
services:
|
||||
agent-mail:
|
||||
image: ghcr.io/dicklesworthstone/mcp_agent_mail:latest
|
||||
ports:
|
||||
- 8765:8765
|
||||
|
||||
strategy:
|
||||
matrix:
|
||||
agent: [agent-1, agent-2, agent-3]
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Run agent
|
||||
env:
|
||||
BEADS_AGENT_MAIL_URL: http://localhost:8765
|
||||
BEADS_AGENT_NAME: ${{ matrix.agent }}
|
||||
BEADS_PROJECT_ID: ${{ github.repository }}
|
||||
run: |
|
||||
bd ready | head -1 | xargs -I {} bd update {} --status in_progress
|
||||
# ... do work ...
|
||||
bd close {} "Completed by CI"
|
||||
```
|
||||
|
||||
Three agents run in parallel without collisions!
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After setup, verify everything works:
|
||||
|
||||
**✅ Server is running:**
|
||||
```bash
|
||||
curl http://127.0.0.1:8765/health
|
||||
# Expected: {"status": "healthy"}
|
||||
```
|
||||
|
||||
**✅ Environment variables are set:**
|
||||
```bash
|
||||
echo $BEADS_AGENT_MAIL_URL
|
||||
# Expected: http://127.0.0.1:8765
|
||||
|
||||
echo $BEADS_AGENT_NAME
|
||||
# Expected: my-agent
|
||||
|
||||
echo $BEADS_PROJECT_ID
|
||||
# Expected: my-project
|
||||
```
|
||||
|
||||
**✅ bd sees Agent Mail:**
|
||||
```bash
|
||||
bd info --json | grep agent_mail
|
||||
# Expected: JSON with agent_mail config
|
||||
```
|
||||
|
||||
**✅ Reservations work:**
|
||||
```bash
|
||||
# Terminal 1
|
||||
bd update bd-test --status in_progress
|
||||
# Expected: Success
|
||||
|
||||
# Terminal 2 (different agent)
|
||||
export BEADS_AGENT_NAME=other-agent
|
||||
bd update bd-test --status in_progress
|
||||
# Expected: Error - reservation conflict
|
||||
```
|
||||
|
||||
**✅ Graceful degradation works:**
|
||||
```bash
|
||||
# Stop server (Ctrl+C in server terminal)
|
||||
|
||||
# Try bd command
|
||||
bd ready
|
||||
# Expected: Warning about Agent Mail unavailable, but command succeeds
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: "Agent Mail unavailable" warnings
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
WARN Agent Mail unavailable, falling back to git-only mode
|
||||
```
|
||||
|
||||
**Quick Fix:**
|
||||
1. Check server is running: `curl http://127.0.0.1:8765/health`
|
||||
2. Verify URL is correct: `echo $BEADS_AGENT_MAIL_URL`
|
||||
3. Restart server if needed
|
||||
|
||||
### Problem: Agents don't see each other's reservations
|
||||
|
||||
**Cause:** Different `BEADS_PROJECT_ID` values
|
||||
|
||||
**Quick Fix:**
|
||||
```bash
|
||||
# All agents MUST use same project ID!
|
||||
export BEADS_PROJECT_ID=same-project-name
|
||||
```
|
||||
|
||||
### Problem: Reservation stuck after agent crashes
|
||||
|
||||
**Quick Fix:**
|
||||
```bash
|
||||
# Option 1: Release via API
|
||||
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-stuck
|
||||
|
||||
# Option 2: Restart server (clears all reservations)
|
||||
pkill -f mcp_agent_mail
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
```
|
||||
|
||||
### Problem: Port 8765 already in use
|
||||
|
||||
**Quick Fix:**
|
||||
```bash
|
||||
# Find what's using port
|
||||
lsof -i :8765 # macOS/Linux
|
||||
netstat -ano | findstr :8765 # Windows
|
||||
|
||||
# Kill old server
|
||||
pkill -f mcp_agent_mail
|
||||
|
||||
# Or use different port
|
||||
python -m mcp_agent_mail.cli serve-http --port 8766
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8766
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Web UI
|
||||
|
||||
View all reservations in real-time:
|
||||
```bash
|
||||
open http://127.0.0.1:8765/mail
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
Check reservations programmatically:
|
||||
```bash
|
||||
# List all reservations
|
||||
curl http://127.0.0.1:8765/api/reservations | jq
|
||||
|
||||
# Check specific reservation
|
||||
curl http://127.0.0.1:8765/api/reservations/bd-42 | jq
|
||||
|
||||
# Release reservation manually
|
||||
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-42
|
||||
```
|
||||
|
||||
### Logs
|
||||
|
||||
Agent Mail logs to stdout. Redirect to file if needed:
|
||||
```bash
|
||||
python -m mcp_agent_mail.cli serve-http > agent-mail.log 2>&1 &
|
||||
tail -f agent-mail.log
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Descriptive Agent Names
|
||||
|
||||
**Bad:**
|
||||
```bash
|
||||
export BEADS_AGENT_NAME=agent1
|
||||
export BEADS_AGENT_NAME=agent2
|
||||
```
|
||||
|
||||
**Good:**
|
||||
```bash
|
||||
export BEADS_AGENT_NAME=claude-frontend
|
||||
export BEADS_AGENT_NAME=gpt4-backend
|
||||
export BEADS_AGENT_NAME=alice-laptop
|
||||
```
|
||||
|
||||
Makes debugging much easier!
|
||||
|
||||
### 2. Set Environment Variables Globally
|
||||
|
||||
**Option 1: Shell Profile**
|
||||
```bash
|
||||
# Add to ~/.bashrc or ~/.zshrc
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=$(whoami)-$(hostname)
|
||||
export BEADS_PROJECT_ID=$(basename $(pwd))
|
||||
```
|
||||
|
||||
**Option 2: Project Config**
|
||||
```bash
|
||||
# .env file in project root
|
||||
BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
BEADS_AGENT_NAME=my-agent
|
||||
BEADS_PROJECT_ID=my-project
|
||||
|
||||
# Load in scripts
|
||||
source .env
|
||||
```
|
||||
|
||||
### 3. Use Same Project ID Across Team
|
||||
|
||||
Create a shared config:
|
||||
```bash
|
||||
# team-config.sh
|
||||
export BEADS_PROJECT_ID=our-team-project
|
||||
export BEADS_AGENT_MAIL_URL=http://agent-mail.internal:8765
|
||||
|
||||
# Each team member sources it
|
||||
source team-config.sh
|
||||
export BEADS_AGENT_NAME=alice # Only this differs per person
|
||||
```
|
||||
|
||||
### 4. Monitor Reservations in Long-Running Agents
|
||||
|
||||
```python
|
||||
# Check reservation health periodically
|
||||
import requests
|
||||
|
||||
def check_reservations():
|
||||
resp = requests.get(f"{agent_mail_url}/api/reservations")
|
||||
my_reservations = [r for r in resp.json() if r["agent_id"] == agent_name]
|
||||
|
||||
for res in my_reservations:
|
||||
# Release if work completed
|
||||
if is_done(res["resource_id"]):
|
||||
requests.delete(f"{agent_mail_url}/api/reservations/{res['resource_id']}")
|
||||
```
|
||||
|
||||
### 5. Handle Graceful Degradation
|
||||
|
||||
Always assume Agent Mail might be unavailable:
|
||||
```python
|
||||
try:
|
||||
bd_update(issue_id, status="in_progress")
|
||||
except ReservationConflict:
|
||||
# Expected - try different issue
|
||||
pass
|
||||
except Exception:
|
||||
# Agent Mail down - falls back to git
|
||||
# Continue normally
|
||||
pass
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Read the full guide**: [AGENT_MAIL.md](AGENT_MAIL.md)
|
||||
2. **Try the Python example**: [examples/python-agent/AGENT_MAIL_EXAMPLE.md](../examples/python-agent/AGENT_MAIL_EXAMPLE.md)
|
||||
3. **Review the ADR**: [adr/002-agent-mail-integration.md](adr/002-agent-mail-integration.md)
|
||||
|
||||
## Getting Help
|
||||
|
||||
**Documentation:**
|
||||
- [AGENT_MAIL.md](AGENT_MAIL.md) - Complete integration guide
|
||||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - General bd troubleshooting
|
||||
- [FAQ.md](FAQ.md) - Frequently asked questions
|
||||
|
||||
**Issues:**
|
||||
- [bd issues](https://github.com/steveyegge/beads/issues) - Integration bugs
|
||||
- [Agent Mail issues](https://github.com/Dicklesworthstone/mcp_agent_mail/issues) - Server bugs
|
||||
|
||||
**Community:**
|
||||
- [Discussions](https://github.com/steveyegge/beads/discussions) - Ask questions
|
||||
- [Examples](../examples/) - Learn from working code
|
||||
|
||||
## TL;DR - Copy-Paste Setup
|
||||
|
||||
```bash
|
||||
# 1. Install Agent Mail
|
||||
git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git ~/mcp_agent_mail
|
||||
cd ~/mcp_agent_mail
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -e .
|
||||
|
||||
# 2. Start server (leave running)
|
||||
python -m mcp_agent_mail.cli serve-http &
|
||||
|
||||
# 3. Configure agent (in new terminal)
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=my-agent
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
|
||||
# 4. Use bd normally - coordination happens automatically!
|
||||
bd ready
|
||||
bd update bd-42 --status in_progress
|
||||
bd close bd-42 "Done"
|
||||
```
|
||||
|
||||
**Done!** You're now using Agent Mail for sub-100ms coordination.
|
||||
@@ -25,8 +25,7 @@ bd info --json
|
||||
# {
|
||||
# "database_path": "/path/to/.beads/beads.db",
|
||||
# "issue_prefix": "bd",
|
||||
# "daemon_running": true,
|
||||
# "agent_mail_enabled": false
|
||||
# "daemon_running": true
|
||||
# }
|
||||
```
|
||||
|
||||
|
||||
@@ -197,40 +197,6 @@ bd cleanup --force
|
||||
|
||||
**Note:** Compaction is permanent graceful decay. Original content is discarded but viewable via `bd restore <id>` from git history.
|
||||
|
||||
## Advanced: Agent Mail (Optional)
|
||||
|
||||
For **multi-agent workflows** (2+ AI agents working concurrently), Agent Mail provides real-time coordination:
|
||||
|
||||
**Benefits:**
|
||||
- 20-50x latency reduction (<100ms vs 2-5s git sync)
|
||||
- Collision prevention via file reservations
|
||||
- Agents can't accidentally claim same issue
|
||||
|
||||
**Quick setup:**
|
||||
```bash
|
||||
# Install and start server (one-time)
|
||||
git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git
|
||||
cd mcp_agent_mail && python3 -m venv .venv && source .venv/bin/activate
|
||||
pip install -e .
|
||||
python -m mcp_agent_mail.cli serve-http
|
||||
|
||||
# Configure each agent (environment variables)
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_NAME=assistant-alpha # Unique per agent
|
||||
export BEADS_PROJECT_ID=my-project
|
||||
|
||||
# Use bd normally - Agent Mail auto-activates
|
||||
bd ready
|
||||
bd update bd-42 --status in_progress # Reserves instantly
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- ✅ Multiple agents working simultaneously
|
||||
- ✅ High collision risk (frequent status updates)
|
||||
- ❌ Single agent workflows (unnecessary overhead)
|
||||
|
||||
See [AGENT_MAIL.md](AGENT_MAIL.md) for complete guide.
|
||||
|
||||
## Background Daemon
|
||||
|
||||
bd runs a background daemon for auto-sync and performance. You rarely need to manage it directly:
|
||||
|
||||
@@ -1,228 +0,0 @@
|
||||
# ADR 002: MCP Agent Mail Integration for Multi-Agent Coordination
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2025-11-08
|
||||
**Epic:** [bd-spmx](../../.beads/beads.db) (Investigation & Proof of Concept)
|
||||
**Related Issues:** bd-6hji, bd-htfk, bd-muls
|
||||
|
||||
## Context
|
||||
|
||||
Beads is designed for AI-supervised coding workflows where multiple AI agents coordinate work on shared codebases. As multi-agent systems become more common, we face challenges:
|
||||
|
||||
### Problem Statement
|
||||
|
||||
1. **Git Sync Latency**: Current git-based synchronization has 2-5 second round-trip latency for status updates
|
||||
2. **No Collision Prevention**: Two agents can claim the same issue simultaneously, causing wasted work and merge conflicts
|
||||
3. **Git Repository Pollution**: Frequent agent status updates create noisy git history with dozens of micro-commits
|
||||
4. **Lack of Real-Time Awareness**: Agents don't know what other agents are working on until after git sync completes
|
||||
|
||||
### Current Workflow
|
||||
|
||||
```
|
||||
Agent A: bd update bd-123 --status in_progress
|
||||
↓ (30s debounce)
|
||||
↓ export to JSONL
|
||||
↓ git commit + push (1-2s)
|
||||
↓
|
||||
Agent B: git pull (1-2s)
|
||||
↓ import from JSONL
|
||||
↓ sees bd-123 is taken (too late!)
|
||||
```
|
||||
|
||||
Total latency: **2000-5000ms**
|
||||
|
||||
## Decision
|
||||
|
||||
**Adopt MCP Agent Mail as an *optional* coordination layer** for real-time multi-agent communication, while maintaining full backward compatibility with git-only workflows.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### 1. Custom RPC Server
|
||||
**Pros:**
|
||||
- Full control over implementation
|
||||
- Optimized for beads-specific needs
|
||||
|
||||
**Cons:**
|
||||
- High development cost (3-4 weeks)
|
||||
- Maintenance burden
|
||||
- Reinventing the wheel
|
||||
|
||||
**Verdict:** ❌ Too much effort for marginal benefit
|
||||
|
||||
### 2. Redis/Memcached
|
||||
**Pros:**
|
||||
- Battle-tested infrastructure
|
||||
- Low latency
|
||||
|
||||
**Cons:**
|
||||
- Heavy dependency (requires separate service)
|
||||
- Overkill for lightweight coordination
|
||||
- No built-in authentication/multi-tenancy
|
||||
|
||||
**Verdict:** ❌ Too heavy for beads' lightweight ethos
|
||||
|
||||
### 3. Git-Only (Status Quo)
|
||||
**Pros:**
|
||||
- Zero dependencies
|
||||
- Works everywhere git works
|
||||
|
||||
**Cons:**
|
||||
- 2-5s latency for status updates
|
||||
- No collision prevention
|
||||
- Noisy git history
|
||||
|
||||
**Verdict:** ✅ Remains the default, Agent Mail is optional enhancement
|
||||
|
||||
### 4. MCP Agent Mail (Chosen)
|
||||
**Pros:**
|
||||
- Lightweight HTTP server (<50MB memory)
|
||||
- <100ms latency for status updates (20-50x faster than git)
|
||||
- Built-in file reservation system (prevents collisions)
|
||||
- Project/agent isolation (multi-tenancy support)
|
||||
- Optional: graceful degradation to git-only mode
|
||||
- Active maintenance by @Dicklesworthstone
|
||||
|
||||
**Cons:**
|
||||
- External dependency (requires running server)
|
||||
- Adds complexity for single-agent workflows (mitigated by optional nature)
|
||||
|
||||
**Verdict:** ✅ Best balance of benefits vs. cost
|
||||
|
||||
## Integration Principles
|
||||
|
||||
### 1. **Optional & Non-Intrusive**
|
||||
- Agent Mail is 100% optional
|
||||
- Beads works identically without it (git-only mode)
|
||||
- No breaking changes to existing workflows
|
||||
|
||||
### 2. **Graceful Degradation**
|
||||
- If server unavailable, fall back to git-only sync
|
||||
- No errors, no crashes, just log a warning
|
||||
|
||||
### 3. **Lightweight HTTP Client**
|
||||
- Use standard library HTTP client (no SDK bloat)
|
||||
- Minimal code footprint in beads (<500 LOC)
|
||||
|
||||
### 4. **Configuration via Environment**
|
||||
```bash
|
||||
# Enable Agent Mail (optional)
|
||||
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||
export BEADS_AGENT_MAIL_TOKEN=<bearer-token>
|
||||
export BEADS_AGENT_NAME=assistant-alpha
|
||||
|
||||
# Disabled by default (git-only mode)
|
||||
bd ready # Works without Agent Mail
|
||||
```
|
||||
|
||||
## Proof of Concept Results
|
||||
|
||||
### File Reservation Testing (bd-6hji) ✅
|
||||
- **Test:** Two agents (BrownBear, ChartreuseHill) race to claim bd-123
|
||||
- **Result:** First agent gets reservation, second gets clear conflict error
|
||||
- **Verdict:** Collision prevention works as expected
|
||||
|
||||
### Latency Benchmarking (bd-htfk) ✅
|
||||
- **Git Sync:** 2000-5000ms (commit + push + pull + import)
|
||||
- **Agent Mail:** <100ms (HTTP send + fetch round-trip)
|
||||
- **Improvement:** 20-50x latency reduction
|
||||
- **Verdict:** Real-time coordination achievable
|
||||
|
||||
### Installation (bd-muls) ✅
|
||||
- **Server:** Runs on port 8765, <50MB memory
|
||||
- **Web UI:** Accessible for human supervision
|
||||
- **Verdict:** Easy to deploy and monitor
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ bd (Beads CLI) │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────────┐ │
|
||||
│ │ Git Sync │ │ Agent Mail │ │
|
||||
│ │ (required) │ │ (optional) │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ - Export │ │ - Reservations │ │
|
||||
│ │ - Import │ │ - Notifications │ │
|
||||
│ │ - Commit │ │ - Status updates│ │
|
||||
│ │ - Push/Pull │ │ │ │
|
||||
│ └─────────────┘ └─────────────────┘ │
|
||||
│ │ │ │
|
||||
└─────────┼──────────────────────┼────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ .beads/ │ │ Agent Mail │
|
||||
│ issues.jsonl │ │ Server │
|
||||
│ (git) │ │ (HTTP) │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
### Coordination Flow (with Agent Mail)
|
||||
|
||||
```
|
||||
Agent A: bd update bd-123 --status in_progress
|
||||
↓
|
||||
├─ Agent Mail: POST /api/reservations (5ms)
|
||||
│ └─ Reserve bd-123 for Agent A
|
||||
├─ Local: Update .beads/beads.db
|
||||
└─ Background: Export to JSONL (30s debounce)
|
||||
|
||||
Agent B: bd update bd-123 --status in_progress
|
||||
↓
|
||||
└─ Agent Mail: POST /api/reservations (5ms)
|
||||
└─ HTTP 409 Conflict: "bd-123 reserved by Agent A"
|
||||
└─ bd exits with clear error
|
||||
|
||||
Total latency: <100ms (vs 2000-5000ms with git-only)
|
||||
```
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Core Integration (bd-wfmw)
|
||||
- [ ] HTTP client wrapper for Agent Mail API
|
||||
- [ ] Reservation check before status updates
|
||||
- [ ] Graceful fallback when server unavailable
|
||||
- [ ] Environment-based configuration
|
||||
|
||||
### Phase 2: Enhanced Features
|
||||
- [ ] Notification system (agent X finished bd-Y)
|
||||
- [ ] Automatic reservation expiry (TTL)
|
||||
- [ ] Multi-project support
|
||||
- [ ] Web dashboard for human supervision
|
||||
|
||||
### Phase 3: Documentation
|
||||
- [ ] Quick start guide
|
||||
- [ ] Multi-agent workflow examples
|
||||
- [ ] Troubleshooting guide
|
||||
|
||||
## Risks & Mitigations
|
||||
|
||||
### Risk 1: Server Dependency
|
||||
**Mitigation:** Graceful degradation to git-only mode. Beads never *requires* Agent Mail.
|
||||
|
||||
### Risk 2: Configuration Complexity
|
||||
**Mitigation:** Zero config required for single-agent workflows. Environment variables for multi-agent setups.
|
||||
|
||||
### Risk 3: Upstream Changes
|
||||
**Mitigation:** Use HTTP API directly (not SDK). Minimal surface area for breaking changes.
|
||||
|
||||
### Risk 4: Data Durability
|
||||
**Mitigation:** Git remains the source of truth. Agent Mail is ephemeral coordination state only.
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- ✅ Latency reduction: 20-50x (verified)
|
||||
- ✅ Collision prevention: 100% effective (verified)
|
||||
- 🔲 Git operation reduction: ≥70% (pending bd-nemp)
|
||||
- 🔲 Zero functional regression in git-only mode
|
||||
|
||||
## References
|
||||
|
||||
- [MCP Agent Mail Repository](https://github.com/Dicklesworthstone/mcp_agent_mail)
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
**Proceed with Agent Mail integration** using the optional, non-intrusive approach outlined above. The proof of concept validated the core benefits (latency, collision prevention) while the lightweight HTTP integration minimizes risk and complexity.
|
||||
|
||||
Git-only mode remains the default and fully supported workflow for single-agent scenarios.
|
||||
Reference in New Issue
Block a user