Claude Code Loop Guide: /loop, /goal, and the Cron Loop Behind 1,800+ Unattended Runs (2026)

Type /loop 5m check the deploy and Claude Code will keep checking your deploy every five minutes until you tell it to stop. That’s the Claude Code loop most people mean, and it’s a great tool. It also stops working when you close your laptop, and it deletes itself after seven days.

I run ten businesses on unattended Claude Code agents, and this container alone has written more than 1,800 run logs since June 12, 2026. None of those runs used /loop. That’s not because /loop is bad. It’s because it was built for a different job.

This Claude Code loop guide covers both jobs. You’ll get the three kinds of loop in Claude Code, exactly how /loop behaves (intervals, self-pacing, loop.md, the jitter, the 7-day expiry), how it compares to /goal, Stop hooks and the bash-style “Ralph” loop, and the cron loop that runs my fleet. All the numbers come from the official docs as of October 2026 or from my own logs, and I’ll tell you which is which.

What a Claude Code Loop Actually Is (There Are Three)

Most articles in this search treat “loop” as one idea. There are really three loops in Claude Code, stacked inside each other. Most confusion comes from mixing them up.

Loop 1: the agent loop (inside one turn)

Every Claude Code turn is already a loop. Claude reads your prompt, calls a tool, reads the result, and decides what to do next. It keeps going until it thinks the task is done. You get this for free. You never type anything to turn it on.

Loop 2: the session loop (between turns)

This is where /loop and /goal live. They keep one open session going after a turn would normally hand control back to you. /loop starts the next turn when a time interval passes. /goal starts it when a separate evaluator decides your condition isn’t met yet.

Loop 3: the outer loop (between sessions)

This one starts a brand-new Claude Code session on a schedule, does one job, and exits. Cron plus claude -p, Anthropic’s cloud scheduled tasks, Desktop scheduled tasks and GitHub Actions all live here. My fleet lives here too. It’s the top rung of the autonomy ladder I laid out in what an AI coding agent actually is.

Loop	What starts the next pass	Survives closing the terminal?	Best for
Agent loop	The last tool result	n/a (one turn)	Every task, automatically
/loop	A time interval, fixed or chosen by Claude	No	Polling while you work
/goal	The previous turn finishing, if the condition isn’t met	No (restored on resume)	Grinding toward a checkable end state
Outer loop (cron, cloud, Desktop, CI)	A clock or an event	Yes	Unattended recurring work

Pick your Claude Code loop by asking one question: does a human have this session open? If yes, use a session loop. If the work has to happen at 3am while you sleep, you need the outer loop. Running a session loop for that is like leaving a terminal open and hoping.

How /loop Works: Fixed Intervals, Self-Pacing, and loop.md

/loop is a bundled skill. Both arguments are optional, and what you give it decides how it behaves.

You type	What happens
/loop 5m check the deploy	Your prompt runs on a fixed schedule (converted to cron)
/loop check the deploy	Self-paced: Claude picks a delay between 1 minute and 1 hour after each pass
/loop or /loop 15m	Runs your loop.md if you have one, otherwise the built-in maintenance prompt

Fixed interval

Give it an interval and Claude turns it into a cron expression, schedules it, and confirms the job ID. Units are s, m, h and d. The interval can come first (30m) or last (“every 2 hours”). Seconds round up to a full minute, because cron can’t schedule anything finer than one minute. Intervals that don’t divide cleanly, like 7m or 90m, get rounded to the nearest one that does, and Claude tells you which one it picked.

Self-paced

Leave the interval out and Claude chooses the gap each time, based on what it saw. It waits less while a build is finishing and longer when nothing is happening. It prints the delay and the reason at the end of every pass, so you can see its thinking. A self-paced loop can also end itself once the work is done. Under the hood, Claude calls its ScheduleWakeup tool with stop: true. If a pass ends without either scheduling the next one or stopping, Claude Code sets one backup wakeup about 20 minutes later. If that pass doesn’t schedule anything either, the loop ends.

Bare /loop and loop.md

A bare /loop runs a built-in maintenance prompt. It finishes unfinished work, looks after the current branch’s PR (review comments, failed CI, merge conflicts), then does cleanup like bug hunts. It won’t start new projects. Risky steps like pushing or deleting only go ahead if the conversation already approved them.

To use your own default prompt, create .claude/loop.md (project) or ~/.claude/loop.md (user). The project file wins if both exist. Write it like you’re typing the prompt. Changes take effect on the next pass, so you can adjust it while the loop runs. Anything past 25,000 bytes gets cut off.

You can also loop a skill: /loop 20m /review-pr 1234. There’s a catch, though. A scheduled run only executes skills Claude is allowed to call on its own. Built-in commands like /model, skills marked disable-model-invocation: true, and MCP prompts arrive as plain text instead of running. If your looped skill “does nothing”, check that first.

Stopping it

This one catches people out. A self-paced loop stops when you press Esc while it’s waiting. A fixed-interval loop ignores Esc and Ctrl+C. You have to ask Claude to cancel it (“cancel the deploy check loop”), or it runs until the seven-day expiry. The tools underneath are CronCreate, CronList and CronDelete. Each task gets an 8-character ID, and one session can hold up to 50.

The Fine Print: Jitter, the 7-Day Expiry, and What Happens When You Close the Lid

Most of the top-ranking guides for this term skip these limits. Every one of them matters if you’re tempted to treat /loop as a scheduler.

Behavior	What the docs say (Oct 2026)	What it means for you
Session must be open	Tasks only fire while Claude Code is running and idle	Close the terminal and the loop stops. A background session can carry it.
Busy session	A due prompt waits until the current turn ends	Your “every 5 minutes” can slip while Claude is mid-task
Missed runs	No catch-up: fires once when idle, not once per missed interval	Don’t use it for anything that has to count runs
Jitter (recurring)	Runs late by up to half the gap, capped at 30 minutes. Hourly or daily runs start 0–30 min late.	A “9am” daily check might run at 9:27
Jitter (every 5 min)	*/5 runs 4m45s after the previous run	Fast polls stay tight (they beat the 5-minute prompt cache)
One-shot on :00 or :30	Can run up to 90 seconds early	Schedule reminders at odd minutes like 3 9 * * *
Expiry	Recurring tasks fire one last time and delete themselves 7 days after creation	A weekly-forever job isn’t possible here
Resume	Cron tasks are restored on --resume; a self-paced /loop is not	Re-run /loop after a restart
Kill switch	CLAUDE_CODE_DISABLE_CRON=1 disables the scheduler and /loop	Useful in shared or CI environments

Times use your local timezone, not UTC. The docs’ own comparison table sets the floor at one minute for /loop, one hour for cloud scheduled tasks, and one minute for Desktop tasks when Claude sets them (one hour in the form).

The seven-day expiry is a feature, not a bug. It’s there so a loop you forgot about can’t burn tokens for a month. If that limit annoys you, your job needs the outer loop.

Here’s the expiry against my own calendar. This container has been running for 137 days. A /loop doing the same work would have expired and needed recreating about 19 times, and only while a terminal was open the whole time.

/loop vs /goal vs Stop Hooks vs the Ralph Loop

“Claude Code loop” now covers four different tools. Here’s how to choose.

/goal: loop until a condition is true

/goal all tests in test/auth pass and the lint step is clean starts a turn right away. After each turn, a separate model checks whether the condition holds. If it doesn’t, Claude starts another turn. The goal clears when the condition is met, when the evaluator thinks it’s impossible, or when you run /goal clear. You get one goal per session, and the condition can be up to 4,000 characters.

Two details matter. First, the evaluator doesn’t run commands or read files itself. It only judges what Claude has put in the conversation. So write conditions Claude can prove with output, like “npm test exits 0″. Second, /goal doesn’t change your permission mode. In Manual mode it still stops and asks before tool calls you haven’t allowed. Add a limit like “or stop after 20 turns” so it can’t run forever.

Stop hook: the permanent version of /goal

A Stop hook also fires after every turn, but it lives in your settings file and applies to every session in that scope. It can run a script for checks that must be exact, or a prompt for checks that need judgment. Use /goal for one-off work and a Stop hook for a rule you want every time.

The Ralph loop: bash around the whole thing

Before any of this was built in, people wrapped Claude in a shell while loop that kept feeding the same PROMPT.md into a fresh run. Geoffrey Huntley popularized the “Ralph” name for it. Each pass starts with a clean context and reads its progress from files on disk. It works, and it’s brutally simple. It also has no built-in stop rule, no budget cap and no schedule. You have to add all three yourself.

You want to…	Use
Check something every few minutes while you work	/loop 5m …
Babysit a PR without picking a cadence	/loop … (self-paced)
Grind until tests pass or the backlog is empty	/goal … (with a turn cap)
Enforce “never stop until X” in every session	Stop hook
Run a big job in fresh contexts until it’s done	Ralph-style bash loop (add a cap)
Run a job every day forever, laptop closed	Outer loop: cron + claude -p, cloud or Desktop scheduled tasks, or GitHub Actions

The Loop I Actually Run: Cron Plus a Fresh Claude Session, 1,800+ Times

Here’s the Claude Code loop behind this site: an outer loop, and boring on purpose. A plain scheduler reads schedule.json and calls a shell dispatcher at each slot. The dispatcher starts a brand-new headless Claude Code session with one instruction: read this skill file and run it.

claude --print --dangerously-skip-permissions -p "$INSTRUCTION" < /dev/null

That flag only makes sense because each brand runs in its own locked-down Docker container. I covered the setup in my Claude Code sandbox write-up. Don’t copy that line onto your laptop.

The numbers (measured from this container’s logs, October 26, 2026)

Metric	Value
Run logs since June 12, 2026	1,806 across 137 days
Active daily slots	12 (every one at :07 past the hour)
Active weekly slots	10 (at :07 or :37, never on the hour)
Per-slot timeout	30 to 90 minutes (this blog writer gets 90)
Runs, Sep 26 – Oct 25	402 across 20 skills
Ended success / skip / fail	369 / 16 / 1
No result line at all	16
/loop or /goal calls in production	0

Why the outer loop wins for unattended work

• Fresh context every run. Each job starts clean and reads what it needs from files: its skill, CLAUDE.md and a memory log. A session that loops for days piles up context. Mine never goes past one job.
• A hard timeout per slot. If a run hangs, the scheduler kills it. A runaway /goal only stops when the evaluator says so.
• A lock per slot. The dispatcher writes a lock file named for the date, slot and task. Only the first one to arrive gets to run, and old locks are cleaned up daily. Two schedulers firing at once can’t publish two posts.
• A result line you can count. Every skill must end with SKILL_RESULT: success|skip|fail. That’s how I can give you the table above. The 16 runs with no result line are my current weak spot. They exited cleanly, printed a nice summary, and skipped the one line a script can count.
• Odd-minute slots. Nothing fires on the hour. Daily slots sit at :07, weekly ones at :07 or :37. That’s the same advice the docs give for one-shot tasks, and it keeps my jobs away from the top-of-the-hour rush on every API I call.

So where does /loop fit for me? In the interactive sessions where I change the fleet: watching a slow deploy, or babysitting a branch while I review something else. That’s exactly the job it was built for. One warning, though: unattended doesn’t mean unreviewed. My agents have filed hundreds of approval cards, and a human in the loop only counts if someone closes the loop.

If you want this outer-loop pattern running your own recurring work (content, inbox triage, lead follow-up) without the months of trial and error, that’s what my done-for-you automation builds are for. The Claude Code best practices post covers the rules I’d set up first.

Claude Code Loop Recipes You Can Copy Today

Five patterns, from the smallest to the biggest. Each one has a clear way to stop, because a Claude Code loop without one is just a bill.

1. Deploy watcher (fixed, short-lived)

/loop 2m check whether the production deploy finished. If it failed, pull the
error log and summarize the cause. When it succeeds or fails, tell me and
cancel this loop.

2. PR babysitter (self-paced)

/loop check PR 1234: if CI is red, read the failing job log and push the
smallest fix; if there are new review comments, address each one. If it's
green and quiet, say so in one line. Stop when the PR is merged.

3. A project loop.md

# .claude/loop.md
Check the release/next PR. Fix red CI with the smallest possible change.
Answer new review comments. Never push to main. Never delete branches.
If nothing needs doing, reply "quiet" and wait longer next time.

4. Goal with a ceiling

/goal every file in src/legacy/ imports from the new api client, `npm test`
exits 0, and no test file is modified, or stop after 25 turns and report
what's left.

5. The outer loop in about 10 lines

# crontab: 7 past every hour, never on the hour
7 * * * * /opt/agents/run-job.sh inbox-triage

# run-job.sh
#!/usr/bin/env bash
set -euo pipefail
LOCK="/tmp/$(date +%F-%H)-$1.lock"
( set -o noclobber; : > "$LOCK" ) 2>/dev/null || exit 0
timeout 30m claude -p "Read skills/$1.md and run it. End with SKILL_RESULT: success|skip|fail" \
  < /dev/null >> "/var/log/agents/$(date +%F_%H-%M)_$1.log" 2>&1

Recipe 5 is a starter, not my exact script. Before you run it unattended, add permission rules (or a sandbox) and an alert. I send a Telegram message on every bad run. And if a job keeps “checking in” without changing anything, read my numbers on whether proactive agents are worth it before you add more loops.

Claude Code Loop FAQ

How do I make Claude Code loop until a task is done?

Use /goal with a condition Claude can prove in its output, plus a turn limit. For example: “npm test exits 0, or stop after 20 turns.” Use /loop without an interval if “done” is about time passing, like a deploy finishing. Claude can end a self-paced loop itself.

Does /loop keep running after I close the terminal?

No. Session-scoped tasks only fire while Claude Code is running and idle. Moving the session to the background carries /loop tasks over. For anything that has to survive a closed laptop, use cloud scheduled tasks, Desktop scheduled tasks, GitHub Actions, or cron with claude -p.

How do I stop a Claude Code loop?

For a self-paced loop, press Esc while it’s waiting. For a fixed-interval loop like /loop 5m, ask Claude to cancel it, or ask “what scheduled tasks do I have?” and cancel by ID. Esc won’t stop those.

What’s the shortest interval?

One minute. Cron can’t go finer, so 30s rounds up to 1m.

Why did my loop expire?

Recurring session tasks delete themselves seven days after you create them, after one final run. Recreate it before then, or move the job to an outer loop.

Is /loop the same as a Ralph loop?

No. /loop re-runs a prompt inside one session on a timer. A Ralph-style loop is a shell while loop that starts a fresh Claude run each time, with progress saved in files. The Ralph loop gets a clean context every pass. /loop keeps the session’s context, which helps for short monitoring and hurts over long runs.

Do loops cost more?

Every pass is a full model turn, so yes. That’s why self-paced loops wait longer when nothing’s happening and why */5 polls start a bit early to stay inside the prompt cache. Cap turns on /goal, cap time on outer loops, and cancel /loop jobs you’ve stopped watching.

Final Thoughts: Pick the Loop by Who’s Watching

A Claude Code loop isn’t one feature. It’s a choice of where the repeating happens. Inside a turn, Claude already loops for you. Inside a session, /loop handles timing and /goal handles finish lines, and both are excellent while you’re there to watch. Outside the session, a plain scheduler starting a fresh claude -p run is what keeps working at 3am. It’s run this site’s ten-brand fleet over 1,800 times without anyone watching.

Start small. Put a /loop on your next deploy. Once a job has run the same way for a week, move it to the outer loop and give it a timeout, a lock and a result line you can count. And if you’d rather skip the trial and error, book an automation strategy session and we’ll work out which of your jobs should loop at all.