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 Routines | Desktop scheduled tasks | /loop (this article) | |
|---|---|---|---|
| Runs on | Anthropic cloud | Your machine | Your machine |
| Requires machine on | No | Yes | Yes |
| Requires open session | No | No | Yes |
| Persistent across restarts | Yes | Yes | Restored on --resume if unexpired |
| Local file access | No | Yes | Yes |
| MCP servers | Per-task | Config files + connectors | Inherits from session |
| Permission prompts | None (autonomous) | Configurable | Inherits from session |
| Customizable schedule | Via /schedule | Yes | Yes |
| Minimum interval | 1 hour | 1 minute | 1 minute |
/loop usage
Alias:
/proactiveis an alias for/loopas of Week 16 (v2.1.105). Both forms work identically.
| Form | Example | Behavior |
|---|---|---|
| Interval + prompt | /loop 5m check the deploy | Runs on a fixed cron schedule |
| Prompt only | /loop check the deploy | Claude picks an interval (1m–1h) per iteration |
| Interval only / nothing | /loop or /loop 15m | Runs 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,
/loopwith 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: “/loopself-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:
| Path | Scope |
|---|---|
.claude/loop.md | Project-level. Takes precedence when both files exist. |
~/.claude/loop.md | User-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.mdisn’t read on third-party providers —/loopwith no prompt prints the usage message instead. (v2.1.248 made the no-prompt default available on these providers; whetherloop.mdis 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 passedManage scheduled tasks
Ask Claude in natural language (“what scheduled tasks do I have?”, “cancel the deploy check”), or reference the underlying tools:
| Tool | Purpose |
|---|---|
CronCreate | Schedule a task. Takes a 5-field cron expression, the prompt, and recurring vs one-shot. |
CronList | List all scheduled tasks with IDs, schedules, and prompts. |
CronDelete | Cancel 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).
| Example | Meaning |
|---|---|
*/5 * * * * | Every 5 minutes |
0 * * * * | Every hour on the hour |
0 9 * * * | Every day at 9am local |
0 9 * * 1-5 | Weekdays 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
:00may 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+):
| Schedule | Max late | Example |
|---|---|---|
*/5 * * * * (every 5 min) | 4m 45s | fires at most 4m45s after due time |
| every 10 min | 0–5 min | fires within 5 min of due time |
| every 30 min | 0–15 min | fires within 15 min of due time |
| every hour | 0–30 min | fires 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/--continuerestores 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
/looptasks 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. .claudedirectory symlink check (v2.1.216). Claude Code stores the scheduled task list in the project’s.claudedirectory. 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 (/loopdynamic) mode, Claude can now explicitly end a loop by callingScheduleWakeupwithstop: 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
ScheduleWakeupimmediately ends the loop — no fallback wakeup. SetCLAUDE_CODE_LOOP_KEEPALIVE=1to restore the pre-v2.1.319 fallback behavior. - Fixed-interval loop stop clarification. Fixed-interval loops keep running until
Escor 7-day expiry —ScheduleWakeup stop:truedoes 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)./forkhas changed semantics again. As of v2.1.212,/forkcreates a new background session with its own row inclaude 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/forkinteracts 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/subtaskinstead./forkevolution: 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 (ownclaude agentsrow)./subtaskis the new in-session delegate. -
Task tool
modeparameter deprecated (v2.1.212). Themodeparameter on the Task tool is deprecated — scheduling logic has moved to theScheduleWakeuptool (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):
.claudedirectory symlink check (v2.1.216). Claude Code stores the scheduled task list in the project’s.claudedirectory. 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;
/schedulein 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
/loopis 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/loopfor the built-in maintenance prompt or yourloop.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.
Esccancels a pending/loopwakeup; in self-paced mode, Claude can also callScheduleWakeupwithstop: true(v2.1.202+) to end the loop intentionally. Cron tasks scheduled directly needCronDeleteby ID.- Available since Claude Code v2.1.72. To turn off:
CLAUDE_CODE_DISABLE_CRON=1.
Try It
- Smoke test: in any session, run
/loop 1m print the time. Watch it fire once, cancel withEsc. - PR babysitter: create
.claude/loop.mdin a project with: “Check therelease/nextPR. 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/loopin that project. - Self-paced poll:
/loop check whether CI passed and address any review comments— Claude shortens intervals while active, lengthens once quiet. - One-shot reminder:
remind me in 45 minutes to check the integration tests. - 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):
/goalruns 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
/goalcompact instead of ending with “Prompt is too long”, and an active goal survives--continue/--resumeafter 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):
/scheduleexplains 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.
CronListnext-run-times require v2.1.299+. Listing scheduled tasks withCronListnow includes the next scheduled run time per task. This field requires v2.1.299 or later; earlier versions return tasks without it..claudesymlink limitation (feature-flag fetching note). Feature-flag fetching at task fire time may not work correctly when the.claudedirectory is a symlink. The scheduled-task fire may silently read stale flags. Applies if you symlink.claudeacross 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 thepermissions.allowarray insettings.json. For example:"permissions": { "allow": ["Skill(inbox-refresh)"] }. - Affects any scheduled task or
/looprun that calls a skill declaringallowed-toolsor hooks; skills that declare neither are not gated. - See W46 digest for the full v2.1.325 changelog.
Related
- Claude Code Routines — durable cloud scheduler; the persistent counterpart.
- goal` command (Week 20) — goal-convergent counterpart: Claude keeps working until it decides the goal is met, rather than running on a schedule.
- Ultraplan — cloud-hosted plan-mode counterpart; another “delegate to the cloud” pattern.
- Claude Code Agent Teams — pairs with scheduled tasks for long-running parallel work.
- Claude Code Hooks — event-driven (vs time-driven) deterministic actions.
- Claude Code Channels — push external events for reactive (rather than polling) workflows.
- Claude Managed Agents — for fully unattended cloud-hosted agents.
- Cowork Marketing Skills Playbook (Ben AI) — a scheduled newsletter-ideation skill with a CSV log to avoid repeats.
- Ultrareview (Cloud Multi-Agent Code Review) — runs in background; pair with
/loopto poll for completion. - Week 15 release digest — Monitor tool launch + self-pacing
/loopintegration. - Loop Engineering: Getting Started with Loops — Anthropic’s own post naming
/loop//scheduleas the “time-based loop” primitive: local-and-ephemeral (/loop) vs. cloud-durable (/schedule). - Cowork + Skills Content System (Grace Leung) — a scheduled content pipeline run from a planner spreadsheet
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 --continuefrom different terminals, or per-tty? - Does the Monitor tool’s streaming output count toward the 50-task session limit?