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.

Recurring tasks expire seven days after creation and fire while Claude Code is running and idle. Resuming the conversation with --resume or --continue can restore an unexpired task. Use /loop to check a deployment or PR during an open session.

Primary source: Run prompts on a schedule

Choose where the scheduled task runs

Local Desktop tasks start their own sessions, but require the app to stay open and the computer to stay awake. They cannot do the work while that computer is asleep. Cloud scheduled tasks, previously called routines, can run with your computer off. A task listed in Desktop may be local or cloud, so check its execution setting.

For example, a nightly repository check can use a cloud task if its repository and required tools are available there. A check that needs a file stored only on your laptop needs a local task and an awake machine. Before relying on either schedule, inspect a completed run and its test output. A saved schedule alone does not prove the check ran.

Primary source: local and cloud scheduled tasks in Desktop

Choose a runtime with the Loop Operator Kit (email unlock, newsletter optional)

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 bounded agent loop: fix a cart total

Try this in an empty practice folder with Node.js 22 or later. Use the two-file cart exercise linked below: the function adds prices but ignores quantities. This is a teaching example, not a live checkout. The same task can be given to Claude Code or Codex; a repeating /loop schedule is not needed.

Cart exercise: setup, tests and expected output (email unlock, newsletter optional)

1. 01Plan: read cart-total.mjs and cart-total.test.mjs. Run node --test --test-concurrency=2 cart-total.test.mjs before editing. Expect two passes and one failure: 1200 × 2 + 500 should be 2900, but the function returns 1700. If the baseline differs, stop and report it.
2. 02Act: change only cartTotal so each price is multiplied by its quantity. Keep the tests unchanged. Do not add packages, handle unrelated inputs or edit another file.
3. 03Verify: rerun the same command and inspect the changed line. Success requires three passing tests, zero failures and an unchanged test file. Keep the command, exit status and before/after line with the result. If the command cannot run, mark verification incomplete.
4. 04Stop: end successfully when those checks pass. For this exercise, allow at most two repair attempts. After the second failed attempt, stop with the failure output and remaining hypothesis. A missing tool, a needed change outside scope or an unexpected baseline also ends the run without a success claim. Do not commit, push or deploy.

The expected trace is short: reproduce the quantity failure, add the multiplication, rerun the tests, review the diff, stop. Two attempts is a limit chosen for this exercise, not a Claude Code default. In unattended software, the runner must enforce attempt and time limits; writing them in a prompt alone does not enforce them. Passing this fixture only verifies the exercise, not a production payment flow.

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.