Skip to content

Session Scheduling with Loop and Cron in Claude Code

Run prompts on a recurring interval or at a specific time using /loop and the cron tools — session-scoped, no external infrastructure required.

Session scheduling lets Claude re-run a prompt automatically within an active session — poll a deployment, babysit a PR, check a long build, or set a one-time reminder. Tasks live in the current conversation; claude --resume or claude --continue restores unexpired ones (recurring within 7 days, one-shots whose fire time hasn't passed). Requires Claude Code v2.1.72 or later. [Source: Scheduled Tasks — Claude Code docs]

/loop — Interactive Recurring Prompts

The /loop bundled skill schedules a recurring prompt. Pass an optional interval and a prompt:

/loop 5m check if the deployment finished and tell me what happened

Claude converts the interval to a cron expression and confirms the cadence and job ID.

Form Example Result
Leading interval /loop 30m check the build Every 30 minutes
Trailing every /loop check the build every 2 hours Every 2 hours
No interval /loop check the build Dynamic — Claude picks a 1-minute to 1-hour delay per iteration

Units: s, m, h, d. Seconds round up to the nearest minute; intervals that don't map cleanly (7m, 90m) round to the nearest cron step. With dynamic intervals, Claude prints the chosen delay and reason each iteration; the Monitor tool often beats polling here by streaming background-script stdout line-by-line. The prompt can invoke another command — /loop 20m /review-pr 1234 re-runs that workflow each fire. Press Esc while a /loop waits to clear the pending wakeup. [Source: Scheduled Tasks — Claude Code docs]

Customize the default prompt with loop.md

A bare /loop runs a built-in maintenance prompt — continue unfinished work, tend to the current branch's PR, then run cleanup passes. Override it with .claude/loop.md (project-level, takes precedence) or ~/.claude/loop.md (user-level). Plain Markdown; write it as if typing the /loop prompt directly. Edits take effect next iteration. Files over 25,000 bytes are truncated. [Source: Scheduled Tasks — Claude Code docs]

Cron Tools — Programmatic Scheduling

Agents and skills use three tools to manage scheduled tasks programmatically:

Tool Purpose
CronCreate Schedule a task — accepts a 5-field cron expression, prompt, and recurrence flag
CronList List all tasks with IDs, schedules, and prompts
CronDelete Cancel a task by its 8-character ID

Standard 5-field expressions (minute hour day-of-month month day-of-week) with wildcards, steps (*/15), ranges (1-5), and comma lists. Day-of-week uses 0 or 7 for Sunday through 6 for Saturday. Extended syntax (L, W, ?, MON, JAN) is not supported. When both day-of-month and day-of-week are constrained, a date matches if either field matches (vixie-cron). Maximum 50 tasks per session. [Source: Scheduled Tasks — Claude Code docs]

One-Time Reminders

Describe it in natural language — Claude schedules a single-fire task that auto-deletes after running:

remind me at 3pm to push the release branch
in 45 minutes, check whether integration tests passed

Execution Semantics

  • Fires between turns — scheduler checks every second, enqueues at low priority; if Claude is mid-response, the task waits for the turn to end
  • Local timezone — 0 9 * * * means 9am wherever Claude Code runs, not UTC
  • Jitter — recurring tasks fire up to 30 minutes after their scheduled time (or half the interval for sub-hourly tasks); one-shots scheduled for :00 or :30 fire up to 90s early. The offset is derived from the task ID (deterministic). Use a minute like 3 9 * * * to skip the one-shot offset
  • 7-day expiry — recurring tasks fire one final time then auto-delete 7 days after creation
  • No catch-up — a fire missed while Claude is busy runs once when idle, not once per missed interval

[Source: Scheduled Tasks — Claude Code docs]

Limitations

  • Session-scoped only — closing the terminal or restarting Claude Code cancels everything
  • One-minute granularity — second-level precision is not available
  • On Bedrock, Vertex AI, and Microsoft Foundry, a prompt with no interval runs on a fixed 10-minute schedule instead of a Claude-chosen dynamic interval, and bare /loop prints the usage message instead of starting the maintenance loop
  • Set CLAUDE_CODE_DISABLE_CRON=1 to disable the scheduler entirely

For scheduling that persists across sessions: Routines (cloud, /schedule in CLI, 1-hour minimum), Desktop Scheduled Tasks, or GitHub Actions with a schedule trigger. To react to events instead of polling, see Channels; to keep working turn after turn until a condition is met, see /goal. [Source: Scheduled Tasks — Claude Code docs]

Example

A skill that monitors a GitHub Actions workflow run and notifies the user when it completes:

/loop 5m check the status of the latest GitHub Actions run on this branch — if it finished, report the result and cancel this loop

Claude creates a recurring cron job that fires every 5 minutes. On each fire, it runs gh run list, checks the status, and — once the run completes — reports the outcome and calls CronDelete to cancel itself.

For programmatic use inside a skill or agent, the equivalent uses CronCreate directly:

CronCreate with expression "*/5 * * * *", prompt "check gh run status and cancel when done", recurring true

Key Takeaways

  • /loop provides quick interactive scheduling; cron tools provide programmatic control for agents and skills
  • Tasks are session-scoped; recurring tasks expire 7 days after creation — they are not persistent infrastructure
  • For durable scheduling across restarts, reach for Routines (cloud) or Desktop scheduled tasks, or a GitHub Actions schedule trigger
  • Use one-time reminders via natural language for deferred checks without recurring overhead
Last reviewed: 2026-05-27 Applies to: claude-code@2.x
Feedback