Claude Code /loop, Explained: How In-Session Scheduling Actually Works
Claude Code /loop, Explained — How In-Session Scheduling Really Works (and Where It Stops)
A terminal coding agent that re-runs the same job on its own — how much of your automation can you actually hand it?
Claude Code is a coding agent that runs in your terminal. Its base model is request → response: you ask, it answers, the turn ends. /loop adds a time axis on top of that — it re-runs a prompt on a cadence so the agent can poll a deployment every five minutes or babysit a pull request (PR) without you re-typing the request each time. The key constraint to internalize up front: /loop is not a cloud daemon. It lives only inside the terminal session you keep open, and it fires only while that session is running and idle.
This piece walks through five things, each checked against the official documentation: ① which version introduced scheduled tasks, ② what the feature is actually for, ③ how it works under the hood, ④ how it differs from the similar-looking /goal and /schedule, and ⑤ whether a paid subscription auto-resumes a loop after you hit a usage limit.
Version and Release: What's Confirmed
The official docs state plainly that scheduled tasks require Claude Code v2.1.72 or later — you can check yours with claude --version. The minimum-supported version is the one fact the documentation pins down exactly; the precise calendar date the feature shipped is reported as early March 2026, but secondary sources disagree by a day, so treat the exact day as unconfirmed.
💡 Bottom line — the feature is confirmed to work on v2.1.72+, and it shipped in early March 2026. The exact release day needs the primary changelog to confirm.
Three Ways to Invoke It
What you put after /loop determines its behavior — both the interval and the prompt are optional. Give it an interval and it runs on a fixed cron beat; omit the interval and the agent decides when to wake up next; omit both and it runs a built-in maintenance prompt.
| What you provide | Example | What happens |
|---|---|---|
| Interval + prompt | /loop 5m check the deploy | Runs on a fixed schedule (e.g., every 5 minutes) |
| Prompt only | /loop check the deploy | Self-paced: the agent picks the next delay each iteration |
| Interval only, or nothing | /loop | Runs the built-in maintenance prompt (or your loop.md) |
A useful detail for real workflows: the prompt can itself be another command. /loop 20m /review-pr 1234 re-runs a saved skill every 20 minutes — handy when you want a recurring review pass rather than a free-form check. You can also override the bare-/loop default by dropping a loop.md file at .claude/loop.md (project-level) or ~/.claude/loop.md (user-level); edits take effect on the next iteration, so you can refine the instructions while a loop is live.
Under the Hood: Cron, IDs, and Idle Firing
When you supply an interval, the agent translates it into a standard 5-field cron expression, registers it as a task, and hands back an 8-character task ID. A single session can hold up to 50 scheduled tasks at once. The scheduler checks every second for due tasks, but the actual run does not interrupt a response in progress — it slips into the idle gap between turns. If the agent is mid-task when a job comes due, the prompt waits until the current turn ends. This matters because it means a scheduled fire can never corrupt or race the work you're actively doing; the trade-off is that there is no catch-up — a fire missed during a long-running request runs once when the agent goes idle, not once per missed interval.
flowchart TD
A([/loop 5m entered]) --> B[Register cron task
issue 8-char ID]
B --> C{Fire time
reached?}
C -->|YES| D[Run prompt in the
idle gap between turns]
C -->|NO| E[Wait]
D --> C
E --> C
style A fill:#3498db,stroke:#2980b9,color:#ffffff
style B fill:#e8f8f5,stroke:#16a085
style C fill:#fef9e7,stroke:#f39c12
style D fill:#eafaf1,stroke:#27ae60,color:#1e8449
style E fill:#fdedec,stroke:#e74c3c,color:#c0392b
🔁 Diagram in one line: an interval becomes a cron task with an 8-character ID; when the fire time arrives the prompt runs in the idle gap between turns — never mid-response — then returns to waiting.
In self-paced (dynamic) mode — when you omit the interval — the agent chooses the next delay between one minute and one hour after each iteration and prints the delay along with its reasoning. Short waits while a build is finishing or a PR is active; longer waits once things go quiet. The minimum granularity is one minute, so sub-minute inputs round up, and values that don't map to a clean cron step — 7m or 90m — round to the nearest valid interval, with the agent telling you what it picked. One nuance worth knowing: for a dynamic loop the agent may instead reach for the Monitor tool, which streams a background script's output line by line rather than re-running a prompt on a timer — often more token-efficient and more responsive than polling.
Three Myths Worth Correcting
Several explanations floating around contradict the official docs. Here are the three that matter most, corrected against the source.
✓ "Fire times jitter by up to a random 10%" → inaccurate. The offset is deterministic, derived from the task ID, so the same task always gets the same offset. 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); one-shot tasks scheduled for the top or bottom of the hour fire up to 90 seconds early. There is no "random 10%." The purpose is load-spreading — it keeps every open session from hitting the API at the same wall-clock second. If exact timing matters, pick a minute that isn't :00 or :30 (e.g., 3 9 * * *) and the one-shot jitter won't apply.
✓ "Expires after 3 days" → it's actually 7 days. A recurring task auto-expires 7 days after creation: it fires one final time, then deletes itself. The "3 days" figure is a stale or second-hand number. This is a deliberate guardrail — it bounds how long a forgotten loop can run.
✓ "It's a stateless tool that drops context every cycle" → no. /loop runs inside the same session and conversation, and in self-paced mode the built-in maintenance prompt explicitly "continues any unfinished work from the conversation." Context persists. And closing the terminal doesn't necessarily lose it: re-entering with --resume or --continue restores any task that hasn't expired.
/loop vs. /goal vs. /schedule
They look alike but operate on completely different axes. The official docs confirm /goal is real — they point you to it explicitly: to keep a session "working turn after turn until a condition is met rather than on an interval, see /goal." So the right mental model is three distinct triggers: a clock (/loop), a condition (/goal), and a cloud schedule (/schedule / Routines).
| Dimension | /loop | /goal | /schedule (cloud) |
|---|---|---|---|
| Trigger | Time interval or self-paced | Keeps going until a condition is met | Cron / API / GitHub events |
| Runs on | Your machine, session required | Your machine, within a session | Anthropic cloud |
| Session dependence | Must be open to fire | Within a session | Runs with machine off |
| Termination | Manual stop · 7-day expiry | Self-terminates on goal completion | As defined by the task |
| Local files | Accessible | Accessible | No (runs on a fresh clone) |
| Minimum interval | 1 minute | — | 1 hour |
| Best for | Deploy polling, PR babysitting | Migrations, finishing a refactor | Unattended recurring automation |
🧠 In one line — /loop repeats the same work on a beat, /goal drives toward a finish condition and adapts its strategy each turn, and /schedule runs unattended in the cloud independent of your machine or session.
Does It Auto-Resume After a Usage Limit?
🔴 Short answer: no, it does not auto-resume.
On the paid plans (Pro / Max), hitting a rolling usage limit pauses the session with a message like "5-hour limit reached — resets 3pm." Based on widely reported behavior, the loop does not wake itself back up once the limit clears — you have to type continue yourself to get it rolling again. This isn't documented as a feature, and the community issue tracker has several open requests asking for automatic resume, so treat auto-resume-after-limit as not currently supported rather than a confirmed promise.
That said, the claim that "you therefore need an API key" overstates it. /loop works fine on a subscription plan. The real constraints are three: ① no auto-resume after a usage limit, ② a 7-day expiry on recurring tasks, and ③ the requirement that the machine and session stay open. If you need genuinely uninterrupted automation, the docs steer you toward cloud Routines, Desktop scheduled tasks, or GitHub Actions instead. Community workarounds exist too — a shell wrapper that watches the reset time and re-sends continue — but those are supplements, not official features. Worth noting for completeness: you can disable the scheduler entirely with the CLAUDE_CODE_DISABLE_CRON=1 environment variable, which makes the cron tools and /loop unavailable and stops any already-scheduled tasks from firing.
🛡️ Reframe: the missing auto-resume, the 7-day expiry, the 1-minute minimum, and the deterministic offset all read as guardrails against a forgotten loop hammering the API and burning cost forever. They're an inconvenience and an intentional brake at the same time.
When to Reach for It — and When Not To
/loop (v2.1.72+, introduced early March 2026) widens the coding agent from "command → response" into "repeat and watch within a session." But it's not an unattended server daemon — it's closer to an in-session assistant that handles repetitive checks while you keep the session open.
The whole comparison collapses to three axes — /loop (time-based repeat) ↔ /goal (condition-based completion) ↔ /schedule (cloud, unattended). If you want a deploy result or PR status checked while you step away for a few minutes, /loop fits well. If your goal is round-the-clock operation that survives a powered-off laptop — say, a job that must run every night — cloud Routines or a CI pipeline is the saner choice on both cost and reliability grounds. The one open question left is the exact release date and the precise v2.1.71 / v2.1.72 boundary, which only the primary changelog can settle.
This article is an informational summary compiled from publicly available official documentation and technical references; it is not a recommendation to adopt or purchase any particular product. Software versions, policies, and pricing change frequently, so verify current specs against the official docs before relying on them.
I gather material from a software-development angle, write it up myself, and double-check it once more before publishing.
This article was written from publicly available data and sources. Last updated: June 9, 2026
📄 View raw research source — click to expand
1차 출처(Claude Code official documentation) has been secured. This resolves most of the contradictions from the research rounds, and several figures (10% jitter, 3-day expiry, stateless) are determined to be errors. On the other hand, the `/goal` command has been **confirmed to exist via official documentation**. This report is written based on verified facts. --- # In-Depth Analysis of Claude Code's `/loop` Feature — How It Works, What Sets It Apart from `/goal` and `/schedule`, and Handling Usage Limits ## 1. Understanding the Question This analysis covers four points: ① the **introduction date and version** of `/loop` added to Claude Code, ② its **functional purpose**, ③ its **technical mechanism**, and ④ how it **differs** from the outwardly similar `/goal`, as well as whether it **automatically resumes upon hitting usage (rate) limits** on subscription plans. This report is written based on the primary source, **Anthropic's official documentation (`code.claude.com/docs/en/scheduled-tasks`)**. Where some figures from prior research rounds (10% jitter, 3-day expiry, "stateless") conflict with the official documentation, they are explicitly noted and corrected. ## 2. Foundation Claude Code is a coding agent that runs in the terminal (CLI). Traditionally, it followed a one-shot round-trip structure of "user input → model response." `/loop` adds **repetition along a time axis** to this structure, automatically re-running a single prompt (or slash command) on a set interval. The official documentation defines it as *"run a prompt repeatedly, poll for status, or set one-time reminders within a Claude Code session."* The key concept here is **session-scoped**. Tasks created by `/loop` live not in an OS daemon or the cloud, but **only within the currently open conversation session**. ## 3. Current State — Version and Date - **Required version**: The official documentation states *"Scheduled tasks require Claude Code v2.1.72 or later"* ([official docs](https://code.claude.com/docs/en/scheduled-tasks)). - **Version discrepancy (contradiction noted)**: The prior research rounds said *"`/loop` was introduced in v2.1.71,"* and web search results also contain both *"introduced in v2.1.71"* and *"requires v2.1.72 or later."* The most coherent interpretation is that **the command first arrived in 2.1.71, and 2.1.72 is the minimum requirement for the scheduler to operate stably**, but there is insufficient primary evidence to definitively settle on one or the other. - **Introduction date (insufficiently verified)**: The research rounds diverged between 2026-03-06 and 2026-03-07, and **both dates rely on secondary sources such as Korean media (AI Times, GeekNews)**. The exact date specified in Anthropic's official changelog was not confirmed as a primary source within the scope of this research, so the **date is trusted only as "early March 2026,"** leaving the day-level detail undetermined. ## 4. Technical Mechanism `/loop` branches into **three modes** depending on the input (per the official documentation table). | Input form | Example | Behavior | |---|---|---| | Interval + prompt | `/loop 5m check the deploy` | Repeats on a **fixed interval** (cron) | | Prompt only | `/loop check the deploy` | **Claude dynamically chooses the interval each repetition** (self-paced) | | Interval only or empty | `/loop` | Runs the built-in maintenance prompt (or `loop.md`) on a dynamic interval | The mechanism works as follows. 1. **cron conversion**: When given an interval, Claude converts it into a 5-field cron expression, registers the task via the `CronCreate` tool, and issues an 8-digit task ID. Management uses `CronList`/`CronDelete` (up to 50 per session). 2. **Internal scheduler**: The scheduler **checks for due tasks every second**, but the prompt fires **between turns (idle), not in the middle of a response**. If busy, it waits until the current turn finishes. 3. **Session dependence**: Closing the terminal or starting a new conversation makes the task disappear. However, if you resume with `--resume`/`--continue`, **unexpired tasks are restored** — this directly conflicts with the "stateless" description from prior research (see the contradiction section below). 4. **Dynamic (self-paced) mode**: When the interval is left empty, Claude decides the next delay itself, **between 1 minute and 1 hour**, after each repetition and outputs its reasoning. It keeps the interval short while a build is in progress, and long when things are quiet. At this point it may also use the **Monitor tool**, which streams a background script, to avoid polling altogether. 5. **Minimum interval of 1 minute**: Second (`s`) units are rounded up to 1 minute. Untidy intervals like `7m` or `90m` are rounded to the nearest cron step, and Claude reports the result. ### Contradiction Corrections — Jitter, Expiry, Stateless - **Jitter**: The prior research said *"up to 10% random jitter,"* but **this is inaccurate.** Per the official documentation, the jitter is a **deterministic offset derived from the task ID**; recurring tasks fire **up to 30 minutes (or half the interval for sub-hourly frequencies)** from the scheduled time, and one-shot tasks fire **up to 90 seconds early**. The phrase "10% random" does not appear in the primary source. - **Expiry**: Round 1 stated a *"3-day limit,"* while Round 2 implied 7 days. **The official documentation confirms 7 days (seven-day expiry)** — a recurring task fires one last time 7 days after creation and is then automatically deleted. "3 days" appears to be a remnant of an older version or secondary source. - **Stateless or not**: Round 1's claim that *"it is stateless, carrying no context forward each cycle"* is **factually incorrect.** `/loop` runs within the same session and conversation, and in particular the built-in prompt in dynamic mode explicitly performs *"continue any unfinished work from the conversation."* In other words, **context is preserved**. ## 5. `/loop` vs `/goal` vs `/schedule` (Routines) Comparison — Resolving the Contradiction The prior research contained a contradiction that *"the existence of `/goal` was not confirmed as a primary source,"* but **the official documentation confirms `/goal` exists**: *"To keep the session working turn after turn until a condition is met rather than on an interval, see `/goal`."* The comparison is therefore valid, and it is actually more accurate to organize it along **three axes**. | Category | `/loop` | `/goal` | `/schedule` (Routines, cloud) | |---|---|---|---| | **Trigger** | Time interval (cron) or dynamic self-pacing | Continuous turns **until a condition is met** (not an interval) | cron / API / GitHub events | | **Execution location** | My machine, requires an open session | My machine, within a session | **Anthropic cloud** | | **Session/machine dependence** | Fires only while the session is open | Within a session | Runs even with the machine OFF or the session ended | | **Termination condition** | Manual stop (Esc) / 7-day expiry; in dynamic mode, self-terminates when it judges completion | **Self-terminates when the goal is achieved** | As defined by the task | | **Local file access** | Available (inherited from session) | Available | Unavailable (fresh clone) | | **Minimum interval** | 1 minute | — | **1 hour** | | **Primary use** | Deploy polling, PR monitoring, build checks | Completing deliverables such as migrations and refactors | Unattended recurring automation | The gist: **`/loop` is "repeat the same task on a set beat,"** **`/goal` is "advance toward an end condition, changing strategy each turn,"** and **`/schedule` (Routines) is "run unattended in the cloud, independent of my computer and session."** The prior research's analogy of `/loop` as a "gear" and `/goal` as "navigation" is reasonable at the trigger level. ## 6. On Subscription Plans When Hitting a Rate Limit — Does It Auto-Resume? **Conclusion: It does not auto-resume (confirmed by primary source).** - On subscription plans (Pro/Max), when Claude Code hits the 5-hour or 7-day rolling limit, it stops the session with a message like *"5-hour limit reached — resets 3pm,"* and **it does not wake itself up even after the reset.** The user must enter `continue` themselves. - This is **a currently unimplemented feature**, with numerous feature requests open on Anthropic's official issue tracker — [#35744](https://github.com/anthropics/claude-code/issues/35744), [#36320](https://github.com/anthropics/claude-code/issues/36320), [#18980](https://github.com/anthropics/claude-code/issues/18980). In other words, the prior research's conclusion of "no auto-resume support" is **accurate.** - **However, the prior research's assertion that "an API key connection is mandatory" is an overstatement.** `/loop` works fine on subscription plans too. But because ① there is no auto-resume on hitting the limit, ② there is a 7-day expiry, and ③ the machine and session must stay open, the official documentation recommends using **Routines (cloud), Desktop scheduling, or GitHub Actions** rather than the pay-as-you-go API **when true uninterrupted automation is needed**. An API key is just one way to bypass subscription limits, not a prerequisite for `/loop`. - **Community workarounds**: External shell wrappers (such as `claude-auto-retry`) that detect the reset time and automatically send `continue` exist; these are supplementary, not official features. - **From a safety standpoint**: The absence of auto-resume, the 7-day expiry, the 1-minute minimum interval, and the deterministic jitter all function as **cost and safety guards that prevent a forgotten loop from hammering the API indefinitely**. For reference, the entire scheduler can be turned off with the `CLAUDE_CODE_DISABLE_CRON=1` environment variable. ## 7. Conclusion and Implications `/loop` (operating on Claude Code v2.1.72+, estimated introduced in early March 2026) is a feature that extends the coding agent from "command–response" to an **"in-session repetition and monitoring"** structure. But it is not an unattended server daemon; rather, it is closer to an **in-session helper tool that handles repeated checks on a developer's behalf while they keep the session open**. The key differentiators compress into three axes — `/loop` (time-based repetition) ↔ `/goal` (condition fulfillment) ↔ `/schedule`/Routines (unattended cloud). The lack of auto-resume on subscription plans is both a limitation and **an intentional brake to prevent runaway costs**. Therefore, if uninterrupted operation is the goal, choosing cloud Routines or a CI pipeline instead of `/loop` is the sensible choice on both cost and stability fronts. The remaining verification tasks are the **exact introduction date (primary confirmation via official changelog)** and the **precise dividing line between v2.1.71 and v2.1.72**. These two are hard to settle with primary sources at this point and require further confirmation. ## Inter-Round Contradictions - The version/date (v2.1.71 · 2026-03-07, /goal v2.1.139) was presented without a primary source (Anthropic's official changelog/docs), relying only on two secondary Korean media outlets, so verification is insufficient - There is potential conflict between the technical description that "/loop is stateless, carrying no context forward each cycle" and the actual behavior that "in self-pace mode it continues the loop with the same prompt" — needs re-confirmation via primary source - Introduction date: Round 1 says 2026-03-07, Round 2 says 2026-03-06, a discrepancy - Both Round 1 and 2 assume the '/goal' command as a comparison target, but there is no citation confirming its existence via primary source (whether the command actually exists is unverified) - Sources are presented only as top-level URLs like 'github.com/anthropics/claude-code' and 'docs.anthropic.com/' without quoting the original text of the v2.1.71 changelog entry, so the version, date, 10% jitter, and 1-minute min interval figures are not confirmed by primary source --- ## References - [Claude Code official documentation (Scheduled tasks)](https://code.claude.com/docs/en/scheduled-tasks) - [GitHub Issue #35744 auto-resume request](https://github.com/anthropics/claude-code/issues/35744) - [GitHub Issue #36320](https://github.com/anthropics/claude-code/issues/36320) - [AI Times](https://www.aitimes.com/news/articleView.html?idxno=211491) - [GeekNews](https://news.hada.io/topic?id=30314)
댓글
댓글 쓰기