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
    # on failure: state untouched — the next iteration retries the same target

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

Thirty 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, 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.