Source: Anthropic official docs — Scheduled tasks; Desktop/Cowork scheduled tasks (2026-10-28): raw/Claude_Cowork_Just_Became_10x_Better_Scheduled_Tasks.md and raw/CLAUDE_COWORK_FULL_COURSE_2+_Hours.md (Ben AI) Type: Product Feature Product: Claude Code Requires: Claude Code v2.1.72 or later

Session-scoped scheduling for Claude Code: re-run a prompt automatically on an interval (poll a deploy, babysit a PR, watch a build), or set a one-time reminder. Tasks live inside the current conversation and stop when you start a new one. Unlike Routines (cloud, durable) or Desktop scheduled tasks (machine-resident, durable), /loop is the lightweight option for inside an open session. To keep the session working turn after turn until a condition is met rather than on a fixed schedule, see the goal` command (Week 20, v2.1.139) — /goal is goal-convergent (Claude decides when done), while /loop is schedule-driven.

Three scheduling options compared

Cloud RoutinesDesktop scheduled tasks/loop (this article)
Runs onAnthropic cloudYour machineYour machine
Requires machine onNoYesYes
Requires open sessionNoNoYes
Persistent across restartsYesYesRestored on --resume if unexpired
Local file accessNoYesYes
MCP serversPer-taskConfig files + connectorsInherits from session
Permission promptsNone (autonomous)ConfigurableInherits from session
Customizable scheduleVia /scheduleYesYes
Minimum interval1 hour1 minute1 minute

/loop usage

Alias: /proactive is an alias for /loop as of Week 16 (v2.1.105). Both forms work identically.

FormExampleBehavior
Interval + prompt/loop 5m check the deployRuns on a fixed cron schedule
Prompt only/loop check the deployClaude picks an interval (1m–1h) per iteration
Interval only / nothing/loop or /loop 15mRuns the built-in maintenance prompt or loop.md

You can also pass another slash command as the prompt: /loop 20m /review-pr 1234. As of v2.1.196, a scheduled fire only runs skills that Claude is allowed to invoke on its own — built-in commands (/permissions, /model, /clear), skills marked disable-model-invocation: true, skills withheld by a skillOverrides setting or Skill deny rule, and MCP prompts (e.g. /mcp__github__list_prs) all reach Claude as plain text instead of executing. Skills an MCP server exposes via the skills primitive still run.

Fixed interval

Supplied intervals can lead (30m do X) or trail (do X every 2 hours) the prompt. Units: s, m, h, d. Seconds round up to the nearest minute (cron has 1-minute granularity). Intervals like 7m or 90m are rounded to the nearest clean cron step and Claude tells you what was picked.

Claude-paced (dynamic) interval

When you omit the interval, Claude chooses one between 1 minute and 1 hour after each iteration based on what it observed: short waits while a build is finishing, longer when nothing is pending. The chosen delay and reasoning print at the end of each iteration. Claude may use the Monitor tool (built-in since v2.1.98, Week 15) for these — a background watcher that streams events into the conversation as new transcript messages, often more token-efficient than re-running prompts. With Monitor, /loop check CI on my PR can stop polling entirely and just react to events as they happen.

Bedrock / Vertex AI / Microsoft Foundry: prior to v2.1.248, prompt with no interval ran on a fixed 10-minute schedule. As of v2.1.248, self-paced dynamic mode is fully available on all providers. (ai-research/claude-code-release-v2-1-248.md; ai-research/claude-code-docs-changelog-2026-08-28.md.)

Built-in maintenance prompt

Bare /loop runs Claude through, in order:

  • continue any unfinished work from the conversation,
  • tend to the current branch’s PR (review comments, failed CI, merge conflicts),
  • run cleanup passes (bug hunts, simplification) when nothing else is pending.

Irreversible actions (push, delete) only proceed when they continue something the transcript already authorized.

Bedrock / Vertex AI / Microsoft Foundry: before v2.1.248, /loop with no prompt printed usage instead of running the maintenance loop. As of v2.1.248 (2026-08-27) the maintenance loop runs on all providers: “/loop self-paced dynamic mode and the no-prompt autonomous default are now always available, including on Bedrock/Vertex/Foundry.” (ai-research/claude-code-release-v2-1-248.md; ai-research/claude-code-docs-changelog-2026-08-28.md.)

loop.md (custom default)

Replace the built-in maintenance prompt with your own. Two locations, first match wins:

PathScope
.claude/loop.mdProject-level. Takes precedence when both files exist.
~/.claude/loop.mdUser-level. Applies in any project that does not define its own.

Plain Markdown — write it like you’d type a /loop prompt directly. Edits take effect on the next iteration. Truncated past 25,000 bytes.

Bedrock / Vertex AI / Microsoft Foundry: loop.md isn’t read on third-party providers — /loop with no prompt prints the usage message instead. (v2.1.248 made the no-prompt default available on these providers; whether loop.md is now read there is not stated.)

Stopping a loop

Press Esc while it’s waiting for the next iteration. This clears the pending wakeup. Tasks scheduled by asking Claude directly (not via /loop) are not affected by Esc — delete them with the cron tools.

In self-paced mode (dynamic-interval /loop), Claude can also end the loop on its own by calling the ScheduleWakeup tool with stop: true (v2.1.202+). This cancels the pending wakeup immediately. Before v2.1.202, not rescheduling was the only way Claude could end a loop autonomously. Fallback behavior: if a self-paced iteration ends without either rescheduling or stopping, Claude Code schedules one fallback wakeup ~20 minutes later; if that fallback iteration also doesn’t reschedule, the loop ends.

Fixed-interval loops keep running until you press Esc or seven days elapse — ScheduleWakeup stop:true only applies to self-paced loops.

One-time reminders

Describe in natural language; 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

Manage scheduled tasks

Ask Claude in natural language (“what scheduled tasks do I have?”, “cancel the deploy check”), or reference the underlying tools:

ToolPurpose
CronCreateSchedule a task. Takes a 5-field cron expression, the prompt, and recurring vs one-shot.
CronListList all scheduled tasks with IDs, schedules, and prompts.
CronDeleteCancel a task by 8-character ID.

A session can hold up to 50 scheduled tasks at once.

Cron expression reference

5-field standard: minute hour day-of-month month day-of-week. Wildcards (*), single values (5), steps (*/15), ranges (1-5), comma lists (1,15,30).

ExampleMeaning
*/5 * * * *Every 5 minutes
0 * * * *Every hour on the hour
0 9 * * *Every day at 9am local
0 9 * * 1-5Weekdays at 9am local
30 14 15 3 *March 15 at 2:30pm local

Day-of-week: 0 or 7 is Sunday, 6 is Saturday. Not supported: extended syntax like L, W, ?, name aliases (MON, JAN). When both day-of-month and day-of-week are constrained, a date matches if either matches (vixie-cron semantics).

All times interpreted in local timezone — 0 9 * * * is 9am wherever you’re running Claude Code, not UTC.

How tasks run

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

Jitter

To stop every session hitting the API at the same wall-clock moment:

  • Recurring tasks fire up to 30 minutes after the scheduled time (or up to half the interval, for tasks that run more often than hourly). An hourly job scheduled for :00 may fire anywhere up to :30. (Prior to W19, this was “up to 10% of period, capped at 15 minutes”.)
  • One-shot tasks scheduled for the top or bottom of the hour fire up to 90 seconds early.

The offset is derived from the task ID, so the same task always gets the same offset. Pick a non-:00/:30 minute (e.g., 3 9 * * *) to skip one-shot jitter entirely.

Detailed jitter table (v2.1.299+):

ScheduleMax lateExample
*/5 * * * * (every 5 min)4m 45sfires at most 4m45s after due time
every 10 min0–5 minfires within 5 min of due time
every 30 min0–15 minfires within 15 min of due time
every hour0–30 minfires within 30 min of due time

Schedules where runs are evenly spaced (e.g., */5) get jitter applied to keep them from clustering. Schedules with unevenly spaced runs (e.g., 0,15,45 * * * *) are not guaranteed to be evenly spread.

Seven-day expiry

Recurring tasks automatically expire 7 days after creation. They fire one final time, then delete themselves. To last longer, cancel and recreate before expiry — or use Routines / Desktop scheduled tasks for durable scheduling.

Disable scheduled tasks

Set CLAUDE_CODE_DISABLE_CRON=1 in your environment. The cron tools and /loop become unavailable; already-scheduled tasks stop firing.

Limitations

  • Tasks only fire while Claude Code is running and idle.
  • No catch-up for missed fires — busy through a scheduled time means it fires once when Claude becomes idle, not once per missed interval.
  • Starting a fresh conversation clears all session-scoped tasks. claude --resume / --continue restores unexpired tasks (recurring within 7 days of creation, one-shots whose time hasn’t passed). Background Bash and Monitor tasks are never restored on resume.
  • Backgrounding the session (via agent view) carries /loop tasks over to a background session, which keeps running without a terminal — useful for long-running loops that would otherwise die when you close your terminal.
  • .claude directory symlink check (v2.1.216). Claude Code stores the scheduled task list in the project’s .claude directory. Scheduling a task fails with an error when that directory, or the task file inside it, is a symlink. Before v2.1.216, Claude Code wrote the task file through the link.

Recent additions (2026-07-12 watchlist sweep)

New content in Claude Code scheduled tasks docs as of v2.1.202, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-scheduled-tasks-2026-07-12.md:

  • ScheduleWakeup stop:true (v2.1.202). In self-paced (/loop dynamic) mode, Claude can now explicitly end a loop by calling ScheduleWakeup with stop: true. This cancels the pending wakeup immediately. Before v2.1.202, not rescheduling was the only mechanism for Claude to end a loop autonomously.
  • Fallback wakeup behavior (v2.1.202–v2.1.318, changed in v2.1.319). Prior to v2.1.319: if a self-paced iteration ended without rescheduling or stopping, Claude Code scheduled a single fallback wakeup ~20 minutes later; if that fallback also didn’t reschedule, the loop ended. As of v2.1.319: a turn that finishes without calling ScheduleWakeup immediately ends the loop — no fallback wakeup. Set CLAUDE_CODE_LOOP_KEEPALIVE=1 to restore the pre-v2.1.319 fallback behavior.
  • Fixed-interval loop stop clarification. Fixed-interval loops keep running until Esc or 7-day expiry — ScheduleWakeup stop:true does not apply to them.

Recent additions (v2.1.212, July 17)

New in v2.1.212, sourced from ai-research/claude-code-docs-changelog-2026-07-17.md and ai-research/claude-code-docs-whats-new-w29-2026-07-17.md:

  • /fork → new background session; /subtask = in-session fork (v2.1.212). /fork has changed semantics again. As of v2.1.212, /fork creates a new background session with its own row in claude agents — it copies the current conversation context and runs independently while the original session keeps going. The old in-session delegate behavior (dispatch a subagent within the current session, get its result back in-place) is now /subtask. This changes how /fork interacts with scheduled tasks: a /loop-managed session that forks now produces a fully independent background session, not an in-session delegate that the loop supervises. To preserve the old in-session parallel-work pattern, use /subtask instead.

    /fork evolution: Before June 2 (v2.1.160) → copy transcript to manually-driven new session; June 2, v2.1.160/161 → in-session subagent delegate; July 17, v2.1.212 → new background session (own claude agents row). /subtask is the new in-session delegate.

  • Task tool mode parameter deprecated (v2.1.212). The mode parameter on the Task tool is deprecated — scheduling logic has moved to the ScheduleWakeup tool (already the primary scheduling surface for /loop).

Recent additions (2026-08-02 watchlist sweep)

Content confirmed absent from the article and added from ai-research/watchlist-snapshots/code-claude-com-docs-en-scheduled-tasks-2026-08-02.md (pending item from the 2026-07-26 sweep):

  • .claude directory symlink check (v2.1.216). Claude Code stores the scheduled task list in the project’s .claude directory. Scheduling a task fails with an error when that directory, or the task file inside it, is a symlink. Before v2.1.216, Claude Code wrote the task file through the link.

Desktop scheduled tasks in Cowork (Ben AI, added 2026-10-28)

Source: raw/Claude_Cowork_Just_Became_10x_Better_Scheduled_Tasks.md. Creator: Ben AI · URL: https://www.youtube.com/watch?v=F6T3WkTWYX4 · Duration: 7:17 · Platform: YouTube · Uploaded: 2026-03-11. The same segment reappears in raw/CLAUDE_COWORK_FULL_COURSE_2+_Hours.md (2026-04-04). This is the “Desktop scheduled tasks” column of the table above, as it worked in March 2026; see the outdated note at the end.

  • What a task is. The Scheduled sidebar page takes a name, description, prompt, frequency (every 10 minutes up to monthly), model and folder. At each interval it sends the prompt to a fresh session. Ben says it worked the same way in Cowork and in the desktop Code tab.
  • Three ways to create one: the Scheduled page form; /schedule in a chat (“every day at 6:00 a.m. schedule my email categorization skill”); or tell Claude while building a skill (“you’re going to run this on the first of each month at 9:00 a.m.”).
  • Schedule skills, not prompts. The prompt just names the skill (“check my unread emails for relevance, you’re my personal assistant, use the daily email skill”), so the schedule runs a tested procedure. Commands that chain several skills can be scheduled the same way.
  • His scheduled skills: daily email categorisation; a daily task review that weighs what was done the previous two days; daily meeting processing (Fireflies transcripts → tasks, meeting overview, key decisions and next-day agenda written to Notion, fully autonomous); daily failed-payment follow-up (checks yesterday’s failed payments, checks earlier email threads, categorises the failure, saves a matching draft in Gmail for review); and monthly accounting (Gmail, Stripe, web search and the Chrome browser to update a spreadsheet, pausing with a blue-dot notification when it needs input). He says the payment follow-up already affects revenue.
  • Human-in-the-loop tasks still help. For accounting the schedule acts as a reminder and does the gathering before he steps in.
  • Polling as a trigger. With no webhooks, run a task often enough to catch events: e.g. hourly “check for new payments and send a thank-you email”. Add a Slack alert for urgent items to turn a skill into a notifier.
  • The limit he hit (March 2026): tasks ran only while the desktop app was open; missed runs fired when it was next opened. That limit is outdated: since July 2026 scheduled tasks inside cloud projects run with no device online, and since October 2026 they attach to projects (see Claude Cowork). For event triggers with the laptop closed Ben later moved to Routines, and he later advised turning report-only scheduled tasks into live artifacts.

Key Takeaways

  • /loop is the lightweight, session-scoped scheduler — for cloud durability use Routines; for machine durability, Desktop scheduled tasks.
  • Three usage shapes: fixed interval (/loop 5m ...), Claude-paced (/loop ... with no interval), or bare /loop for the built-in maintenance prompt or your loop.md.
  • Recurring loops auto-expire after 7 days; reset by recreating, or pick a durable scheduler upstream.
  • Jitter is deterministic (derived from task ID) — predictable per task, scattered across sessions in aggregate.
  • Esc cancels a pending /loop wakeup; in self-paced mode, Claude can also call ScheduleWakeup with stop: true (v2.1.202+) to end the loop intentionally. Cron tasks scheduled directly need CronDelete by ID.
  • Available since Claude Code v2.1.72. To turn off: CLAUDE_CODE_DISABLE_CRON=1.

Try It

  1. Smoke test: in any session, run /loop 1m print the time. Watch it fire once, cancel with Esc.
  2. PR babysitter: create .claude/loop.md in a project with: “Check the release/next PR. If CI red, pull the failing job log and propose a fix. If review comments arrived, address each. If green and quiet, say so in one line.” Then run bare /loop in that project.
  3. Self-paced poll: /loop check whether CI passed and address any review comments — Claude shortens intervals while active, lengthens once quiet.
  4. One-shot reminder: remind me in 45 minutes to check the integration tests.
  5. List with: “what scheduled tasks do I have?” Cancel with: “cancel the deploy check job.”

Recent additions (2026-08-21 weekly sweep)

/goal behavior changes from v2.1.236 and v2.1.239, sourced from ai-research/claude-code-docs-changelog-2026-08-21.md:

/goal check-in backoff (v2.1.236 / v2.1.239)

The 30-minute /goal check-in introduced in v2.1.234 now backs off: after the first check-in at 30 minutes, subsequent check-ins space out to 1 hour, then every 2 hours. Previously the check-in repeated every 30 minutes regardless, which could generate noisy interruptions on truly long-running background tasks. The env var CLAUDE_CODE_GOAL_CHECKIN_MINUTES=0 still opts out of check-ins entirely.

/goal restored on --resume (v2.1.239)

Resuming a session from the claude --resume picker now restores its active goal. Previously a goal set in a session was lost when you resumed from another terminal or after a disconnect.

Source: ai-research/claude-code-docs-changelog-2026-08-21.md. Full detail in What’s New — Week 34.

Recent additions (v2.1.246–v2.1.284, August 25 – September 28 2026)

From the anthropics/claude-code release notes; digests: W35 · W37 · W38 · W40.

/goal

  • v2.1.246 (2026-08-25): idle sessions start at most three check-ins on long-running background work per goal; your next message allows three more. This caps the backoff schedule above for sessions nobody is watching.
  • v2.1.269 (2026-09-11): /goal runs no longer stall silently after API errors, network drops or token limits — the goal retries with backoff, or pauses and says why, including until a usage limit resets.
  • v2.1.274 (2026-09-17): hook-driven sessions such as an active /goal compact instead of ending with “Prompt is too long”, and an active goal survives --continue / --resume after the session compacted.

/loop

  • v2.1.248 (2026-08-27): see the Bedrock / Vertex AI / Microsoft Foundry notes under “Claude-paced (dynamic) interval” and “Built-in maintenance prompt” above.
  • v2.1.284 (2026-09-28): in self-paced mode Claude writes each status update, and the outcome when the loop stops, as visible text — before, updates were often written only in its reasoning and not shown.

/schedule and routines

  • v2.1.251 (2026-08-28): /schedule explains that MCP servers configured in Claude Code can’t be attached to cloud routines, instead of a bare “No MCP connectors” message.
  • v2.1.283 (2026-09-25): new routine schedules default to a few minutes past the hour, with a note that routines set exactly on the hour can start several minutes late.

Recent additions (2026-10-18 watchlist sweep)

Source: ai-research/watchlist-snapshots/code-claude-com-docs-en-scheduled-tasks-2026-10-18.md.

  • CronList next-run-times require v2.1.299+. Listing scheduled tasks with CronList now includes the next scheduled run time per task. This field requires v2.1.299 or later; earlier versions return tasks without it.
  • .claude symlink limitation (feature-flag fetching note). Feature-flag fetching at task fire time may not work correctly when the .claude directory is a symlink. The scheduled-task fire may silently read stale flags. Applies if you symlink .claude across projects.

Recent additions (2026-11-14 W46 sweep)

Source: ai-research/claude-code-docs-changelog-2026-11-14.md.

/loop and scheduled tasks now gate some skills (v2.1.325). The release note: scheduled tasks and /loop “ask before running a skill that declares allowed-tools or hooks”. An unattended run that reaches such a skill stops at the prompt.

  • To run a skill without a prompt: add Skill(<skill-name>) to the permissions.allow array in settings.json. For example: "permissions": { "allow": ["Skill(inbox-refresh)"] }.
  • Affects any scheduled task or /loop run that calls a skill declaring allowed-tools or hooks; skills that declare neither are not gated.
  • See W46 digest for the full v2.1.325 changelog.

Open Questions

  • What is the precise “low priority” enqueue behavior — does a long-running tool call extend wait beyond the user’s current turn?
  • Are session-scoped tasks shared across claude --continue from different terminals, or per-tty?
  • Does the Monitor tool’s streaming output count toward the 50-task session limit?