carlos

home · docs · schedule

guides · schedule

Set it once, forget it.

carlos's daemon fires scheduled runs. Five-field cron plus a seven-form English grammar. Each schedule binds to a frame; the per-fire context loads that frame's provider override, vault subtree, and capabilities.

How to schedule

shell 
carlos schedule add "every weekday at 9am tell me yesterday's PRs"
carlos schedule add -f research "daily at 7am summarize hn front page"
carlos schedule list
carlos schedule rm <id>

Or from the TUI composer:

TUI 
/schedule list
/schedule add <natural-language expression>
/schedule rm <id>

Grammar

Two surfaces accepted; both lower to the same internal cron shape.

Five-field cron

cron 
m h dom mon dow      # standard cron, UTC by default; local-tz via config

Natural language (seven forms)

The parser at internal/schedule/parse.go accepts a small English grammar:

Each form lowers to the five-field shape; carlos schedule list shows both representations side by side.

Per-frame fires

Schedules carry a frame: field (Phase F-14). Daemon-side per-fire plumbing (73905ac) resolves the right provider via frame.ResolveProvider before each run. The -f <frame> flag on carlos schedule add populates this field; frame.ResolveProvider honors provider_override if set on the frame.

Notifications + gateway

The system notifier is wired to scheduled-run completion: osascript on macOS, notify-send on Linux, no-op fallback elsewhere. When the gateway is enabled, delivery routes through the same broker that handles approval prompts. See Gateway for the adapter set.

Daemon management

shell 
carlos daemon enable      # install launch agent (launchd / systemd --user)
carlos daemon disable     # uninstall
carlos daemon status      # is it running, when did it last fire
carlos daemon run         # foreground run (for debugging)

The daemon listens on ~/.carlos/daemon.sock (UDS IPC). The onboarding daemon screen surfaces what enabling actually means (Phase O-4 consequence box).

Output

Per-fire artifacts land under ~/.carlos/frames/<name>/digest/. Each run is a sub-agent in its own right; the same Budget and Tracker caps apply. The supervisor view surfaces scheduled runs the same as any other sub-agent, so a runaway nightly job shows up where you already look.

Composing with research

A useful pattern: schedule a recurring /research so the cited report lands automatically. Combined with gateway delivery, you get a digest pushed to your phone every morning.

Recipe

Daily WebGPU digest at 7am, delivered via ntfy to your phone:

shell 
carlos schedule add -f research \
  "daily at 7am research what's new in webgpu"

The fire spawns a /research sub-agent in the research frame; the cited report saves to ~/.carlos/frames/research/research/ and the completion notification routes through whichever gateway channel you wired.

Related

Gateway covers the broker that delivers scheduled-run notifications off-box. Research documents the pipeline that pairs naturally with recurring fires. Frames covers provider_override and the per-frame context each fire loads; slash commands covers /schedule and /daemon.