Sidecar Daemon¶
Unified process supervisor, cron scheduler, and message-driven job dispatcher
Entry points¶
work_buddy.sidecar
Details¶
A single long-lived Python process that replaces multiple independent Windows Task Scheduler entries with a unified process supervisor, cron/heartbeat scheduler, and message-driven job dispatcher.
Starting: powershell.exe -Command "cd
Manages its own lifecycle via PID file (data/runtime/sidecar.pid) and state file (data/runtime/sidecar_state.json).
Three subsystems: 1. Process Supervisor — starts and monitors child services. Health-checks every 30s, restarts crashed services with exponential backoff, gives up after 5 crashes. 2. Cron/Heartbeat Scheduler — loads job .md files from sidecar_jobs/ and fires them on their cron schedule. Supports exclusion windows (quiet hours) and hot-reloads config+jobs every 30s. 3. Message-to-Job Dispatch — polls messaging service for pending messages addressed to work-buddy. Classifies each message and executes automatically.
Job file format: .md files in sidecar_jobs/ with YAML frontmatter (schedule, recurring, type, capability/params, enabled, spawn_mode).
Job types: capability (calls registered MCP gateway capability directly), workflow (triggers registered workflow), prompt (freeform text — spawns claude -p agent session, consent-gated).
Agent spawn modes for prompt jobs: headless_ephemeral (default, --print --no-session-persistence), headless_persistent (--print only, registered in data/runtime/agent_registry.json), interactive_persistent (deferred).
Remote sessions (work_buddy/remote_session.py): remote_session_begin launches a visible Claude Code terminal session with --remote-control. Consent-gated. Primary use case: Remote Control from phone.
Cron syntax: standard 5-field cron in the timezone set in config.yaml (default: America/New_York).
Config (sidecar: section in config.yaml): health_check_interval, max_service_crashes, restart_backoff_base, services (with module/port/enabled per service), jobs_dir, heartbeat, message_poll_interval.
Observability: Writes data/runtime/sidecar_state.json on every tick. Query via sidecar_status or sidecar_jobs capabilities.