Agent Loops in Claude Code: A Working Guide

An agent loop is the cycle an AI agent repeats to finish a task: think, act, observe the result, verify it, then decide whether to go again or stop. A single prompt answers once. A loop keeps going until something tells it the job is done. That something is the part almost nobody designs, and it is the reason most agent runs either stall or quietly produce garbage. I run agents in loops across seven live products, so most of what follows is what broke and what I changed because of it.

What an Agent Loop Actually Is

Take the simplest real example. You tell the agent to fix the failing tests. It reads the code, changes a file, runs the suite, sees three failures, reads the output, changes another file, runs again, sees one failure, fixes it, runs again, green, stops. That whole sequence is one agent loop. The model call is a single step inside it. The loop is the structure around the model calls that decides what happens next and when to quit.

Every agent loop has four parts, whether you designed them or not: a goal, an action space (the tools it can use), a feedback signal (what it learns after acting), and a stop condition. If you never defined the feedback signal or the stop condition, the model invents them, and a model inventing its own definition of done is exactly how you end up with an agent that says the tests pass when it never ran them.

Primary source: How Claude Code works

Why the Loop Became the Bottleneck, Not the Prompt

Prompt engineering was about phrasing one request well enough to get one good answer. That mattered when the model answered once. In a loop, one great answer buys you almost nothing, because pass twelve is going to be built on top of passes one through eleven and nobody checked those. Quality stops being a function of how you asked and becomes a function of how the loop checks itself.

The failures follow a pattern. An agent with no verifier does not usually explode, it drifts. It fixes the test by deleting the assertion. It marks a task complete because the last command exited zero, and the last command was an echo. It refactors a working module because it decided that was implied. None of these look like errors mid-run. They look like progress, which is what makes them expensive. You find them later, in a diff you were not reading closely, or in production.

The Manager Problem: Why Watching an Agent Is Harder Than Coding

Here is the thing people hit around week two with Claude Code and do not have a name for. Writing the code yourself is bounded work: you know what you did. Managing an agent that writes code is unbounded review work, and review is slower per line than writing. So the agent gets faster, and you become the bottleneck, and the natural response is to review less carefully, which is the one response that removes the only safety net in the system.

The way out is not more discipline in reading diffs. It is moving the checking from you to the loop. Every check you can express as a command that exits nonzero is a check you never have to perform with your eyes again. Tests, type checks, lint, a build, a migration dry run, a schema diff. That is the actual job now: converting your judgment into gates the loop can run without you. What is left over, the things that genuinely need a human, is a much shorter list than it feels like at the start.

How to Verify Code Inside an Agent Loop

A verifier is anything that gives the loop an honest yes or no about the state of the world after an action. Ranked by how much I trust them, from most to least:

1. 01A command with a real exit code. The test suite, tsc, the build, a migration check. It cannot be talked into passing, and it is the only category I let run unattended.
2. 02A diff-scoped gate. Lint or tests limited to what actually changed, so a long loop stays fast enough that the agent keeps running it instead of skipping it.
3. 03A second agent reviewing the first one's output against written criteria. Useful for things no command captures, like whether the change matches the issue. Weaker than an exit code, because it is a model checking a model.
4. 04The agent's own claim that it is done. This is not verification. Treat it as a request for review, never as evidence.

Two rules that came out of getting this wrong. First, never let the loop pipe a gate into another command without preserving the exit status, because tee will happily turn a red suite green and the agent will believe it. Second, cap the number of passes. An agent that has failed the same gate five times is not converging, and pass six costs money to learn nothing. Stop and read the output yourself.

Claude Code /loop: What It Does and What It Does Not

Claude Code's /loop runs a prompt or a slash command on a repeating interval. Written as /loop 5m /tests it runs your tests every five minutes. Leave the interval out and Claude picks the cadence itself after each pass, which is what you want when the wait depends on the work rather than the clock.

The limits matter more than the syntax. Recurring tasks expire seven days after creation. They fire only while Claude Code is running and idle, so a closed laptop is a stopped loop. Resuming the same conversation with --resume or --continue restores an unexpired task. That shape makes /loop right for session-scoped polling: watching a deploy finish, babysitting an open PR, rerunning checks while you work on something else in the same window. It is the wrong tool for anything that has to survive you closing the terminal. For that, use Routines, Desktop scheduled tasks, or GitHub Actions, which run whether or not you are there.

Primary source: Run prompts on a schedule

Loop Engineering: The Four Things I Check Before Starting One

Loop engineering is just designing those four parts on purpose instead of letting the model guess them. Before I start any loop, autonomous or not, I answer these:

• What is the stop condition, stated as something a machine can evaluate. Not "until it works", but "until npm test exits zero" or "until the PR check is green". No stop condition is the single most common cause of an agent running off the rails.
• What is the verifier, and can it be fooled. If the only proof is the agent's own summary, there is no verifier and the loop is open whether I admit it or not.
• Open or closed. A closed loop runs to completion on its own and needs a strong verifier. An open loop puts a human at the decisions that are irreversible. Anything touching production data, money, or a public surface is open, permanently.
• How narrow is the scope. A loop aimed at one module converges. A loop aimed at "improve the codebase" wanders, because every pass changes what the next pass sees.

A Loop I Actually Run

My blog pipeline runs on a schedule: it drafts a post in Hebrew, builds the site, opens a PR, and sends me a message. Every part of it is chosen against the list above. The stop condition is my merge. The verifier is the build, so a draft that breaks the site never reaches a PR at all, and I never see it. The scope is one post, not the blog. It is an open loop on purpose, because publishing under my name is not reversible in the way a code change is.

The lesson that generalizes: the more autonomy you give a loop, the stronger the verifier has to be, and the two have to move together. Add autonomy without adding verification and you have not saved work, you have moved it downstream to a version of yourself who has less context and a live user waiting. That is the whole trade. Everything else is syntax.