Run the built-in maintenance prompt

When you omit the prompt, Claude uses a built-in maintenance prompt instead of one you supply. On each iteration it works through the following, in order:

• continue any unfinished work from the conversation
• tend to the current branch's pull request: review comments, failed CI runs, merge conflicts
• run cleanup passes such as bug hunts or simplification when nothing else is pending

Claude does not start new initiatives outside that scope, and irreversible actions such as pushing or deleting only proceed when they continue something the transcript already authorized.

/loop

A bare /loop runs this prompt at a dynamically chosen interval. Add an interval, for example /loop 15m, to run it on a fixed schedule instead. To replace the built-in prompt with your own default, see Customize the default prompt with loop.md.

Customize the default prompt with loop.md

Create a loop.md file to replace the built-in maintenance prompt with your own instructions. It defines a single default prompt for bare /loop, not a list of separate scheduled tasks, and Claude Code ignores it whenever you supply a prompt on the command line. To schedule additional prompts alongside it, use /loop <prompt> or ask Claude directly.

Claude looks for the file in two locations and uses the first one it finds.

The file is plain Markdown with no required structure. Write it as if you were typing the /loop prompt directly. The following example keeps a release branch healthy:

Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.

Edits to loop.md take effect on the next iteration, so you can refine the instructions while a loop is running. When no loop.md exists in either location, the loop falls back to the built-in maintenance prompt. Keep the file concise: content beyond 25,000 bytes is truncated.

Stop a loop

To stop a self-paced /loop while it is waiting for the next iteration, press Esc. This clears the pending wakeup so the loop does not fire again. Tasks you scheduled by asking Claude directly are not affected by Esc and stay in place until you delete them.

In self-paced mode, Claude can also end the loop on its own once the task is complete. Claude calls the ScheduleWakeup tool with stop: true, which cancels the pending wakeup immediately. If an iteration ends without either rescheduling or stopping, Claude Code schedules one fallback wakeup about 20 minutes later and ends the loop when that iteration doesn't reschedule either.

Loops on a fixed interval keep running until you cancel them like any other scheduled task or seven days elapse.

Set a one-time reminder

For one-shot reminders, describe what you want in natural language instead of using /loop. Claude schedules a single-fire task that deletes itself after running.

remind me at 3pm to push the release branch

in 45 minutes, check whether the integration tests passed

Claude pins the fire time to a specific minute and hour using a cron expression and confirms when it will fire.

Manage scheduled tasks

Ask Claude in natural language to list or cancel tasks, or reference the underlying tools directly.

what scheduled tasks do I have?

cancel the deploy check job

These are the underlying tools Claude uses:

Each scheduled task has an 8-character ID you can pass to CronDelete. A session can hold up to 50 scheduled tasks at once.

How scheduled tasks run

The scheduler checks every second for due tasks and enqueues them at low priority. A scheduled prompt fires between your turns, not while Claude is mid-response. If Claude is busy when a task comes due, the prompt waits until the current turn ends.

All times are interpreted in your local timezone. A cron expression like 0 9 * * * means 9am wherever you're running Claude Code, not UTC.

Jitter

A scheduled task can run at a different time than its schedule says. If every session's tasks ran exactly on schedule, many of them would call the API at the same moment, so Claude Code shifts each task's run time. Recurring tasks run late, and one-shot tasks scheduled on the hour or half hour run a little early.

How late a recurring task runs

When you create a recurring task, Claude Code gives it a fixed delay and adds that delay to every run. The delay is worked out from the task's ID, so the same task runs the same number of minutes late each time, including when the session is idle and nothing else is running.

Tasks that run more often get shorter delays, and 30 minutes is the longest delay a task can get. These are the delay ranges for some common schedules:

For example, 7,37 * * * * schedules a task for :07 and :37, which are 30 minutes apart, so its delay is somewhere between 0 and 15 minutes. If this task's delay is 14 minutes, it runs at :21 and :51 every hour. Changing the schedule to a different minute moves the run time, and a delay is still added on top.

When a one-shot task runs early

A one-shot task scheduled for :00 or :30 runs up to 90 seconds early. Claude Code doesn't shift a one-shot task scheduled for any other minute, so when the timing matters, schedule it off the hour and half hour: 3 9 * * * instead of 0 9 * * *.

Seven-day expiry

Recurring tasks automatically expire 7 days after creation. The task fires one final time, then deletes itself. This bounds how long a forgotten loop can run. If you need a recurring task to last longer, cancel and recreate it before it expires, or use Routines or Desktop scheduled tasks for durable scheduling.

Cron expression reference

CronCreate accepts standard 5-field cron expressions: minute hour day-of-month month day-of-week. All fields support wildcards (*), single values (5), steps (*/15), ranges (1-5), and comma-separated lists (1,15,30).

Day-of-week uses 0 or 7 for Sunday through 6 for Saturday. Extended syntax like L, W, ?, and name aliases such as MON or JAN is not supported.

When both day-of-month and day-of-week are constrained, a date matches if either field matches. This follows standard vixie-cron semantics.

Disable scheduled tasks

Set CLAUDE_CODE_DISABLE_CRON=1 in your environment to disable the scheduler entirely. The cron tools and /loop become unavailable, and any already-scheduled tasks stop firing. See Environment variables for the full list of disable flags.

Limitations

Session-scoped scheduling has inherent constraints:

• Tasks only fire while Claude Code is running and idle. Closing the terminal or letting the session exit stops them firing. Backgrounding the session carries /loop tasks over to a background session, which keeps running without a terminal.
• No catch-up for missed fires. If a task's scheduled time passes while Claude is busy on a long-running request, it fires once when Claude becomes idle, not once per missed interval.
• When you resume a session with claude --resume or claude --continue, Claude Code restores the tasks scheduled with CronCreate, except recurring tasks that have expired and one-shot tasks whose scheduled time has passed. A self-paced /loop isn't restored, so run /loop again to restart it. Background Bash and monitor tasks are never restored on resume.
• With feature-flag fetching off, Claude Code stores a task you asked to keep across sessions in the project's .claude/scheduled_tasks.json file. When the .claude directory or that file is a symlink, Claude Code returns an error instead of scheduling the task. A saved task runs only in the project folder where you created it. If you copy the file into another folder, such as a new worktree, sessions there list the copied tasks but don't run them, so create the task again in that folder.

For cron-driven automation that needs to run unattended:

• Routines: run in the cloud on a schedule, via API call, or on GitHub events
• GitHub Actions: use a schedule trigger in CI
• Desktop scheduled tasks: run locally on your machine