pfangueiro 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:
| Need | Instrument |
|---|---|
| One notification when a condition becomes true ("tell me when the build finishes", "when the server is ready") | Bash with run_in_background, running a command that exits once the condition holds: until grep -q "Ready in" dev.log; do sleep 0.5; done |
| One per occurrence, as it happens ("tell me every time an ERROR line appears") | Monitor — each stdout line of a long-running script becomes an event, streamed in real time |
| One per occurrence until a known end (emit each CI step, stop when the run completes) | Monitor with a command that emits lines and then exits |
| Waiting a few seconds or minutes inside a task | Monitor with an until-loop — foreground sleep is blocked in Bash |
| Anything that must outlive the session | RemoteTrigger (remote-triggers skill) |
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-weekprompt(required) — The prompt to execute at each fire timerecurring(optional, default: true) —falsefor one-shot remindersdurable— 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 minutes7 * * * *— Every hour at :073 9 * * 1-5— Weekdays at 9:03am57 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
CronCreateschema 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: thedurableparameter 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 thedurabledescription in the live schema before relying on it — if it says "has no effect", it does. For scheduling that must survive session exit, useRemoteTrigger(see theremote-triggersskill) 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
:00or:30may 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
:00and:30minute marks — pick off-minutes to reduce API load spikes - Keep prompts focused and actionable — the scheduled prompt runs with full agent context
- Use
CronListto audit active jobs before creating new ones - Clean up with
CronDeletewhen a monitoring task is no longer needed - For one-shot reminders, always set
recurring: false
Related
/loopskill — Higher-level recurring task wrapper/scheduleskill — Remote agent triggers (survives session exit)experiment-loopskill — Metric-driven optimization with iteration