Scheduled Tasks

Schedule recurring or one-shot prompts using Claude Code's built-in cron tools.

When to Use

• Poll CI/CD pipeline status at intervals
• Set reminders during long-running work
• Periodic quality checks (lint, test, build)
• Monitor external resources or services
• Recurring data collection or reporting

When NOT to Use a Cron

CronCreate re-runs a prompt at fixed wall-clock intervals. It is the wrong instrument for short waits and live watching — cron polls on a schedule and cannot fire mid-query, so it will not notice an event until its next tick. Reach for these instead:

Use a cron only for genuinely periodic work on a wall-clock cadence. Note that an unbounded Monitor command (tail -f, while true) stays armed until its timeout, so use Bash + run_in_background when one notification is all that is wanted.

Tools

CronCreate

Schedule a recurring or one-shot prompt.

Parameters:

• cron (required) — Standard 5-field cron expression: minute hour day-of-month month day-of-week
• prompt (required) — The prompt to execute at each fire time
• recurring (optional, default: true) — false for one-shot reminders
• durable — accepted but inert. The tool schema states it "has no effect — durable persistence is not available. All jobs are session-only (in-memory, gone when this Claude session ends)." Do not pass it and do not treat it as persistence.

Returns: Job ID for managing the schedule.

CronDelete

Cancel a scheduled job by its ID.

CronList

List all active scheduled jobs in the current session.

Cron Expression Syntax

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *

Common patterns:

• */5 * * * * — Every 5 minutes
• 7 * * * * — Every hour at :07
• 3 9 * * 1-5 — Weekdays at 9:03am
• 57 8 * * * — Daily at ~9am (avoid :00 for load distribution)

One-shot (pinned):

• 30 14 15 4 * — Once at 2:30pm on April 15

Constraints

• Session-only — treat persistence as unavailable: as the live CronCreate schema reports it, jobs live only in this Claude session, nothing is written to disk, and every job is gone when Claude exits. Durable persistence is feature-gated: the durable parameter is real and the CLI ships an implementation behind it, but when the gate is off the schema states plainly that it "has no effect". Read the durable description in the live schema before relying on it — if it says "has no effect", it does. For scheduling that must survive session exit, use RemoteTrigger (see the remote-triggers skill) rather than betting on a gate.
• Idle-only firing: Jobs only fire while the REPL is idle (not mid-query)
• 7-day max: Recurring tasks auto-expire after 7 days — they fire one final time, then are deleted. Tell the user about the 7-day limit when scheduling a recurring job.
• Jitter: Recurring tasks may fire up to 10% of their period late (max 15 min); one-shot tasks landing on :00 or :30 may fire up to 90s early

Patterns

Poll CI Status

CronCreate:
  cron: "*/3 * * * *"
  prompt: "Check the CI status of the current branch with `gh run list --branch $(git branch --show-current) --limit 1` and notify me if it completed or failed"

For a single CI run that is already in flight, prefer Monitor with a poll loop that exits when the run reaches a terminal state — it reports each check as it lands instead of waking the agent every 3 minutes indefinitely.

Periodic Quality Check

CronCreate:
  cron: "7 * * * *"
  prompt: "Run the linter and type checker. If there are new errors since the last check, show them to me"

One-Shot Reminder

CronCreate:
  cron: "30 14 1 4 *"   (pinned to specific date/time)
  prompt: "Remind me to check the deploy status"
  recurring: false

Sleep/Resume for Autonomous Monitoring

Agents can self-suspend and resume without user prompts using combinations of cron and sleep patterns:

Periodic Wake-Check-Sleep

CronCreate:
  cron: "*/10 * * * *"
  prompt: "Check CI status for the current branch. If build failed, alert the user. Otherwise, do nothing."

The agent wakes every 10 minutes, checks status, and goes back to idle. Each wake-up costs one API call.

Surviving a Restart

Not possible with a cron under the current schema — a job is gone the moment Claude exits, and durable reports "has no effect" while its gate is off. Do not promise the user persistence on the strength of that parameter; check the live schema text if it matters. Anything that must outlive the session belongs in RemoteTrigger (remote-triggers skill).

Best Practices

• Avoid :00 and :30 minute marks — pick off-minutes to reduce API load spikes
• Keep prompts focused and actionable — the scheduled prompt runs with full agent context
• Use CronList to audit active jobs before creating new ones
• Clean up with CronDelete when a monitoring task is no longer needed
• For one-shot reminders, always set recurring: false

Related

• /loop skill — Higher-level recurring task wrapper
• /schedule skill — Remote agent triggers (survives session exit)
• experiment-loop skill — Metric-driven optimization with iteration