Scheduled tasks and routines in Claude Code

Who this is for and what you will be able to do

This guide is for people who want Claude Code to do recurring work without keeping a terminal open, such as checking open pull requests each day or re-running a check some time later. After reading it you will know how cloud scheduled tasks differ from session-scoped /loop, how to create and trigger each kind, and where their limits sit.

Two kinds of scheduling, two places they run

Claude Code offers two ways to schedule work, and they run in different places.

The first is the cloud scheduled task, formerly called a routine. It is a saved configuration with a prompt, one or more repositories, and a set of connectors, packaged once and run automatically. It runs on Anthropic-managed cloud infrastructure, so it keeps working when your laptop is closed^[1]. The feature is in research preview, so its behavior and limits may still change^[1].

The second is /loop, which lives inside the Claude Code session you have open. When the session exits or the terminal closes, it stops^[2].

The minimum intervals differ as well. Cloud tasks run no more often than once an hour, while /loop can go down to one minute^[2]. Use a cloud task for work that must run reliably without your machine, and /loop for keeping an eye on something during a session^[2].

Preparing: account and plan

Scheduled tasks are available on Pro, Max, Ultra, Team, and Enterprise plans. You can create them at claude.ai/code/routines or from the CLI with /schedule^[1].

Creating a cloud task

A task is made of a prompt, repositories, and triggers. The prompt should say what to do. Each run is a full Claude Code cloud session that can run shell commands, use skills, and call the connectors you include. You do not pick a permission mode when you create the task, and new sessions start in auto mode^[1].

Three settings decide what a task can reach: the repositories you select, the cloud environment's network access and variables, and the connectors you include^[1]. Give each one only what the task needs.

Each run clones the selected repositories at its start. Claude writes its changes to branches whose names start with claude/, so if you want pushes elsewhere, say so in the prompt^[1].

From the CLI, /schedule is quicker. A one-off task can be written in plain language:

/schedule tomorrow at 9am, summarize yesterday's merged PRs

Claude turns the phrase into an absolute time and confirms it before saving^[1].

Timing: cron and one-off runs

A recurring task can use a preset frequency or a cron expression. A five-field expression is read in UTC. So 0 9 * * 1-5 means 9:00 on weekdays in UTC, not 9:00 where you are. If an expression starts with a CRON_TZ= prefix, it is read in that time zone instead^[1].

Also watch the top of the hour. A run scheduled exactly for 9:00 can start a few minutes late, so a time such as 9:07 starts closer to the mark. Expressions that run more often than once an hour are rejected^[1].

A one-off task runs once at its timestamp, then switches itself off and is marked Completed^[1].

Three kinds of triggers

A task can carry one or more triggers. The three types are Schedule, API, and GitHub events^[1].

API triggers

An API trigger gives the task its own HTTP endpoint. A POST with the task's bearer token starts a new session and returns that session's URL, so an outside system can start the task when it needs to^[1].

Two details matter. First, the token is shown only once, so store it somewhere safe as soon as it appears. Each task has its own token. Regenerating it makes the old one stop working, and deleting it removes the API trigger^[1].

Second, the request body can include an optional text field carrying run-specific context, such as an alert or a log excerpt. The platform wraps that text in a <routine-fire-payload> block and labels it as untrusted data. The saved prompt has to point at that payload explicitly, for example by telling the task to investigate the alert described in the block. Text sent with Run now in the web interface is wrapped the same way^[1].

During the research preview, the request and response shapes, rate limits, and token behavior can all change^[1].

GitHub triggers

A GitHub trigger starts a new session each time a matching event occurs. Two pull request updates therefore produce two separate sessions. The Claude GitHub App must be installed on the repository first^[1].

The events fall into three groups: pull requests, releases, and issues. For pull requests you can filter by author, title, body, base branch, head branch, labels, draft state, and merged state. The task starts only when every filter condition matches^[1].

Usage limits

Scheduled tasks count against subscription usage in the same way interactive sessions do. They also have hourly caps. Scheduled runs are capped at 100 per hour per account. Run now, API fires, and re-running a one-off task share a cap of 30 per hour per task. API fires have their own cap of 100 per hour per account. None of these caps carries overage billing^[1].

Session-scoped scheduling with /loop

/loop repeats a prompt inside the session you have open. A typical command is /loop 5m check if the deployment finished and tell me what happened, which runs the check every five minutes^[2].

Intervals can use s, m, h, or d. Seconds round up to the next minute, since cron works at one-minute resolution. An interval such as 7m or 90m does not map onto a clean cron step, so it is rounded to the nearest one that does, and Claude tells you which one it chose^[2].

Without an interval, Claude picks the wait itself after each iteration, anywhere from one minute to one hour, based on what it has observed, and prints the delay and its reason^[2].

A bare /loop runs a built-in maintenance prompt. It continues unfinished work, handles the current branch's pull request (review comments, failed CI, and merge conflicts), and runs cleanup passes when nothing else is pending^[2]. To replace that default, write .claude/loop.md for the project or ~/.claude/loop.md for yourself. The project file takes precedence, and anything beyond 25,000 bytes is cut off^[2].

To stop a self-paced loop, press Esc while it waits for its next iteration. A fixed-interval loop such as /loop 5m has to be cancelled by asking Claude, because neither Esc nor Ctrl+C stops it. A loop that nobody cancels ends seven days after it was created^[2].

Limits of session-scoped tasks

These tasks fire only while Claude Code is running and idle. Closing the terminal or ending the session stops them. Backgrounding a session carries /loop tasks into a background session, which keeps running without a terminal^[2].

To avoid many requests hitting the API at the same moment, Claude Code delays recurring runs by up to half the gap to the next run, and never by more than 30 minutes. A task written */5 * * * * is not delayed. A one-shot task set for :00 or :30 can run up to 90 seconds early. A session can hold up to 50 scheduled tasks at once^[2].

When you resume with claude --resume or claude --continue, Claude Code restores tasks created with CronCreate. Expired recurring tasks and one-shot tasks whose time has passed are not restored, and a self-paced /loop has to be started again^[2].

To turn the scheduler off, set CLAUDE_CODE_DISABLE_CRON=1. Then CronCreate and /loop become unavailable, and tasks already scheduled stop firing^[2].

Limits and common problems

• Session loops do not last. Recurring session-scoped tasks expire after seven days, so use a cloud task for anything long-running^[2].
• Cloud times depend on the time zone. A five-field cron is read in UTC, and runs set exactly on the hour may start a few minutes late^[1].
• One-off tasks do not repeat. After a run the task turns itself off, so you must set a new time to run it again^[1].
• A one-shot reminder waits for an idle session. Session-scoped tasks fire only when Claude is idle, so a prompt that comes due mid-response waits for the turn to end^[2].

Next steps

For Desktop scheduled tasks, GitHub Actions schedule triggers, and the full cloud task reference, see the official documentation^[1][2].