schedule

Syntax

schedule: <when>

What it does

Part of the config tier — it declares when the loop runs rather than what it does: manual, nightly, on push, or a cron expression. It sits at the top of the file, before any definition, alongside its siblings runner: (which agent executes it), target: (which directory), and notify: (where results go). Together these turn a hand-run loop into an unattended, recurring job.

Reach for schedule: on loops whose value comes from repetition — a nightly dependency audit, a security scan on every push, a weekly link-checker. The keyword only sets the cadence; the loop still needs a real done when check and a thrash guard, because an unattended run has no human watching each cycle. That is the point of pairing it with notify: — the loop reports its outcome to Slack or email so a failed or blocked run surfaces to a person even though nobody launched it by hand. Note the current runtime executes manual and simply parses the other cadences, so today schedule: documents intent and wires the config; treat scheduled cadences as declarative until the runner enforces them, and don't assume a nightly line alone will wake the loop up.

Example

use the audit method
schedule: nightly
notify: slack

schedule: on push
runner: claude
target: services/api

loop "gate the api on every push":
  goal: no high-severity findings in the api service
  done when "semgrep --severity=high services/api" finds nothing
  after 3 tries: stop and warn "scan still failing"

Common mistakes

• Expecting a cadence to fire today. The v1 runtime executes manual and only parses nightly / on push / cron. A schedule: nightly line records intent but won't wake the loop yet — run it by hand or via your own scheduler until the runner enforces cadence.
• Putting it inside a loop body. schedule: is a config-tier line — it belongs at the top of the file, before any loop / pipeline / flow. Indented under a definition it is a parse error.
• Scheduling without a notifier. An unattended run nobody watches needs a notify: so failures reach a human. A silent scheduled loop can fail every night unnoticed.
• No thrash guard on a recurring run. Without after N tries: stop and warn, a scheduled loop that can't reach green can loop and burn tokens with no one at the keyboard. Floor every unattended loop.

Related