How Claude Loops Work

If you have read What Are Claude Loops? you already know what a loop is. This page goes one layer deeper — how loops actually execute, what the runtime does between iterations, and the design choices you should make to keep loops fast, cheap, and correct.

The lifecycle of a loop

Every Claude Loop follows the same six-stage lifecycle:

1. Invocation. You type /loop <interval> <task>. The runtime parses the interval (optional) and the task body.
2. First execution. Claude runs the task immediately, as if you typed it directly. The task can use any tool, read any file, call any MCP server.
3. Scheduling. When the task finishes, the runtime schedules the next wake-up. In fixed-interval mode, that is exact arithmetic. In dynamic mode, Claude calls ScheduleWakeup and picks a delay.
4. Idle wait. The session sleeps until the scheduled time. No tokens are consumed during this period.
5. Re-invocation. The runtime wakes Claude back up and re-runs the same prompt. Conversation history is preserved.
6. Termination. Loop ends when you type /loop stop, end the session, or the model decides not to schedule another wake-up.

Fixed-interval mode

This is the simpler of the two modes. You provide an explicit time string and the runtime takes care of scheduling.

/loop 5m check the staging deploy

Accepted interval formats include seconds (30s), minutes (5m), hours (2h), or a combination (1h30m). The runtime clamps anything under a sensible floor — typically 60 seconds — to prevent runaway loops.

Fixed-interval is great when:

• You know the exact cadence the underlying state changes at (e.g. a metric that updates every minute).
• You want predictable cost — N iterations per hour, period.
• The task is uniform every time.

Dynamic mode and ScheduleWakeup

Dynamic mode is where Claude Loops get genuinely intelligent. When you omit the interval, Claude self-paces by calling the ScheduleWakeup tool at the end of each iteration.

/loop poll the deploy and tell me when it is live

At the end of each run, Claude decides:

• Whether to schedule another iteration at all.
• How long to wait — typically a number of seconds, clamped to a runtime-defined range.
• What prompt to re-fire on wake-up (usually the same one — pass it verbatim).

The model is trained to think about what it is actually waiting for, not "how many minutes feels right." This produces much better pacing than a fixed interval in most real-world cases.

The cache-window trade-off

Anthropic's prompt cache has a roughly 5-minute TTL. That has direct consequences for delay choice:

• Under ~5 minutes (60-270s): cache stays warm. Cheap and fast. Right for actively polling external state.
• ~5 minutes to 1 hour (300-3600s): you pay a cache miss. Right when you genuinely need to wait minutes for the underlying state to change.
• Don't pick exactly 300s. Worst of both — you eat the cache miss without amortizing it. Either drop to ~270s or commit to 1200s+.

How loops survive long sessions

A common worry: "Won't a loop fill my context window and break?" No. Claude Code automatically summarizes prior messages as the conversation grows. Loops are designed to ride out compressions without state loss. The runtime preserves:

• The original loop prompt — re-fired verbatim each iteration.
• Long-running tool results (open files, running background processes).
• Memory and skills, which live outside the conversation.

What is summarized is the back-and-forth of prior iterations. That is almost always fine — each loop run is independent reasoning, not a continuation of the last.

Stopping conditions

A loop ends in one of four ways:

1. Explicit stop. You type /loop stop in the session.
2. Session end. Closing Claude Code terminates the loop. Nothing leaks into the background.
3. Model self-termination. In dynamic mode, Claude can simply omit the ScheduleWakeup call. No next iteration is scheduled.
4. Runtime cancellation. The runtime can cancel a loop on certain unrecoverable errors.

Local loops vs. cloud routines

Loops are session-bound by default. If you close your laptop, the loop stops. For unattended automation, you have two options:

• /schedule — creates a cloud routine that runs on a cron schedule using CronCreate. Independent of your local session.
• Autonomous /loop — a special invocation pattern (<<autonomous-loop-dynamic>>) where there is no user prompt and the model runs on its own goals. Useful for cloud agents that need self-paced wake-ups rather than cron arithmetic.

Best practices

1. Match the interval to the state-change rate

If a deploy takes ~8 minutes, polling every 60 seconds burns the prompt cache 8 times for nothing. Use ~270s or let dynamic mode pick.

2. Make the task idempotent

Loops re-run. If your task creates files, opens PRs, or sends messages, build in checks so the second iteration does not duplicate work from the first.

3. Give the loop a clear "done" condition

Especially in dynamic mode, tell Claude when to stop. "Watch the deploy and ping me when it is live, then end the loop" is better than "watch the deploy."

4. Keep the task small

One loop, one job. Multiple independent jobs deserve multiple loops, or a wrapper skill that branches.

5. Log what changed

Loops that scan for new state should remember what they saw last time. Use a scratch file or skill memory to dedupe.

Loops and tool use

Loops can call any tool Claude Code has access to in the current session — file I/O, Bash, web fetch, MCP servers, skills. The model decides which to use per iteration. That is the entire reason loops exist: programmable polling with judgment, not just a cron task.

Where to go from here

• Step-by-step starter guide — get your hands dirty.
• Full documentation — every flag, every option.
• 20+ examples — copy-paste templates.