Skip to main content

​
Daemon Commands

The dispatch daemon is a background process that automatically assigns ready tasks to idle workers based on priority and dependencies. These commands control the daemon lifecycle and sleep/wake behavior.

​
sf daemon start

Start the dispatch daemon. Usage: 
sf daemon start [options]

​
Options

​
--server
string
default:"http://localhost:3457"
Orchestrator server URL

​
Examples

# Start daemon
sf daemon start

# Start daemon on custom port
sf daemon start --server http://localhost:8080

​
Output

Daemon started
The daemon handles automatic task assignment to idle workers. Tasks are dispatched based on:
  • Priority (P1 before P2, etc.)
  • Dependencies (only ready/unblocked tasks)
  • Agent availability (workers with sessionStatus: 'idle')

​
sf daemon stop

Stop the dispatch daemon. Usage: 
sf daemon stop [options]

​
Options

​
--server
string
default:"http://localhost:3457"
Orchestrator server URL
​
--force
boolean
default:"false"
Skip confirmation prompt

​
Examples

# Stop daemon (with confirmation)
sf daemon stop

# Force stop without prompt
sf daemon stop --force

# Stop daemon on custom server
sf daemon stop --server http://localhost:8080

​
Output

Stopping the daemon will halt all automatic task dispatch. Continue? (y/N): y
Daemon stopped

​
sf daemon status

Show the current status of the dispatch daemon. Usage: 
sf daemon status [options]

​
Options

​
--server
string
default:"http://localhost:3457"
Orchestrator server URL

​
Examples

# Check daemon status
sf daemon status

# Get JSON output
sf daemon status --json

# Check on custom server
sf daemon status --server http://localhost:8080

​
Output

Status:    running
Uptime:    2h 35m 12s
Dispatched: 47 task(s)
Last dispatch: 2026-03-02T15:30:00Z

Dispatch:  ▶ active

​
Rate-Limited Status

When rate-limited, the status shows which executables are limited and when they reset: 
Status:    running
Uptime:    0h 15m 42s
Dispatched: 5 task(s)

Dispatch:  ⏸ paused (rate limited)
Rate-limited executables:
  - /opt/homebrew/bin/claude-code: resets 3:00 AM (in 2h 45m)
  - /usr/local/bin/opencode: resets 3:15 AM (in 3h)
Soonest reset: 3:00 AM (in 2h 45m)

​
sf daemon sleep

Manually pause dispatch until a specified time. Usage: 
sf daemon sleep [options]

​
Options

​
--server
string
default:"http://localhost:3457"
Orchestrator server URL
​
--until
string
default:""
Sleep until a specific time (e.g., "3am", "Feb 22 at 9:30am", "tomorrow at 3pm")
​
--duration
number
default:""
Sleep for a duration in seconds

​
Examples

# Sleep until 3am
sf daemon sleep --until "3am"

# Sleep until a specific date and time
sf daemon sleep --until "Feb 22 at 9:30am"

# Sleep until tomorrow at 3pm
sf daemon sleep --until "tomorrow at 3pm"

# Sleep for 1 hour (3600 seconds)
sf daemon sleep --duration 3600

​
Output

Daemon dispatch paused until 3/3/2026, 3:00:00 AM
When to use sf daemon sleep:This command is a manual escape hatch for when rate limit time parsing fails or produces incorrect results. Normally, the daemon detects rate limits automatically from agent provider error messages. Use this when:
  • Automatic rate limit detection fails
  • You need to manually control dispatch timing
  • You want to prevent dispatch during specific time windows
What happens during sleep:
  • Task dispatch is paused
  • Non-dispatch polls continue (inbox, plan auto-complete, etc.)
  • The daemon remains running in the background

​
sf daemon wake

Immediately resume dispatch, clearing all rate limits and sleep timers. Usage: 
sf daemon wake [options]

​
Options

​
--server
string
default:"http://localhost:3457"
Orchestrator server URL

​
Examples

# Wake the daemon
sf daemon wake

# Wake daemon on custom server
sf daemon wake --server http://localhost:8080

​
Output

Daemon dispatch resumed. Rate limits cleared.
sf daemon wake clears:
  • All rate limit entries (per-executable timers)
  • The manual sleep timer (set via sf daemon sleep)
  • Any other dispatch pause state
The daemon will resume normal task dispatch on the next poll cycle (typically within 10-30 seconds).

​
Common Workflows

​
Start and Monitor Daemon

# Start daemon
sf daemon start

# Monitor status
watch -n 10 'sf daemon status'

​
Handle Rate Limits

# Check status
sf daemon status

# If rate-limited, sleep until reset time
sf daemon sleep --until "3am"

# Or manually wake early
sf daemon wake

​
Stop During Maintenance

# Stop dispatch
sf daemon stop --force

# Do maintenance work
# ...

# Restart dispatch
sf daemon start

​
Rate Limit Handling

The daemon automatically detects rate limits from agent provider error messages and pauses dispatch until the reset time. Supported providers:
  • Claude Code (detects 429 errors, parses reset times)
  • OpenCode (detects rate limit messages)
  • OpenAI Codex (detects 429 responses)
What happens during rate limit:
  1. Agent spawn fails with rate limit error
  2. Daemon parses reset time from error message
  3. Dispatch is paused until reset time
  4. sf daemon status shows rate-limited state
  5. Dispatch automatically resumes after reset
Manual override: If automatic detection fails or you need to adjust timing: 
# Set custom sleep time
sf daemon sleep --until "3:30am"

# Force immediate resume
sf daemon wake

Agent Commands

Register and manage agents that the daemon dispatches to

Task Commands

View tasks that the daemon assigns

Build docs developers (and LLMs) love

Get started for freeTalk to us