Schedule

/schedule — Task Scheduling

Orientation

Use when: scheduling a recurring or one-off remote agent run (cron-style, outside the current session). Don't use when: repeating work within the current session (use /loop); continuous unattended campaigns (use /daemon).

Default execution path (READ FIRST)

/schedule add does NOT call CronCreate by default. It shells out to node scripts/local-schedule.js which installs a native OS entry (Windows Task Scheduler or Unix cron). Only pass --remote to use Anthropic's routine system, and only after explicit user confirmation.

Why: CronCreate counts against the account-wide 15 routine runs / 24h cap; every fire of the scheduled task counts. See docs/ROUTINE-QUOTA.md.

Default flow — /schedule add "<expr>" "<command>" (no --remote)

Run:

node scripts/local-schedule.js add "<expr>" "<command>" --confirm

Before running, show the cadence, project, prompt and persistence and obtain approval to create the OS task. Normal Claude permissions remain enabled. Do not add a bypass flag to make unattended execution succeed.

Then report the returned ID and the removal command. This survives session end, machine reboot, and consumes zero routine quota. Use /schedule list and /schedule remove {id} (which also shell out to local-schedule.js) by default. Remove tasks before uninstalling. New jobs require their .citadel/schedules/<id>.json record; deleting it disables execution but leaves an inert OS entry. Existing jobs retain their old bypass flags until explicitly removed and recreated. See runner safety and migration.

Codex automation lane

When running in Codex and the user wants the schedule to survive the current terminal session, create a Codex Automation plan instead of a local OS entry:

node scripts/codex-automation.js plan --type schedule --cadence "<expr>" --command "<command>" --write

Give the returned prompt to the Codex app automation surface and keep the generated .planning/codex-automations/{id}.json as the durable Citadel record.

If .planning/ does not exist, create it before writing automation state.

Opt-in routine flow — /schedule add --remote ...

Only when --remote is explicitly passed:

1. Confirm: "This will use CronCreate, which counts against your 15 routine runs / 24h quota and is cleared at session end. Continue? (y/N)"
2. On confirmation, run the CronCreate-based flow documented below.

The rest of the protocol documents the full CronCreate flow for reference and for --remote invocations.

When to Route Here

• "run pr-watch every hour"
• "check my PRs automatically"
• "schedule a thing"
• "remind me to run tests every 30 minutes"
• "set up a recurring task"
• "list my scheduled tasks"
• "cancel the PR check"
• Any mention of "schedule", "recurring", "every N minutes/hours", "cron"

Protocol

/schedule list

List all currently scheduled tasks using CronList.

Output format:

Active schedules (N):
  [id] {description} — {cron expression} — next run: {time}

No schedules active.

If CronList is not available: output a helpful error (see Fringe Cases).

/schedule add "{description}" {/skill-or-command}

Create a recurring task.

Steps:

1. Parse the user's description to extract:
   • Natural language interval: "every 30 minutes", "hourly", "every day at 9am"
   • The skill or command to run: /pr-watch, /do status, etc.
2. Convert natural language to a cron expression (see Conversion Table below)
3. Confirm with user: "I'll run {command} {natural-language-interval} (cron: {expression}). OK?"
4. If confirmed: call CronCreate with the expression and command
5. Output: "Scheduled. ID: {id}. Use /schedule remove {id} to cancel."

Cron Expression Conversion Table:

If the user provides a raw cron expression directly, use it as-is without converting. Validate it has 5 fields before accepting.

/schedule remove {id}

Remove a scheduled task by ID using CronDelete.

If the user doesn't know the ID: run /schedule list first, show the list, and ask which one to remove.

Output: "Removed schedule {id} ({description})."

/schedule status

Show all active schedules and their next run times. Equivalent to /schedule list with additional context about what each task does and when it last ran (if available).