---
description: Run background sync daemon
argument-hint: [--stop] [--status] [--health]
---

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 first `bd` command)
- **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