Loop engineering is designing what happens around an AI agent between its turns and across its runs. It covers the check that decides whether a result stands and the cap that ends a run. It also covers the trigger that starts a run, and the review of traces that changes the harness for the next one. Bigcircle has built the check, the cap and the trace on two agents in production, and on both they sit in the harness rather than in the prompt.
Key facts
Definition
Loop engineering builds the controls between an agent's turns and across its runs, so a run with no person prompting it still ends, is checked against the system it changed, and leaves a trace that says why it stopped.
How Bigcircle does it
- On Skionis, Bigcircle's validation loop checks each template against the live AWS account, and a template that will not come clean after bounded revision goes to a person as a request the agent cannot safely fulfil.
- On Solarpunk, Bigcircle compares the agent's claimed completion with the state of the application, and the trace separates a planning defect from an outage, an expired session or stale state.
- In Bigcircle's harness work, a change to the prompt, the model, the tools or the harness clears an eval suite in CI built from real traffic before it merges.
Comparison
A /goal condition in Claude Code is judged by a model reading the conversation, while a Stop hook script can run the tests itself and keep its own turn count.
Key number
A pull request Simon Maple of Tessl described ran 66 review rounds, kept going after a person said stop, and cost roughly $800.
On Skionis, a DevOps agent we shipped on a live AWS account, a validation loop checks each generated template against the account before an engineer sees it. We measured template errors before deploy falling from around 10% to 4% across the loop's introduction.
On Solarpunk, a desktop agent we built for executive operations, a critic decides after every step whether to continue, retry or escalate. The run then compares what the agent says it finished with the real state of the application. In both systems, the decision to accept a result rests on the system the agent changed and not on the agent's own account of it.
Most of what ranks for the term lists the parts of a loop. We cover the decisions underneath those parts: what the check should read, where the cap is enforced, and what changes when an event starts the run. After that come the failures that should change the harness and the places a person stays. Then we set loop engineering beside harness engineering, the layer it is most often confused with. Claude Code gets its own section, because its commands cover part of this and leave the rest to you. The guide ends with the cases where a loop is the wrong tool.
For the short definition, and the four loops that DeepLearning.AI's course names, see our loop engineering glossary entry. This guide assumes the definition and goes into the build.
What does an AI agent loop need before it runs unattended?
An agent is already a loop. The model picks an action, a tool call runs it, the result comes back, and the model picks again. Loop engineering adds controls around that cycle, and each one answers a question the model should not be the one to answer.
Give each control a home outside anything the agent can edit. A control the agent can change is one more thing the agent decides, and the point of the control is that it does not. The table lists the controls, where each belongs, and what breaks when it is missing.
| Control | Question it answers | Where it belongs | What happens without it |
|---|---|---|---|
| Exit check | Is the result right? | A check that reads the system the agent changed | The agent's own "done" ends the run, true or not |
| Round cap | How many attempts? | The harness, checked before each round | A failing loop retries until someone notices the bill |
| Budget | How much may this run spend? | The harness, beside the round cap | A long run looks like progress while it spends tokens |
| Stop | Can a person end it now? | A flag the harness reads before each round | A stop sent as a message competes with everything else in the context |
| Trigger | What starts a run? | An event deduplicated on its ID | One message delivered twice starts two runs |
| Stop reason | Why did it end? | A field on the trace of every run | Every failed run becomes a model investigation |
Read the figure from left to right, one round at a time. The orange gate runs before every round and the blue turn is the only step the model takes. The green check answers to the system rather than to the agent.
Keep the gate in code, for the reason our harness work enforces permission scope in code the agent cannot edit. A rule the model reads is a rule the model can reason its way past. A rule the harness checks does not depend on the model at all, so put the cap, the budget and the stop flag in one check that runs before each round.
Why should the check read the system, not the transcript?
Most writing on loop engineering recommends a maker and a checker. One agent does the work, and a second agent with different instructions grades it. Keep that split, and then decide what the checker reads. A checker that reads the conversation is reading the maker's account of the work, and a confident summary of a test run looks the same as a test run.
Claude Code's /goal command shows the gap plainly. As of 1 November 2026, its evaluator judges the condition against what has surfaced in the conversation, and it does not run commands or read files on its own. That works when the transcript holds the real test output. It fails quietly when the agent paraphrases the output, or when the condition asks about something the transcript never shows.
On Skionis we check against the account. A schema check only tells you a template is well formed, and only the account tells you it will apply. So the validation loop reads live limits, quotas, regions and existing resources, and most errors die there before AWS is asked to start anything.
On Solarpunk the critic's verdict is not the last word. We compare the agent's claimed completion with the state of the target application, and that comparison catches work the agent reported as done that never happened. Our guide on why AI agents report unfinished work as done covers that read in detail.
Write the check so the agent cannot pass it by changing it. A loop allowed to edit the test suite can turn a failing run green by deleting the test, and the run will then report success. Keep the check's files outside the paths the agent can write. Put the constraints in the check itself: no test file modified, no check skipped, and no file outside the task touched.
The watcher needs the same protection as the test. In OpenAI's misalignment report, updated 20 October 2026, a coding agent removed a monitoring integration and then denied removing it. A check the agent can reach is a check the agent can switch off, whether or not anyone asked it to.
Order the checks so certainty comes before judgment, and run the deterministic ones first: the build, the tests, the schema and a read of the target system. Use a model as judge only for what code cannot decide, such as whether an analysis answers the question it was given. Score that judge against human labels before it gates anything, with the method in how to build LLM evals.
How do you cap an AI agent loop and its cost?
Cap the rounds in the harness, and set the number from runs that worked. AI Native Dev shared an account from Simon Maple of Tessl about a pull request whose agent ran 66 review rounds. It kept going after a person said stop, and it cost roughly $800.
Record how many rounds your good runs take in testing, and set the cap above the slowest of them. A run still failing past that point usually has a cause another round will not fix. The plan is wrong, a permission is missing, or a dependency is down.
Keep separate counters for separate kinds of retry. On Skionis, retries sit in two places: inside the validation loop, and around execution against the provider. They recover from different things, a malformed template in one case and a transient or partial provider failure in the other. Give each its own cap, since one shared counter lets a flaky provider spend the attempts meant for fixing the output, and the run then escalates with the wrong reason on it.
Count rounds without progress as well as rounds. Claude Code stops a goal loop when the agent keeps answering the evaluator with no tool use for several turns in a row, which is a progress check rather than a round count. Track whether the system's state changed between rounds, not only whether a tool ran. A run that edits the same file back and forth is not making progress, even though every round has a tool call in it.
Do not leave the cap to the model. Claude Code's advice for bounding a goal is to write a clause such as "or stop after 20 turns" into the condition, and the evaluator judges that clause from the conversation. That is a cap the model reports on, so pair it with a counter the harness owns.
Maple's pull request also kept running after a person asked it to halt. Make the stop a state the harness reads before each round. A stop sent as a message is one more instruction competing with everything else in the context, and it loses often enough to matter.
Put a token or dollar budget beside the round cap, and check both before every round. OpenAI's Codex Goals continue from the latest state only while the goal stays active and within budget. The Pragmatic Engineer heard from developers who dropped loops after trying them, and at companies paying API prices for tokens, loops get expensive fast. Our guide on AI agent cost covers how to price a run before you schedule a thousand of them.
When a run hits a cap, hand it to a person rather than letting it widen its own scope. On Skionis, a template that will not come clean after bounded revision goes to a person as a request the agent cannot safely fulfil. We bound Solarpunk's retries for the same reason. An agent that retries indefinitely against a broken vendor is worse than one that stops, because it burns cost and time while looking busy.
What changes when an event starts the run?
Nobody is watching when a triggered run begins, so the harness has to assume that. Gergely Orosz asked his readers how they use loops and drew around 210 replies. Two of the most common uses were triggers and scheduled jobs: an agent that starts on a new error, a new ticket or a timer. That is old automation with a model in the middle, and it inherits the old failures as well as the new ones.
Deduplicate every event on its ID before a run starts. Queues and webhooks deliver the same message twice, and two runs on one ticket will open two pull requests or send two replies. Make every write the agent can make safe to repeat, so a run that crashed halfway can be retried without doing the first half twice.
Limit concurrent runs per target as well, because a burst of alerts on one service should start one investigation, not ten that each open a fix for the same fault.
Give a triggered run the same permission scope and approval points as a run a person started. Enforce them in the tool, not in the prompt, as our guide to human in the loop AI agents sets out. A triggered run that needs approval will often ask at an hour when nobody answers. Decide in advance that it parks with its state saved somewhere it can resume from, so the approval does not start the work over.
Put an expiry on every scheduled loop. Claude Code expires recurring session tasks 7 days after creation, as of 1 November 2026, which bounds how long a forgotten loop can run. Build the same limit into any scheduler you write, and make renewal a decision someone takes. A loop nobody remembers keeps spending against a goal nobody still holds.
Which failures should change the harness?
The loop that learns from traces changes the system the other loops run inside, so we give it the most care. DeepLearning.AI's course calls it the hill-climbing loop. It reads traces from many runs, finds the failures that repeat, and changes the harness. Our harness work starts from the same input, with a real run traced end to end before anything changes.
Record a stop reason on every run before you try to learn from any of them. Keep the reasons short: the check passed, the check failed past its cap, the budget ran out, there was no progress, a person stopped it, or it escalated.
On Solarpunk, each trace also tells a planning defect apart from a provider outage, an expired session, stale state or an unsupported action. Count runs by reason before changing anything. The largest class is often an environment problem that no harness change will fix.
Feed only the planning defects back into the harness. A loop that learns from outages changes the agent to work around failures that were never the agent's, and the workaround stays after the vendor recovers. On Skionis, every validation failure and its revision sit in one record with the request and the result. Those failures are the system's own log of what the model gets wrong, and we use them to improve the loop rather than the prompt.
Count people's corrections as traces too, and weight them above the automated ones. On the trademark drafting platform, we treat attorney corrections as the most valuable signal in the system, because they measure the gap automated scoring cannot see. A loop that learns only from automated checks gets better at passing those checks, and no better at the work a person still fixes by hand.
Merge every harness change through the same gate as any other change. Ours is an eval suite in CI built from cases pulled from real traffic. A change to the prompt, the model, the tools or the harness has to clear it before it merges.
A change found by reading traces fixes the runs it was found in, and only the rest of the suite shows what it broke. Keep that gate, the permission scope and the trace itself outside anything a loop can edit. A loop told to raise a pass rate can raise it by weakening the check.
Where do people stay in the loop?
People stay where the loop cannot check itself: at the goal, at the irreversible change, and at the escalation. A loop that runs well makes it tempting to stop reading what it produces. The result is a codebase or a ledger that nobody on the team understands, so decide where each person reads before deciding how often.
Design the review surface before the review cadence. On Skionis, the human gate is an architecture diagram of what will exist after the change. The alternative is raw template diffs, and engineers do not read those carefully at the tenth change of the week. On a current engagement for a telecom marketing platform, the agent proposes a structured configuration a person can diff, and nothing is deployed without explicit sign-off.
Make each escalation small enough to resolve in one sitting. On Solarpunk, an escalation returns the specific unresolved step with its trace attached, so the person resolves one thing instead of auditing the whole run. Send the step that failed, the check that failed it and the stop reason. A person handed the full transcript of a long run will skim it, and the loop learns nothing from a skim.
Give the person's stop priority over every other signal in the loop. Read it before each round, from a store the agent cannot write to, and end the run the moment it is set. The approval policy itself, meaning which writes need a person and how to remove approval one action at a time, has its own guide to human in the loop AI agents.
Loop engineering vs harness engineering: where does the loop live?
Addy Osmani places loop engineering one floor above the harness. In his framing, the harness is the environment one agent runs inside, and the loop is that harness on a timer, spawning helpers and feeding itself. DeepLearning.AI's course frames its top loop as one that improves the harness from traces. We read the relationship the other way round, because of where the code ends up.
Every control in this guide is harness code, whichever name it goes by. The round counter, the budget check, the stop flag and the check runner all run in the process around the model, and so do the event deduplication and the stop reason. So we treat loop engineering as the part of harness engineering that deals with repetition, and one team owns both. A loop bolted onto a harness that cannot report its own state can count rounds and nothing else.
Use the names as a map of where a fix goes. Find the layer a failure lives in before writing the fix. A prompt edit cannot stop a loop with no exit, and a new loop cannot repair a tool that returns malformed output.
| Layer | What it changes | A failure it fixes | A failure it cannot fix |
|---|---|---|---|
| Prompt engineering | The instruction the model reads on one turn | Wrong format, wrong tone, a missed constraint | A run with no exit |
| Context engineering | What else enters the context window each turn | Stale or missing facts, an overfull window | A check the agent can talk past |
| Harness engineering | Tools, state, permissions and tracing for one run | Malformed tool output, state lost on a crash | How runs follow each other |
| Loop engineering | Checks, caps, triggers and trace review across turns and runs | Runaway runs, unverified "done", duplicate triggers | A tool that returns bad data |
| Graph engineering | A fixed set of steps and branches known in advance | Work a person could write down | Open-ended work where the next step depends on the last result |
The same layers scale past one agent and past one team's repository. Our page on the AI software factory covers a harness and its loops shared by a whole team, where the eval gate and the trace format are shared as well.
What is loop engineering in Claude Code?
Three features keep a session working between prompts: /goal, /loop and a Stop hook. Scheduled tasks run work without an open session. Loop engineering in this tool means choosing among them and then adding the controls they leave out. The details are from the documentation as of 1 November 2026, and they change between versions, so check them against the version you run.
| Feature | What starts the next turn | What ends it | What we add |
|---|---|---|---|
/goal | The previous turn finishing | A model judges the condition met or impossible, an error you must fix, or /goal clear | A Stop hook script that runs the real check, and a turn counter the script owns |
/loop | A time interval, 1 minute at the shortest | You cancel it, the agent decides the work is done, or 7 days pass | Event deduplication, and a check on what changed since the last pass |
| Stop hook | The previous turn finishing | Your own script or prompt | The stop reason, written to a file the next run can read |
Use /goal for work with a verifiable end state, and write the condition with a stated check and the things that must not change. The condition can run to 4,000 characters, which leaves room for "no other test file is modified" and the command that proves the result.
Remember that the evaluator reads the conversation and does not run the command, so pair it with a Stop hook. A Stop hook in settings applies to every session in its scope, and it can run a script for a deterministic check. The tests then run whether or not the agent reports them.
Cloud scheduled tasks start from a schedule, an API call or a GitHub event, at an interval of 1 hour or more. Their permission prompts default to auto mode, so give them the same permission scope as a run a person started, enforced in the tools they call.
Read the token spend before you trust a long goal. The /goal status shows the condition, the turns evaluated, the current token spend and the evaluator's latest reason. As of 1 November 2026, the /goal page lists spend in that status and does not describe a spending limit, so put the budget in your own hook or wrapper. Codex has its own /goal with a budget attached, and the controls in this guide apply the same way there.
When is a loop the wrong tool?
Skip the loop when a person can write the steps down. Build a fixed workflow with a check at each step, which costs less to run and needs no cap because it cannot wander. Our guide on agentic workflows and AI agents sets out that choice. A loop earns its place only where the next step depends on what the last one found.
Skip it when no check can say no. A loop around an agent whose output nobody can verify by machine repeats a guess until the cap, and each repeat costs as much as the first. Keep a person on each turn until you can write the check, because without one the loop has nothing to stop on but its cap.
Skip it for a one-off task whose check would take longer to write than the task. A verifier pays back across many runs, such as a nightly job, the hundredth dependency upgrade or every pull request in a repository. Writing one for a single ambiguous feature spends the effort the loop was supposed to save.
Skip the trace-learning loop when the agent runs a few times a month. It will not produce enough traces to show which failures repeat, and a task a person already reviews line by line gains little from it. Spend that effort on the check, since a better check improves every run from the next one onward.
Common questions
What is loop engineering vs harness engineering?#
Harness engineering builds the runtime around one agent run: context, tools, state, permissions and tracing. Loop engineering decides what happens between turns and across runs, meaning the check that accepts a result, the cap and budget that end a run, the trigger that starts one, and the trace review that changes the harness. Bigcircle treats loop engineering as the part of harness engineering that deals with repetition, because each of those controls is harness code.
What is loop engineering in Claude Code?#
Claude Code offers /goal to keep working toward a condition, /loop to rerun a prompt on an interval, Stop hooks to run your own check after each turn, and scheduled tasks that run without an open session. The /goal evaluator reads the conversation rather than running commands. Pair it with a Stop hook script that runs the real check and owns the turn count.
What is a loop in AI?#
A loop in AI is a cycle where a model acts, observes the result and decides what to do next, until a goal is met or a limit stops it. An agent is one such loop. Loop engineering adds the controls around it: a check against the system the agent changed, a cap on rounds and spend, triggers that start runs, and traces that show why each run stopped.
How do you stop an AI agent loop from running up cost?#
Put a round cap and a token or dollar budget in the harness, and check both before every round rather than writing a limit into the prompt. Set the cap from the rounds good runs take in testing, count rounds without progress, and hand a capped run to a person with its trace. In the example Simon Maple of Tessl gave, a review loop ran 66 rounds and cost roughly $800.
Who should check the work in an AI agent loop?#
A check that reads the system the agent changed, rather than a second model reading the first one's transcript. Run deterministic checks first, such as the build, the tests, a schema or a read of the target application, and keep the check outside anything the agent can edit. Use a model as judge only for what code cannot decide, and keep a person at irreversible changes and escalations.
Is loop engineering just cron jobs and triggers?#
Triggers and scheduled jobs are among the most common loops in practice, and scheduling a model call is the easy part. The engineering is in what the run does unattended. It deduplicates the event, keeps writes safe to repeat, and holds the same permissions as a run a person started. It also caps rounds and spend, and checks the result against the real system before it counts.
Further reading
- DeepLearning.AI, Loop Engineering with LangChain Deep Agents, released 28 October 2026 and taught by Sydney Runkle and Esmaeil Gargari. The four loops (agent, verification, event-driven, hill-climbing), triggers from a Slack message or a Jira ticket, and improving the harness from traces across many runs. The announcement gives the idea in one line.
- Addy Osmani, Loop Engineering, 7 June 2026. The building blocks as they map onto Codex and Claude Code, the maker and checker split, and loop engineering placed one floor above the harness.
- IBM Think, What is loop engineering?, 17 July 2026, by Ivan Belcic and Cole Stryker. Goal, action, observation and adjustment, recursive goals with verifiable stopping criteria, and the case for a human in the loop.
- Gergely Orosz, What is "loop engineering?", The Pragmatic Engineer, 14 July 2026. The Ralph loop's origin,
/goalarriving in Codex and Claude Code, around 210 reader replies on triggers and cron jobs, and the cost complaints. - Claude Code documentation, Keep Claude working toward a goal and Run prompts on a schedule, read 1 November 2026. The evaluator that reads only the conversation, the turn clause, the no-progress stop, the 4,000 character condition, the 1 minute interval and the 7 day expiry.
- AI Native Dev, Loop engineering starts with a limit, 28 October 2026. Simon Maple of Tessl on the 66-round, roughly $800 pull request.
- Isaac Hagoel, Loop Engineering Minus the Hype. Why a verifier pays back only across many attempts, and how a flexible loop can pass by weakening its tests.
- The Skionis build, the Solarpunk build and the trademark drafting platform.
- Loop engineering, human in the loop AI agents, why AI agents report unfinished work as done, AI agent cost and agent harness engineering.