Skip to main content

Daemon Architecture

Beads runs a background daemon for auto-sync and performance.

Overview​

Each workspace gets its own daemon process:

  • Auto-starts on first bd command
  • Handles database ↔ JSONL synchronization
  • Listens on .beads/bd.sock (Unix) or .beads/bd.pipe (Windows)
  • Version checking prevents mismatches after upgrades

How It Works​

CLI Command
    ↓
RPC to Daemon
    ↓
Daemon executes
    ↓
Auto-sync to JSONL (5s debounce)

Without daemon, commands access the database directly (slower, no auto-sync).

Managing Daemons​

# List all running daemons
bd daemons list
bd daemons list --json

# Check health and version mismatches
bd daemons health
bd daemons health --json

# View daemon logs
bd daemons logs . -n 100

# Restart all daemons
bd daemons killall
bd daemons killall --json

Daemon Info​

bd info

Shows:

  • Daemon status (running/stopped)
  • Daemon version vs CLI version
  • Socket location
  • Auto-sync status

Disabling Daemon​

Use --no-daemon flag to bypass the daemon:

bd --no-daemon ready
bd --no-daemon list

When to disable:

  • Git worktrees (required)
  • CI/CD pipelines
  • Resource-constrained environments
  • Debugging sync issues

Event-Driven Mode (Experimental)​

Event-driven mode replaces 5-second polling with instant reactivity:

# Enable globally
export BEADS_DAEMON_MODE=events
bd daemons killall  # Restart to apply

Benefits:

  • Less than 500ms latency (vs 5s polling)
  • ~60% less CPU usage
  • Instant sync after changes

How to verify:

bd info | grep "daemon mode"

Troubleshooting​

Daemon not starting​

# Check if socket exists
ls -la .beads/bd.sock

# Try direct mode
bd --no-daemon info

# Restart daemon
bd daemons killall
bd info

Version mismatch​

After upgrading bd:

bd daemons killall
bd info  # Should show matching versions

Sync not happening​

# Force sync
bd sync

# Check daemon logs
bd daemons logs . -n 50

# Verify git status
git status .beads/

Port/socket conflicts​

# Kill all daemons
bd daemons killall

# Remove stale socket
rm -f .beads/bd.sock

# Restart
bd info

Configuration​

Daemon behavior can be configured:

# Set sync debounce interval
bd config set daemon.sync_interval 10s

# Disable auto-start
bd config set daemon.auto_start false

# Set log level
bd config set daemon.log_level debug

See Configuration for all options.