Loops

A loop is Claude repeating a cycle of work until a stop condition is met. Four kinds, from a single prompt to a routine that runs with no one watching, and when to reach for each.

What it is

There is a lot of talk about "loop engineering" right now, and nearly as many definitions. The Claude Code team uses a narrow one: a loop is an agent repeating cycles of work until a stop condition is met.

So every loop answers two questions. What starts the next cycle, and what stops it? The four kinds on this page are four different answers. Each one also hands Claude one more piece of your job: first the check, then the stop condition, then the trigger, and finally the prompt itself.

Not every task needs a complex loop. Start with the simplest one that works, and move down the list only when the work calls for it.

Turn-based loops

• Starts: when you send a prompt.
• Stops: when Claude judges the task is done, or needs more from you.
• Best for: short tasks that are not part of a regular process or schedule.
• Cost control: a specific prompt, and a check Claude can run itself, so it needs fewer turns.

Every prompt already starts a loop. Claude gathers context, takes action, checks its work, repeats if it needs to, and answers. That cycle is the agentic loop, and you steer it one turn at a time.

Ask Claude to add a like button. It reads your code, makes the edit, runs the tests, and hands back something it believes works. Then you open the browser, click the button, and write the next prompt. That checking step is the first thing to hand off.

Write the checks you do by hand into a skill, and give Claude tools to see, measure, or interact with the result. The more a check comes down to numbers, the easier it is for Claude to judge its own work.

---
name: verify-frontend-change
description: Verifies a UI change end to end before it is reported as done. Use after any edit to a page, component, or style.
---
# Verifying frontend changes
Never report a UI change as done just because the edit succeeded. Check it the way a reviewer would:

1. Start the dev server and open the edited page in the browser.
2. Use the change. For a new control, click it, confirm the state changes, and take a screenshot before and after.
3. Check the browser console. There must be zero new errors or warnings.
4. Run a performance trace with the Chrome DevTools MCP server and check Core Web Vitals.

If any step fails, fix it and start again from step 1. Never hand back work that is only partly verified.

• Step 4 needs the Chrome DevTools MCP server. A check is only as good as the tools Claude has to run it.
• "Zero new errors" is a number. "Looks right" is not.

Goal-based loops

• Starts: when you set a goal with /goal.
• Stops: when the goal is met, or the cap you set runs out.
• Best for: tasks with an exit Claude can prove, like tests passing or a score over a threshold.
• Cost control: a specific finish line, and an explicit cap like "stop after 5 tries".

Bigger tasks rarely finish in one turn. Agents do better when they can iterate, and /goal lets you decide how long Claude keeps going.

Without a goal, Claude decides what "good enough" means, and it can stop early. With one, a separate model checks your condition every time Claude tries to stop, and sends it back to work until the condition holds. That is why hard numbers work so well here. A test count or a score threshold leaves nothing to interpret.

/goal npm test exits 0 with no test files edited or skipped, or stop after 10 turns

• Setting a goal starts work right away. The condition is the instruction, so no separate prompt is needed.
• "npm test exits 0" is both the end state and a check Claude proves by running it.
• "No test files edited or skipped" closes the easy shortcut: changing the tests instead of the code.
• "Or stop after 10 turns" is the budget. Claude reports progress against it every turn.

Write a condition that holds up

The evaluator only judges what Claude has shown in the conversation. It does not run commands or read files. So a good condition has:

• One measurable end state: a test result, an exit code, a file count, an empty queue.
• A stated check: how Claude proves it, such as "npm test exits 0" or "git status is clean".
• Constraints that matter: what must not change on the way there.
• A cap: a turn or time limit, such as "or stop after 20 turns".

A condition can be up to 4,000 characters.

Goal commands

• One goal per session. Resuming a session restores an active goal, with its turn count and timer reset.
• If Claude keeps answering the evaluator without using any tools for several turns in a row, Claude Code stops the loop and hands control back, with the goal still set.

Under the hood, /goal is a session-scoped, prompt-based Stop hook. So it follows the same rules as hooks: it only works in a trusted folder, and it is unavailable when disableAllHooks is true or managed settings set allowManagedHooksOnly. If you want the same check in every session, write the Stop hook yourself.

Time-based loops

• Starts: when an interval passes.
• Stops: when you cancel it, or the work is done (the PR merges, the queue is empty).
• Best for: recurring work, and work that waits on a system outside your project.
• Cost control: longer intervals, or reacting to events instead of the clock.

Some work repeats. The task stays the same and only the inputs change, like summarizing Slack every morning. Other work waits on something outside your project, like a PR that might get review comments or fail CI. The simple way to handle it is to check on an interval and react to what changed.

/loop 5m check my PR, address review comments, and fix failing CI

What you give /loop decides how it runs:

• Intervals take s, m, h, or d. Seconds round up to a minute, and odd steps like 7m round to the nearest clean one. Claude tells you what it picked.
• The prompt can be a skill: /loop 20m /review-pr 1234. Only skills Claude may call on its own will run. One marked disable-model-invocation: true (see Slash commands) arrives as plain text instead.
• The built-in maintenance prompt finishes open work, tends to the current branch's PR (review comments, failed CI, merge conflicts), then runs cleanup passes. It does not start anything new.

Set your own default with loop.md

Check the release/next PR. If CI is red, read the failing job log,
find the cause, and push a minimal fix. If new review comments came in,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.

• .claude/loop.md belongs to the project and wins over ~/.claude/loop.md, which covers any project without its own.
• It is used only when you give /loop no prompt. A prompt you type after /loop replaces it.
• Edits apply on the next run, so you can tune it while the loop is going. Anything past 25,000 bytes is cut off.

Stopping, and what /loop cannot do

• Press Esc to stop a self-paced loop while it waits for its next run.
• A loop on a fixed interval runs until you cancel it ("cancel the deploy check job") or for seven days. On day seven it runs one last time, then deletes itself.
• /loop lives in your session. It fires only while Claude Code is open and idle, between turns, never mid-reply. Close the session and it stops.
• If Claude is busy when a run is due, it runs once when Claude is free, not once for every run it missed.

Move it to the cloud with /schedule

/loop stops when your laptop does. /schedule saves the work as a routine instead: a prompt, one or more repositories, and the connectors it needs, run on Anthropic's cloud.

/schedule weekdays at 9:07, summarize yesterday's merged PRs

• 9:07, not 9:00. A run set exactly on the hour can start several minutes late.
• Besides a schedule, a routine can start from an HTTP call or a GitHub event, such as a new pull request. Reacting to an event is often cheaper than checking on a timer.
• Routines are in research preview and need a claude.ai subscription: Pro, Max, Team, or Enterprise. If you sign in with an API key or a cloud provider, /schedule does not show up at all.
• /schedule list, /schedule update, and /schedule run manage routines from the CLI. Everything else is at claude.ai/code/routines.

The Desktop app has a third option, a local scheduled task. Here is how the three compare:

Proactive loops

• Starts: on an event or a schedule, with no one watching.
• Stops: each task stops when its goal is met. The routine runs until you turn it off.
• Best for: steady streams of well-defined work, like bug reports, issue triage, migrations, and dependency upgrades.
• Cost control: run the routine on a smaller, faster model, and save the most capable one for judgment calls.

A proactive loop is not a new command. It is the pieces above, put together so work gets picked up and finished without anyone typing a prompt. To handle incoming bug reports:

1. /schedule runs a routine that checks for new reports.
2. /goal says what done looks like, and skills say how to verify it.
3. A workflow runs agents that triage each report, fix it, and review the fix.
4. Auto mode keeps a local loop from stopping to ask permission. A cloud routine already runs without prompts.

Put together, the prompt could look like this:

/schedule every hour: check #project-feedback for bug reports.
/goal: do not stop until every report found this run is triaged, acted on, and answered.
When fixing a bug, use a workflow to try three solutions in parallel worktrees,
and have a judge review them adversarially.

• The prompt asks for a workflow by name. Claude only launches one when you ask.
• The routine's form has a model picker next to the prompt. That is where you route it to a smaller model.

Keeping quality up

What a loop produces is only as good as the system around it.

• Keep the codebase clean. Claude follows the patterns already in your code, the good ones and the bad ones.
• Give Claude a way to check its work. Write down what good looks like for your team as skills.
• Make docs easy to reach. Framework and library docs carry the current best practice.
• Use a second agent to review. A reviewer with fresh context is not swayed by the main agent's reasoning. The built-in /code-review skill does this, and so does Code Review for GitHub. Loops that write code need loops that check it.

When one result misses the bar, do not stop at fixing that result. Put the fix into the system, as a skill, a hook, or a line in CLAUDE.md, so every later run gets it too.

Keeping cost down

Every trip around a loop spends tokens. Give each loop clear limits:

• Pick the right tool and model. Small tasks do not need several agents, or a loop at all. Plenty of work runs fine on a cheaper, faster model.
• Say what done looks like. A clear finish line gets Claude there sooner, but not too soon.
• Pilot before a big run. A workflow can spawn hundreds of agents. Try a small slice first and see what it costs.
• Use scripts for fixed steps. Running a script costs less than reasoning through the same steps again. A PDF skill can ship a form-filling script, so Claude runs it instead of rewriting it each time.
• Do not run routines more often than needed. Match the interval to how often the thing you watch actually changes.
• Check where the tokens go. /usage breaks recent usage down by skills, subagents, and MCP servers. /goal with no arguments shows turns and tokens so far. /workflows shows each agent's usage and lets you stop any of them.

Your model and effort level are among the biggest levers on what a loop costs.

Which loop to reach for

To get started, look at work you already do. Pick one task where you are the bottleneck and ask which piece you could hand off. Can you write the check? Is the goal clear enough to state? Does the work arrive on a schedule? Then run the loop, watch where it stalls or goes too far, and adjust.

When not to use one

A loop earns its cost when the work repeats or needs many turns. A quick question or a small edit is already a turn-based loop, so do not wrap it in /goal. If the steps are fixed and never change, write them as a workflow. If a check must hold in every session, not just this one, make it a Stop hook in your settings instead of a /goal.