What is loop mode
Imagine it this way: You have an assistant who knows to try, fix it if it fails, and try again. You don't have to keep saying, 'now try again.' It keeps going on its own until it works.
Loop mode is when Claude executes, checks the result, and, if it didn’t work, fixes it and tries again automatically. Instead of approving each step, you define the goal and success criteria, and Claude iterates on its own until it meets them.
In practice, you enable loop mode with flags like --dangerously-skip-permissions or by configuring allowedTools in settings. Claude gets permission to run tools without asking for approval at every step. It's powerful, but requires safety guardrails (topic 3).
In one sentence: loop mode = Claude executes, tests, and fixes things on its own until it meets the success criterion.
When to use vs. interactive
Imagine it this way: You don't leave an intern alone in surgery on their first day. But after months, you let them dress wounds without supervision. Loop mode is wound care; critical tasks are surgery.
Use loop mode when: (1) the success criteria are clear and automatable (tests pass, linter is clean, build works), (2) the actions are reversible (you can git reset), and (3) the scope is limited (it’s not the entire system). Use interactive mode when decisions require human judgment or the risk of error is high.
A good rule of thumb: if you'd trust a competent junior to do it alone, it can be a loop. If you'd review a senior's work before merging, do it interactively. Loop mode isn't laziness. It's smart delegation for tasks with automated feedback.
In one sentence: loop for tasks with automatable criteria and low risk; interactive for judgment calls.
Security Guards
Imagine it this way: A self-driving car has sensors, an emergency brake, and speed limits. Loop mode needs the same: allowed tools, an iteration limit, and isolation.
The three essential guardrails: (1) allowedTools in settings.json limits which tools Claude can use without asking; (2) max turns sets how many iterations to do before stopping; (3) git worktree isolates changes in a separate branch so the main branch stays clean.
Configure before running, not after. A loop without guardrails can run indefinitely, spend tokens, and make unwanted changes. The minimum: restrict allowedTools to read/write/bash, enable a worktree, and create a checkpoint commit before starting.
In one sentence: configure allowedTools, max turns, and worktree BEFORE running the loop. Never afterward.
The loop mode cycle: execute, test, decide, and repeat until the success criteria are met.
Caution: loop without safeguards
A loop without restricted allowedTools can delete important files, run destructive commands, or spend hundreds of dollars on tokens. Configure the guardrails BEFORE starting the loop.
Real-time monitoring
Imagine it this way: You don't put food in the oven and go to sleep. You check on it from time to time. With loop mode, monitoring means watching the terminal while it runs.
While the loop is running, keep the terminal visible. Claude shows what it’s doing in each iteration: which files it read, what it edited, which command it ran, and the result. If you see something strange (editing the wrong file, repeating the same error in a loop), interrupt it with Ctrl+C.
For long loops, use git diff --stat between iterations to see the size of the changes. If the diff is growing too much, it may indicate that the loop is diverging instead of converging. Another sign: if the number of errors doesn't decrease with each iteration, something is wrong.
In one sentence: keep the terminal visible and stop if the diff grows or the errors don't decrease.
Stop at the right point
Imagine it this way: A sculptor stops when the statue is finished. If they keep going, they ruin it. Loop mode is the same: a clear stopping criterion is just as important as a starting criterion.
Set explicit stopping criteria in the prompt: "stop when all tests pass", "stop when the linter returns zero errors", "stop when the build completes successfully". Without a clear criterion, the loop may keep trying to "improve" something that's already good, wasting tokens without making progress.
Watch out for diminishing returns: if the loop has already solved 95% and is spinning its wheels on the remaining 5%, it may be more efficient to stop and handle the rest manually. A good sign of convergence is when each iteration makes fewer changes than the previous one.
In one sentence: explicit stopping criteria in the prompt. Without them, the loop spends tokens endlessly.
Loop mode vs. background agents
Imagine it this way: Loop mode is an assistant in your office working while you have coffee. Background agents are assistants in a remote office you can’t even see. Each has trade-offs.
Loop mode runs locally, in your terminal, with access to your filesystem. Background agents (like those in GitHub Actions or Devin) run on remote servers. Loop mode is quicker to set up, cheaper per iteration, and you can see everything in real time. Background agents scale better and run while you sleep.
In practice, loop mode is ideal for session-based tasks (an afternoon's work). Background agents are better for long-running tasks (running a 2-hour test suite, processing 500 PRs). Most developers start with loop mode and scale up to background agents as needed.
In one sentence: loop mode = local, fast, visible; background agents = remote, scalable, asynchronous.
What’s the prerequisite for using loop mode safely?
Module Summary
Next module:
2-4 — Loop Patterns in Practice: real loop recipes you can copy and run.