Plain text · sha256 0ad661417250
The description, line by line
36 lines Line numbers are v2.1.269 on the left and this capture on the right.
1
1
Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders.
2
2
3
3
Uses standard 5-field cron in the user's local timezone: minute hour day-of-month month day-of-week. "0 9 * * *" means 9am local — no timezone conversion needed.
4
4
5
5
## One-shot tasks (recurring: false)
6
6
7
7
For "remind me at X" or "at <time>, do Y" requests — fire once then auto-delete.
8
8
Pin minute/hour/day-of-month/month to specific values:
9
9
"remind me at 2:30pm today to check the deploy" → cron: "30 14 <today_dom> <today_month> *", recurring: false
10
10
"tomorrow morning, run the smoke test" → cron: "57 8 <tomorrow_dom> <tomorrow_month> *", recurring: false
11
11
12
12
## Recurring jobs (recurring: true, the default)
13
13
14
14
For "every N minutes" / "every hour" / "weekdays at 9am" requests:
15
15
"*/5 * * * *" (every 5 min), "0 * * * *" (hourly), "0 9 * * 1-5" (weekdays at 9am local)
16
16
17
17
## Avoid the :00 and :30 minute marks when the task allows it
18
18
19
19
Every user who asks for "9am" gets `0 9`, and every user who asks for "hourly" gets `0 *` — which means requests from across the planet land on the API at the same instant. When the user's request is approximate, pick a minute that is NOT 0 or 30:
20
20
"every morning around 9" → "57 8 * * *" or "3 9 * * *" (not "0 9 * * *")
21
21
"hourly" → "7 * * * *" (not "0 * * * *")
22
22
"in an hour or so, remind me to..." → pick whatever minute you land on, don't round
23
23
24
24
Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.
25
25
26
26
## Durability
27
27
28
28
By default (durable: false) the job lives only in this Claude session — nothing is written to disk, and the job is gone when Claude exits. Pass durable: true to write to .claude/scheduled_tasks.json so the job survives restarts. Only use durable: true when the user explicitly asks for the task to persist ("keep doing this every day", "set this up permanently"). Most "remind me in 5 minutes" / "check back in an hour" requests should stay session-only.
29
29
30
30
## Runtime behavior
31
31
32
32
Jobs only fire while the REPL is idle (not mid-query). Durable jobs persist to .claude/scheduled_tasks.json and survive session restarts — on next launch they resume automatically. One-shot durable tasks that were missed while the REPL was closed are surfaced for catch-up. Session-only jobs die with the process. The scheduler adds a small deterministic jitter on top of whatever you pick: recurring tasks fire up to 10% of their period late (max 15 min); one-shot tasks landing on :00 or :30 fire up to 90 s early. Picking an off-minute is still the bigger lever.
33
33
34
34
Recurring tasks auto-expire after 7 days — they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the 7-day limit when scheduling recurring jobs.
35
35
36
36
Returns a job ID you can pass to CronDelete.
What it accepts
4 parameters The JSON parameter schema sent beside this description, 1,052 characters of it. Name, type, then whether the client marked it required.cron
string
required
Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "*/5 * * * *" = every 5 minutes, "30 14 28 2 *" = Feb 28 at 2:30pm local once).
durable
boolean
optional
true = persist to .claude/scheduled_tasks.json and survive restarts. false (default) = in-memory only, dies when this Claude session ends. Use true only when the user asks the task to survive across sessions.
prompt
string
required
The prompt to enqueue at each fire time.
recurring
boolean
optional
true (default) = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete. Use false for "remind me at X" one-shot requests with pinned minute/hour/dom/month.
sha256 66e88456428e · the schema as the client sent it:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"cron": {
"description": "Standard 5-field cron expression in local time: \"M H DoM Mon DoW\" (e.g. \"*/5 * * * *\" = every 5 minutes, \"30 14 28 2 *\" = Feb 28 at 2:30pm local once).",
"type": "string"
},
"durable": {
"description": "true = persist to .claude/scheduled_tasks.json and survive restarts. false (default) = in-memory only, dies when this Claude session ends. Use true only when the user asks the task to survive across sessions.",
"type": "boolean"
},
"prompt": {
"description": "The prompt to enqueue at each fire time.",
"type": "string"
},
"recurring": {
"description": "true (default) = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete. Use false for \"remind me at X\" one-shot requests with pinned minute/hour/dom/month.",
"type": "boolean"
}
},
"required": [
"cron",
"prompt"
],
"type": "object"
}