Stop prompting.
Design the loop.

Loop engineering is the practice of designing the system that runs your AI agent in a repeating cycle — find work, do it, verify it, record it, repeat — instead of prompting the agent by hand each step. You stop being the person who types the next instruction and become the person who designs the machine that decides what the next instruction is.

The term went mainstream in June 2026 when Addy Osmani synthesized these ideas into a named discipline, and the framing stuck because it describes a real shift already underway: the folk version had existed for a year as the "run the agent in a while true loop" trick, and every serious agent team had independently invented pieces of it. Naming it made it designable.

The cleanest way to place it is as the third rung of a ladder, where each level contains the one below:

The word "loop" is doing double duty here, and separating the two meanings is the key to the whole discipline. The inner loop is the agent loop itself — plan → act → observe — the ReAct-style cycle inside every harness, where the model thinks, calls a tool, reads the result, and thinks again. That loop is largely built for you by whoever ships your agent.

The outer loop is the one you engineer. It wraps the entire agent run as a single step inside a bigger cycle:

Every design decision in this handbook lives in one of those five outer stages. If your mental model of "agent" stops at the inner loop, the rest of this page is the missing half.

Outer loops come in four shapes, distinguished by what triggers them and what stops them. Choosing the right shape is the first real design decision — most bad loops are a goal problem forced into a heartbeat shape, or vice versa.

They compose. A mature setup is usually a cron loop that discovers work, hook loops that react to events, and goal loops spawned per work item — each with its own stopping rule. The goal loop is the most powerful and the most dangerous: it's the only one whose natural state is "keep going," which is why it gets its own section on stopping conditions below.

Across tools, working loops converge on the same six components. Five are primitives you configure; the sixth is a discipline you maintain.

The same blocks exist under different names in every major harness:

The pattern to internalize: discovery (automations find work), isolation (worktrees keep parallel work safe), knowledge (skills stop you re-explaining), reach (connectors let it act), judgement (subagents verify), memory (state survives the run). Miss one and the loop leaks — usually money.

A loop's stopping condition must be checked by machinery, not judged by the model. "The refactor looks complete" is a judgement; 0 failing tests && 0 lint errors is a condition. Models are systematically overconfident about their own completions, so a loop that lets the agent declare victory will terminate early on plausible-looking work — and a loop with no condition at all simply never stops.

Layer three guards, in order of bluntness:

The third guard is the architectural pattern worth naming: the verification split. The agent that wrote the change must not be the agent that approves it — the same failure of incentives as a developer reviewing their own PR, except the model fails it more reliably. In practice: one subagent implements in a worktree, a second subagent with fresh context reviews against the project's skills and runs the tests, and only a pass releases the work downstream. Evaluating agent output rigorously is its own discipline — the Agent Evals handbook covers it.

Models forget everything between runs. The loop can't. External memory — state kept outside the context window — is what turns a series of isolated agent runs into a system that makes progress. Without it you get state amnesia: the Monday run re-fixes what Friday's run fixed, the migration loop re-converts the same ten files, and iteration count stops correlating with progress.

Two rules make state trustworthy. First, the loop reads state before framing the task and writes state after verification — never mid-run, so a crashed run can't record work it didn't finish. Second, state records facts, not vibes: "converted auth/session.ts, tests pass" is replayable; "made good progress on auth" is amnesia with extra steps. A resume-point convention — one line saying exactly where the next run picks up — is the cheapest reliability upgrade a loop can get.

Loops multiply whatever they touch — including your bill. A manual prompt costs one conversation; a heartbeat loop with a verifier subagent is dozens of model calls an hour, all day, whether or not there's work to do. A goal loop with no iteration cap can burn hundreds of dollars in an hour while making no progress at all. Cost isn't a footnote to loop engineering; it's a design axis.

Three levers, roughly in order of impact:

And put a budget ceiling on every loop as a hard cap, not a dashboard you check later. A loop that stops at its budget is an inconvenience; a loop you discover on the invoice is a story you tell at conferences.

The last two failures are human, not technical, and they're the ones Osmani's write-up dwells on. Orchestration tax is the ceiling loops eventually hit: not model capability, but your bandwidth to review what they produce — parallelism past that point manufactures unreviewed changes. And cognitive surrender is the failure past the ceiling: you stop having opinions about the output entirely. The same loop produces opposite results for an engineer who understands the system deeply and one who has delegated the understanding itself.

Theory compresses into a worked example. Here is the reference architecture — a nightly triage-and-fix loop, the "hello world" of loop engineering — using every block from section 04:

And because a loop is ultimately just code, here is the entire idea in one runnable file — a goal loop for a migration, with all three guards and both state rules from section 06. Swap the claude -p line for any agent harness you use:

import json, subprocess, sys

MAX_ITERATIONS = 8                      # guard 1 — hard cap
STATE_FILE = "loop-state.json"          # external memory

def load_state():
    try:
        return json.load(open(STATE_FILE))
    except FileNotFoundError:
        return {"queue": ["auth/session.py", "auth/token.py"], "done": []}

def verified():                         # guard 2 — checked by machinery, not the model
    return subprocess.run(["pytest", "-q"]).returncode == 0

def run_agent(task):                    # the whole inner loop is this one box
    subprocess.run(["claude", "-p", task])

for i in range(MAX_ITERATIONS):
    state = load_state()                # read state BEFORE framing the task
    if not state["queue"]:
        print("goal met"); sys.exit(0)  # verifiable stopping condition
    target = state["queue"][0]
    run_agent(f"Migrate {target} to the new session API. Done so far: {state['done']}")
    if verified():                      # guard 3 — verifier is not the implementer
        state["done"].append(state["queue"].pop(0))
        json.dump(state, open(STATE_FILE, "w"))   # write state AFTER verification
        subprocess.run(["git", "commit", "-qam", f"migrate {target}"])  # bank the verified work
        if not state["queue"]:
            print("goal met"); sys.exit(0)  # re-check, or a last-try success reads as "cap hit"
    else:                               # state untouched — the next iteration retries the same target
        subprocess.run(["git", "checkout", "--", "."])  # ...from clean code, not the failed edits

print("cap hit with work remaining — escalate to a human")  # end loudly, never silently

Under forty lines, and every concept in this handbook is present: the cap, the condition, the verification split (pytest judges, not the agent), read-first/write-last state, a clean retry (a failed attempt’s edits are discarded, verified ones committed), facts-not-vibes checkpoints, and a loud ending. Production loops grow worktrees, subagents, and connectors around this skeleton — they never replace it.

How to actually start, without the fleet:

Pick one recurring chore you already do — triaging CI failures, dependency bumps, flaky-test hunting. Boring and frequent beats impressive and rare. Write the skill first: the conventions you'd explain to a new teammate go in a version-controlled instruction file, because an outer loop is only as good as the context it frames (that's the L2 layer doing its job inside L3). Give it the three guards from section 05 — a cap, a condition, a verifier — before its first unattended run, not after its first incident. Run it supervised for a week, reading everything it produces; you're calibrating trust, and you'll usually fix the skill file three times in the first five runs. Then schedule it and add the next loop only when reviewing this one costs you almost nothing.

One well-guarded loop that runs every night is worth more than five clever ones you had to turn off. The engineers getting leverage from this aren't the ones with the most agents — they're the ones whose loops they can stop thinking about.

The instructive part is why each guard exists — every one was added after its absence hurt. The ship-gate exists because early videos degraded quietly: each looked fine in isolation while the batch drifted mediocre — silent quality drift, caught only by a human audit. The queue governor exists because building faster than the upload cap just manufactured a warehouse. And the resume-point convention exists because the first crashed batch re-rendered work it had already finished — state amnesia, paid for in GPU-hours.

Run the page’s migration loop against its default queue, auth/session.py then auth/token.py, with MAX_ITERATIONS = 8. Say the agent’s first attempt at session.py leaves a test red.

Rows 0 and 1 show write-last doing its job. The failed attempt left no record, so iteration 1 retried the same target instead of believing it was done. The alternate rows show two things the guards do not. First, the cap is shared by the whole queue, not given to each file: 8 iterations for 2 files leaves at most 6 attempts at whichever file is stuck. Second, why the queue is checked twice. If the only empty-queue check ran at the top of an iteration, a success on the last allowed iteration would fall out of the for loop into the “cap hit” message and page a human for work that is finished. The re-check straight after writing state is what prevents that false alarm.

• Retrying on a dirty tree

  When the tests fail, the agent’s half-finished edits are still on disk. Leave them, and the next attempt starts from broken code, not from the last good commit. The page’s loop runs git checkout -- . before the retry and commits each verified file, so the reset cannot throw away earlier good work. git checkout does not remove new untracked files; a fresh worktree per attempt does.

• The implementer can edit the verifier

  If the agent can touch the tests or the lint config, deleting a failing test is the cheapest way to make pytest -q exit 0. Protect the verifier’s files. Then add a check to the gate that fails the run if the number of tests goes down.

• One poison item eats the whole budget

  In the page’s loop, a first file that never passes takes all 8 iterations, and the second file is never attempted. Keep an attempt counter per item. After N failures, move the item to the human inbox and carry on with the rest of the queue.

• Overlapping runs on one state file

  A nightly cron run that takes longer than a day starts again while the previous run is still going. Both read the same queue and pick the same item, and the last writer wins. Take a lock at the start, or skip the run if the previous one is still alive.

• A hook loop that triggers itself

  A loop that runs on every push, and pushes, can fire itself forever. Filter out events your own bot authored. GitHub Actions blocks the simple case for you: events created with the workflow’s GITHUB_TOKEN do not start new workflow runs, except workflow_dispatch and repository_dispatch. A personal access token or app token gets no such protection.

• Dependency bots

  Dependabot and Renovate are cron loops that predate LLM agents. They run on a schedule, open one PR per update, let CI act as the verifier, and leave the merge to a human. Their PR limits and grouping rules are the orchestration-tax ceiling, written down as config.

• Kubernetes controllers

  A controller is a goal loop that never exits. It compares the desired state with the actual state, acts to close the gap, and runs again. It has to be idempotent because it may act on the same object many times. That is the design a goal loop over a work queue should copy.

• CI as the verification split

  The cheapest independent verifier is the pipeline the team already trusts. A loop that opens a PR and waits for the required checks gets a judge that is not the implementer, and branch protection stops anything red from merging.

• The interview version

  “Design an agent that fixes flaky tests overnight.” Name the loop type (cron to find flakes, a goal loop per test), the three guards, where state lives, the per-item attempt limit, and the budget cap. Then say what a human reviews. Picking the right shape and stop rule matters more than which model you name.