Skillforge Field notes on shipping with AI tools

Claude Code /loop: Fixed, Self-Paced and Default Loops

claude-codeai-workflows

/loop re-runs a prompt on a schedule while a Claude Code session stays open. It is the quick way to poll a deploy or babysit a pull request, and it behaves differently depending on whether you give it an interval, a prompt, both or neither. This page covers the three forms, when a run starts late, how loops end, and what /loop is not good for.

Verified against: the Claude Code scheduled-tasks documentation and commands page (fetched 2026-11-20), the GitHub changelog for 2.1.329, and claude --version (2.1.329). This is documentation reading, not a live run: we did not start a loop and watch it fire, so every behavior below is as documented. Where the changelog says something the docs do not yet say, it is marked.

The three forms

| You type | What happens | | :- | :- | | /loop 5m check the deploy | Your prompt runs on a fixed schedule | | /loop check the deploy | Your prompt runs at an interval Claude picks after each iteration | | /loop or /loop 15m | A built-in maintenance prompt runs (or your loop.md, if you have one) |

You can pass a skill as the prompt, such as /loop 20m /review-pr 1234. A scheduled fire only runs skills Claude is allowed to invoke on its own. Built-in commands like /model or /clear, skills marked disable-model-invocation: true, and MCP prompts reach Claude as plain text instead of executing.

Fixed interval

With an interval, Claude turns it into a cron expression, schedules the job and confirms the cadence and an 8-character job ID. The interval can lead (30m) or trail (every 2 hours) and takes s, m, h or d. Cron has one-minute granularity, so seconds round up to a minute, and intervals that are not a clean cron step (the docs give 7m and 90m) are rounded to the nearest one that is. Claude tells you what it picked, so read the confirmation.

Self-paced interval

Leave the interval out and Claude chooses a delay between one minute and one hour after each iteration, based on what it saw: short while a build is finishing, longer when nothing is pending. The delay and the reason are printed at the end of each iteration. In a session where the Monitor tool is available, Claude may use it instead of polling, which streams script output back and, per the docs, is often more token-efficient.

Self-paced loops and the maintenance prompt work on every provider and with feature-flag fetching off. On Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry, or with fetching off, both need v2.1.248 or later.

The default prompt and loop.md

A bare /loop runs a built-in prompt that, in order, continues unfinished work from the conversation, tends the current branch's pull request (review comments, failed CI, merge conflicts), and then runs cleanup passes when nothing else is pending. Each run still goes through your permission checks before it pushes or deletes anything.

To replace that prompt, create a loop.md file. It defines one default prompt for a bare /loop, not a list of tasks, and Claude Code ignores it whenever you type a prompt on the command line. To run more prompts alongside it, use /loop <prompt> or ask Claude directly.

When a run actually starts

Do not expect cron-exact timing. To spread API load, Claude Code shifts each task:

| Schedule | When each run starts | | :- | :- | | Every 5 minutes (/loop 5m, written */5 * * * *) | 4 minutes 45 seconds after the previous run | | Every 10 minutes | 0 to 5 minutes late | | Every 30 minutes | 0 to 15 minutes late | | Hourly or less often | 0 to 30 minutes late |

The rule from the docs: unless it runs every five minutes, a recurring task starts late by up to half the gap to the next run, and by at most 30 minutes. A one-shot task set for :00 or :30 runs up to 90 seconds early, so schedule off the hour (3 9 * * *, not 0 9 * * *) when timing matters.

A scheduled prompt also fires between your turns, not while Claude is mid-response. If Claude is busy when a task comes due, it waits for the turn to end.

Stopping a loop

  • Self-paced loop: press Esc on an empty prompt while it waits for the next iteration. A Pending wakeup cancelled notice confirms it. Ctrl+C while Claude is idle also works, except in a background session you attached to.
  • Fixed-interval loop: ask Claude to cancel it ("cancel the deploy check loop"). Esc and Ctrl+C do not stop it.
  • Claude can end a self-paced loop itself once the job is done, by calling ScheduleWakeup with stop: true.
  • Otherwise it ends on its own: recurring tasks fire one last time 7 days after creation, then delete themselves.

Under the hood these are the CronCreate, CronList and CronDelete tools. You can ask "what scheduled tasks do I have?" to list them with IDs, next run times (v2.1.299 or later) and prompts. A session holds at most 50.

The 2.1.329 changelog says this session's scheduled tasks, /loop wakeups, the goal and forks now appear in /tasks, and that x stops one after asking. The commands page we fetched still describes /tasks as background work and subagents only, so treat the changelog line as unconfirmed by the docs and unrun by us.

What /loop will not do

  • It only fires while Claude Code is running and idle. Close the terminal or exit and it stops. Backgrounding the session carries loops over to the background session.
  • A self-paced loop is not restored by --resume. CronCreate tasks are, except expired recurring tasks and one-shots whose time has passed. Run /loop again.
  • In a background session, a self-paced loop stops if its wakeup comes due while the process is not running, for example after a crash. Reply to the session to keep it going.
  • CLAUDE_CODE_DISABLE_CRON=1 turns the scheduler off: CronCreate and /loop become unavailable and scheduled tasks stop firing.

For work that must run while your machine is off, the docs point to cloud scheduled tasks, Desktop scheduled tasks or GitHub Actions. We cover the unattended claude -p route in running Claude Code on a schedule.

FAQ

What is the shortest interval?

One minute. Seconds in your interval round up to a minute.

Does /loop 5m run exactly every five minutes?

Close: the docs say each run starts 4 minutes 45 seconds after the previous one, to stay inside the five-minute prompt cache window.

Will a loop survive a restart?

A fixed-interval task made with CronCreate is restored on --resume unless it expired. A self-paced /loop is not.

Can I leave one running for a month?

No. Recurring tasks expire after 7 days. Cancel and recreate, or use a cloud or Desktop scheduled task.