From 4e38626361d96afb1712a8604d6cebe6643e274b Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 26 Oct 2025 19:03:03 -0700 Subject: [PATCH] Document bd daemons commands (bd-150) Amp-Thread-ID: https://ampcode.com/threads/T-f1cff202-188b-4850-a909-c2750d24ad22 Co-authored-by: Amp --- AGENTS.md | 40 ++++++++- README.md | 31 +++++++ commands/daemons.md | 215 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 285 insertions(+), 1 deletion(-) create mode 100644 commands/daemons.md diff --git a/AGENTS.md b/AGENTS.md index 499dddae..78dc5260 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,8 +99,10 @@ SQLite Databases (complete isolation) **Version Management:** bd automatically handles daemon version mismatches (v0.16.0+): - When you upgrade bd, old daemons are automatically detected and restarted - Version compatibility is checked on every connection -- No manual `bd daemon --stop` required after upgrades +- No manual intervention required after upgrades - Works transparently with MCP server and CLI +- Use `bd daemons health` to check for version mismatches +- Use `bd daemons killall` to force-restart all daemons if needed **Alternative (not recommended): Multiple MCP Server Instances** If you must use separate MCP servers: @@ -198,6 +200,42 @@ bd merge --into --json # Consolidate duplicates bd merge bd-42 bd-43 --into bd-41 --dry-run # Preview merge ``` +### Managing Daemons + +bd runs a background daemon per workspace for auto-sync and RPC operations. Use `bd daemons` to manage multiple daemons: + +```bash +# List all running daemons +bd daemons list --json + +# Check health (version mismatches, stale sockets) +bd daemons health --json + +# Stop a specific daemon +bd daemons stop /path/to/workspace --json +bd daemons stop 12345 --json # By PID + +# View daemon logs +bd daemons logs /path/to/workspace -n 100 +bd daemons logs 12345 -f # Follow mode + +# Stop all daemons +bd daemons killall --json +bd daemons killall --force --json # Force kill if graceful fails +``` + +**When to use:** +- **After upgrading bd**: Run `bd daemons health` to check for version mismatches, then `bd daemons killall` to restart all daemons with the new version +- **Debugging**: Use `bd daemons logs ` to view daemon logs +- **Cleanup**: `bd daemons list` auto-removes stale sockets + +**Troubleshooting:** +- **Stale sockets**: `bd daemons list` auto-cleans them +- **Version mismatch**: `bd daemons killall` then let daemons auto-start on next command +- **Daemon won't stop**: `bd daemons killall --force` + +See [commands/daemons.md](commands/daemons.md) for detailed documentation. + ### Workflow 1. **Check for ready work**: Run `bd ready` to see what's unblocked diff --git a/README.md b/README.md index e585c069..5bc4d3ec 100644 --- a/README.md +++ b/README.md @@ -396,6 +396,37 @@ bd sync **Note:** Auto-sync is enabled by default. Manual export/import is rarely needed. +### Managing Daemons + +bd runs a background daemon per workspace for auto-sync and RPC operations. Use `bd daemons` to manage multiple daemons: + +```bash +# List all running daemons +bd daemons list + +# Check health (version mismatches, stale sockets) +bd daemons health + +# Stop a specific daemon +bd daemons stop /path/to/workspace +bd daemons stop 12345 # By PID + +# View daemon logs +bd daemons logs /path/to/workspace -n 100 +bd daemons logs 12345 -f # Follow mode + +# Stop all daemons +bd daemons killall +bd daemons killall --force # Force kill if graceful fails +``` + +**Common use cases:** +- **After upgrading bd**: Run `bd daemons health` to check for version mismatches, then `bd daemons killall` to restart all daemons with the new version +- **Debugging**: Use `bd daemons logs ` to view daemon logs +- **Cleanup**: `bd daemons list` auto-removes stale sockets + +See [commands/daemons.md](commands/daemons.md) for complete documentation. + ## Examples Check out the **[examples/](examples/)** directory for: diff --git a/commands/daemons.md b/commands/daemons.md new file mode 100644 index 00000000..e0ddad1a --- /dev/null +++ b/commands/daemons.md @@ -0,0 +1,215 @@ +# bd daemons - Daemon Management + +Manage bd daemon processes across all repositories and worktrees. + +## Synopsis + +```bash +bd daemons [flags] +``` + +## Description + +The `bd daemons` command provides tools for discovering, monitoring, and managing multiple bd daemon processes across your system. This is useful when working with multiple repositories or git worktrees. + +## Subcommands + +### list + +List all running bd daemons with metadata. + +```bash +bd daemons list [--search DIRS] [--json] [--no-cleanup] +``` + +**Flags:** +- `--search` - Directories to search for daemons (default: home, /tmp, cwd) +- `--json` - Output in JSON format +- `--no-cleanup` - Skip auto-cleanup of stale sockets + +**Example:** +```bash +bd daemons list +bd daemons list --search /Users/me/projects --json +``` + +### health + +Check health of all bd daemons and report issues. + +```bash +bd daemons health [--search DIRS] [--json] +``` + +Reports: +- Stale sockets (dead processes) +- Version mismatches between daemon and CLI +- Unresponsive daemons + +**Flags:** +- `--search` - Directories to search for daemons +- `--json` - Output in JSON format + +**Example:** +```bash +bd daemons health +bd daemons health --json +``` + +### stop + +Stop a specific daemon gracefully. + +```bash +bd daemons stop [--json] +``` + +**Arguments:** +- `` - Workspace path or PID of daemon to stop + +**Flags:** +- `--json` - Output in JSON format + +**Example:** +```bash +bd daemons stop /Users/me/projects/myapp +bd daemons stop 12345 +bd daemons stop /Users/me/projects/myapp --json +``` + +### logs + +View logs for a specific daemon. + +```bash +bd daemons logs [-f] [-n LINES] [--json] +``` + +**Arguments:** +- `` - Workspace path or PID of daemon + +**Flags:** +- `-f, --follow` - Follow log output (like tail -f) +- `-n, --lines INT` - Number of lines to show from end (default: 50) +- `--json` - Output in JSON format + +**Example:** +```bash +bd daemons logs /Users/me/projects/myapp +bd daemons logs 12345 -n 100 +bd daemons logs /Users/me/projects/myapp -f +bd daemons logs 12345 --json +``` + +### killall + +Stop all running bd daemons. + +```bash +bd daemons killall [--search DIRS] [--force] [--json] +``` + +Uses escalating shutdown strategy: +1. RPC shutdown (2 second timeout) +2. SIGTERM (3 second timeout) +3. SIGKILL (1 second timeout) + +**Flags:** +- `--search` - Directories to search for daemons +- `--force` - Use SIGKILL immediately if graceful shutdown fails +- `--json` - Output in JSON format + +**Example:** +```bash +bd daemons killall +bd daemons killall --force +bd daemons killall --json +``` + +## Common Use Cases + +### Version Upgrade + +After upgrading bd, restart all daemons to use the new version: + +```bash +bd daemons health # Check for version mismatches +bd daemons killall # Stop all old daemons +# Daemons will auto-start with new version on next bd command +``` + +### Debugging + +Check daemon status and view logs: + +```bash +bd daemons list +bd daemons health +bd daemons logs /path/to/workspace -n 100 +``` + +### Cleanup + +Remove stale daemon sockets: + +```bash +bd daemons list # Auto-cleanup happens by default +bd daemons list --no-cleanup # Skip cleanup +``` + +### Multi-Workspace Management + +Discover daemons in specific directories: + +```bash +bd daemons list --search /Users/me/projects +bd daemons health --search /Users/me/work +``` + +## Troubleshooting + +### Stale Sockets + +If you see stale sockets (dead process but socket file exists): + +```bash +bd daemons list # Auto-cleanup removes stale sockets +``` + +### Version Mismatch + +If daemon version != CLI version: + +```bash +bd daemons health # Identify mismatched daemons +bd daemons killall # Stop all daemons +# Next bd command will auto-start new version +``` + +### Daemon Won't Stop + +If graceful shutdown fails: + +```bash +bd daemons killall --force # Force kill with SIGKILL +``` + +### Can't Find Daemon + +If daemon isn't discovered: + +```bash +bd daemons list --search /path/to/workspace +``` + +Or check the socket manually: + +```bash +ls -la /path/to/workspace/.beads/bd.sock +``` + +## See Also + +- [bd daemon](daemon.md) - Start a daemon manually +- [AGENTS.md](../AGENTS.md) - Agent workflow guide +- [README.md](../README.md) - Main documentation