27c0c331ac
- bd-1h8: Add --no-daemon hint to compact error messages - bd-8ql: Replace non-existent merge command with actionable guidance - bd-ayw: Add 'When to use daemon mode' decision tree to daemon.md - bd-keb: Add database maintenance section to QUICKSTART.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2.3 KiB
Run a per-project background daemon that manages database connections and syncs with git.
Per-Project Daemon (LSP Model)
Each project runs its own daemon at .beads/bd.sock for complete database isolation.
On Windows this file stores the daemon's loopback TCP endpoint metadata—leave it in place so bd can reconnect.
Why per-project daemons?
- Complete database isolation between projects
- No cross-project pollution or git worktree conflicts
- Simpler mental model: one project = one database = one daemon
- Follows LSP (Language Server Protocol) architecture
Note: Global daemon support was removed in v0.16.0. The --global flag is no longer functional.
When to Use Daemon Mode
✅ You SHOULD use daemon mode if:
- Working in a team with git remote sync
- Want automatic commit/push of issue changes
- Need background auto-sync (5-second debounce)
- Making frequent bd commands (performance benefit from connection pooling)
❌ You DON'T need daemon mode if:
- Solo developer with local-only tracking
- Working in git worktrees (use --no-daemon to avoid conflicts)
- Running one-off commands or scripts
- Debugging database issues (direct mode is simpler)
Local-only users: Direct mode (default without daemon) is perfectly fine. The daemon mainly helps with git sync automation. You can still use bd sync manually when needed.
Performance note: For most operations, the daemon provides minimal performance benefit. The main value is automatic JSONL export (5s debounce) and optional git sync (--auto-commit, --auto-push).
Common Operations
- Start:
bd daemon(auto-starts on firstbdcommand) - Stop:
bd daemon --stop - Status:
bd daemon --status - Health:
bd daemon --health- shows uptime, cache stats, performance metrics - Metrics:
bd daemon --metrics- detailed operational telemetry
Sync Options
- --auto-commit: Automatically commit JSONL changes
- --auto-push: Automatically push commits to remote
- --interval: Sync check interval (default: 5m)
The daemon provides:
- Connection pooling and caching
- Better performance for frequent operations
- Automatic JSONL sync (5-second debounce)
- Optional git sync