Back to Blog

Claude Code /loop: run a prompt on a schedule, and know how it stops

Alex Kim
11 min read
Claude Code /loop: run a prompt on a schedule, and know how it stops

Last updated: November 18, 2026

TL;DR

/loop reruns a prompt on a schedule inside an open Claude Code session: /loop 5m check if the deployment finished fires every five minutes until you cancel it or seven days pass. Before you start one, know which kind you're making, because the two kinds stop differently (scheduled tasks docs).

  • โฑ๏ธ Fixed interval. /loop 30m <prompt> runs on a cron schedule. Esc won't stop it: ask Claude to cancel it.
  • ๐Ÿงญ Claude picks the interval. /loop <prompt> waits between one minute and one hour each time. Esc on an empty prompt stops it, and Claude can end it when the work is done.
  • ๐Ÿงน Nothing at all. A bare /loop runs a built-in maintenance prompt, or your own loop.md.
  • ๐Ÿ–ฅ๏ธ It needs the session. Close the terminal and it stops firing. For schedules that outlive the session, use a desktop or cloud scheduled task.
  • ๐Ÿ“… It expires. Recurring tasks delete themselves 7 days after creation.

Before you start

/loop is a bundled skill, and it only works while Claude Code is running and idle. Three things to check first (scheduled tasks docs):

  • The scheduler is on. Setting CLAUDE_CODE_DISABLE_CRON=1 in your environment turns it off, and /loop becomes unavailable.
  • The session will stay open. Tasks fire between your turns, never mid-response, and stop when the session exits. Backgrounding the session carries a loop over to a background session that keeps running without a terminal.
  • Your permissions fit the job. A loop inherits the session's permission mode and MCP servers. If the prompt pushes, deletes or runs a command your settings don't allow, each run stops to ask. Our permissions guide covers the allow rules.

/loop suits polling: a deploy, a pull request's CI, a long build. If what you want is "keep working until the tests pass," that's /goal, which starts the next turn as soon as the last one ends (our /goal guide).

Step 1: Pick the kind of loop

What you type decides how the loop behaves:

You typeExampleWhat runs
An interval and a prompt/loop 5m check the deployYour prompt, on a fixed schedule
A prompt only/loop check the deployYour prompt, at an interval Claude chooses each time
An interval only, or nothing/loopThe built-in maintenance prompt, or your loop.md

Fixed interval is for checks that should happen on the clock. Claude-chosen interval is for work that speeds up and slows down: after each run, Claude picks a delay between one minute and one hour from what it saw, short while a build is finishing and longer when nothing is pending, and prints the delay with its reason. In a session where the Monitor tool is available, Claude may stream a background script's output instead of polling at all.

Step 2: Write the interval and the prompt

The interval can lead as a bare token (30m) or trail as a clause (every 2 hours). The units are s, m, h and d. Two rounding rules apply:

  • Seconds round up to a minute, since cron counts in minutes. The minimum is one minute.
  • Odd intervals round to a clean cron step. 7m or 90m becomes the nearest interval cron can express, and Claude tells you which one it picked.

The prompt can be a skill: /loop 20m /review-pr 1234 reruns that skill each time. Only skills Claude is allowed to invoke on its own will run. Built-in commands such as /model or /clear, skills marked disable-model-invocation: true, and MCP prompts reach Claude as plain text instead.

Claude converts a fixed interval to a cron expression and confirms the cadence and an 8-character job ID. A session holds up to 50 scheduled tasks.

Step 3: Check when it will actually run

A scheduled run doesn't start exactly on the minute. Claude Code shifts each task so that every session's tasks don't hit the API at once:

ScheduleWhen each run starts
Every 5 minutes, which is what /loop 5m creates4 minutes 45 seconds after the previous run
Every 10 minutes0 to 5 minutes late
Every 30 minutes0 to 15 minutes late
Hourly or less often0 to 30 minutes late

To see the next run, read the row under Claude's CronCreate call, which shows a time such as next run 10:21 AM, or ask "what scheduled tasks do I have?" and read the CronList rows. Next-run times need Claude Code v2.1.299 or later. All times are your local timezone, not UTC.

Step 4: Stop it

This is where the two kinds differ, so match the method to the loop:

  • A loop Claude paces: press Esc on an empty prompt while it waits for the next run, or Ctrl+C while Claude is idle. A Pending wakeup cancelled notice confirms it. Claude can also end this kind on its own once the task is done.
  • A fixed-interval loop: ask Claude to cancel it, for example "cancel the deploy check loop". Esc and Ctrl+C don't stop it. Claude removes it with CronDelete and the job ID.
  • Either kind: recurring tasks expire 7 days after creation. The task fires one final time, then deletes itself. To keep a check going longer, cancel and recreate it before then, or move it to a desktop or cloud scheduled task. Take that number from the docs rather than an older write-up.

If a self-paced run ends without rescheduling or stopping, Claude Code schedules one fallback wakeup about 20 minutes later and ends the loop if that run doesn't reschedule either.

Replace the default prompt with loop.md

A bare /loop runs Anthropic's maintenance prompt: continue unfinished work, tend to the current branch's pull request (review comments, failed CI, merge conflicts), then run cleanup passes such as bug hunts when nothing else is pending. Each run goes through your permission checks before it pushes or deletes anything.

To set your own default, write a loop.md file. Claude Code reads .claude/loop.md in the project first, then ~/.claude/loop.md. Write it as you would type the prompt, for example: check the release PR, fix red CI with a minimal change, address new review comments, and say so in one line if everything is quiet. Edits take effect on the next run, it's ignored whenever you type a prompt after /loop, and anything past 25,000 bytes is cut off.

A loop.md is a good place to put the rules a loop should follow every time. Our guide to compound engineering for Claude Code shows how to build that kind of written guidance up one fix at a time.

When a loop doesn't fire

  • No catch-up. If a run comes due while Claude is busy, it fires once when Claude is idle, not once per missed interval.
  • Resuming restores some tasks, not all. Resuming a session restores fixed-interval tasks that haven't expired, but not a self-paced /loop: run /loop again. Background shell commands and monitors aren't restarted either.
  • A crash stops a self-paced loop in a background session if its wakeup comes due while the process isn't running. Reply to the session and ask Claude to keep it going.
  • To leave a background session without stopping its loop, press Ctrl+C twice on an empty prompt while Claude is idle. That needs v2.1.295 or later. Press Esc first if you want the loop stopped. Our agent view guide covers background sessions.

/loop, desktop tasks or cloud tasks

/loopDesktop scheduled taskCloud scheduled task
Runs onYour machineYour machineAnthropic's cloud by default
Needs an open sessionYesNoNo
Needs the machine onYesYesNo
Local filesYesYesNo, a fresh clone
Minimum interval1 minute1 minute when Claude sets it, 1 hour in the forms1 hour

Anthropic's own advice: /loop for quick polling during a session, desktop tasks when you need local files and tools, and cloud tasks for work that should run without your machine. Our guide to Claude scheduled tasks compares the three in detail.

Troubleshooting

SymptomLikely causeFix
/loop isn't availableCLAUDE_CODE_DISABLE_CRON is setRemove it from your environment
Esc doesn't stop the loopIt's a fixed-interval loopAsk Claude to cancel it by name
Runs start minutes lateJitter on intervals other than 5 minutesExpected; read the next run time in CronList
Each run stops to askThe loop inherits Manual permissionsAllow the commands it needs, or change the session's mode
A skill in the prompt shows up as textThe skill can't be invoked by Claude, or it's a built-in commandUse a skill Claude may invoke, or describe the steps in the prompt
The loop vanished after a restartIt was self-paced, or it expiredRun /loop again

Frequently asked questions

What does /loop do in Claude Code?

It reruns a prompt on a schedule while your session stays open. With an interval, such as /loop 5m, it runs on a fixed cron schedule. Without one, Claude picks a delay between one minute and one hour after each run. With no prompt, it runs a built-in maintenance prompt or your loop.md.

How do I stop a /loop in Claude Code?

It depends on the kind. A loop Claude paces stops with Esc on an empty prompt, or Ctrl+C while Claude is idle. A fixed-interval loop such as /loop 5m doesn't respond to either: ask Claude to cancel it by name. Every recurring task also ends on its own 7 days after creation.

How long does a Claude Code /loop run?

Until you stop it, Claude ends a self-paced loop, or 7 days pass. Recurring tasks expire 7 days after creation, fire one last time and delete themselves. To run longer, cancel and recreate the loop before it expires, or use a desktop or cloud scheduled task.

Does /loop keep running when I close Claude Code?

No. Tasks fire only while Claude Code is running and idle, so closing the terminal stops them. Backgrounding the session keeps the loop going without a terminal. For a schedule independent of any session, use a desktop scheduled task on your machine or a cloud scheduled task.

What is the difference between /loop and /goal?

A loop starts the next run when a time interval passes, which suits polling a deploy or a pull request. A goal starts the next turn as soon as the last one ends and stops when a separate model confirms your condition holds. Use /loop to check back and /goal to finish a task.

What is the minimum interval for /loop?

One minute. Seconds round up to the nearest minute, since cron has one-minute granularity, and intervals that don't map to a clean cron step, such as 7m or 90m, round to the nearest one that does. Claude tells you which interval it picked.

Can /loop run a skill?

Yes, as the prompt: /loop 20m /review-pr 1234 reruns that skill each time. Only skills Claude may invoke on its own run. Built-in commands, skills marked disable-model-invocation, skills withheld by a deny rule and MCP prompts reach Claude as plain text instead.

What is loop.md in Claude Code?

A file that replaces the built-in maintenance prompt for a bare /loop. Claude Code reads .claude/loop.md in the project first, then ~/.claude/loop.md. It's plain Markdown written like the prompt itself, takes effect on the next run, and is ignored when you type a prompt after /loop.

Give the loop rules to follow

A loop runs the same prompt many times without you, so whatever it gets wrong, it gets wrong on repeat. The fix is the same as for any agent: write down how this repository builds, tests and ships, once, where Claude reads it. Our guide to compound engineering for Claude Code shows how. For the other ways to run Claude Code without you, start with our Claude Code automation guide.

#claude-code#Automation#ai-agents#Loop#Scheduled Tasks
Free assessment

Stop guessing. Score your first workflow.

Score one workflow in about five minutes. Nine questions, a grade, and the specific gap holding it back - no call required.