Loop Engineering: Claude Code Loops, Routines & Workflows

TL;DR: Loop engineering is the discipline of making agents repeat cycles of work until a stop condition is met — instead of prompting them one turn at a time. Anthropic’s Boris Cherny, creator of Claude Code, describes his own workflow bluntly: “I don’t prompt Claude anymore. I have loops running. They’re the ones prompting Claude and figuring out what to do. My job is to write loops.”¹ Claude Code now ships a full ladder of loop surfaces — /goal (repeat until a separate model confirms a condition), /loop (recurring local runs), the official Ralph plugin (iterate until a promise is kept), routines (cloud cron), and dynamic workflows (Claude writes a JavaScript orchestration graph and runs up to 1,000 subagents against it). The load-bearing craft is none of those features: it is verification. A loop converges only when something outside the generator — a test, a grader model, a pixel diff, a machine check — decides “done.” Get that right and loops compound; get it wrong and you buy a very expensive random walk. This guide covers every loop surface with version anchors, the Ralph pattern and its failure modes, when loops need to become graphs, the verification ladder, cost and safety discipline, and how to run a standing fleet. Current as of Claude Code v2.1.224 (August 2026).

What Is Loop Engineering?

Two years ago, engineers wrote source code by hand. Then agents wrote the code from human prompts. The shift now underway is one level higher: agents prompt agents, and the human writes the system that decides what gets prompted. Cherny rates the step change directly: “As big as the step from source code to agents was, loops are just as important and as big a step.”²

His definition is refreshingly mundane: “Loop is essentially a cron job that’s running locally for Claude. Routine is the same thing, but it’s running in the cloud.”³ The exotic-sounding practice — “hundreds, sometimes thousands of agents running 5, 10, 20 hours” overnight,⁴ Claude Code “100% written by Claude Code for over six months”⁴ — reduces to a small set of primitives: a prompt that re-fires on a schedule or a condition, state that survives between iterations, and a check that ends the run.

Anthropic named the discipline in June 2026: loops are “agents repeating cycles of work until a stop condition is met,” and “the quality of a loop’s output depends on the system around it.”⁵ The system around it is what this guide is about.

A provenance note, because the discourse moved fast in mid-2026: the term “graph engineering” — often attributed to Cherny in viral posts — was coined by the community (Peter Steinberger’s July 18 “are we still talking loops or did we shift to graphs yet?”, amplified by Hamel Husain), not by Anthropic or Cherny.⁶ The widely shared “85% of our engineers… the way you do it is graph engineering” quote circulates only through third-party posts; in preparing this guide we could not locate it in any primary record of his talks (the YC Startup School conversation, Bloomberg’s Odd Lots, TechCrunch’s Meta @Scale report), so treat it as unverified attribution. His actual practice is graph-shaped (orchestrators spawning implementer/verifier/fixer subagents, nested to depth 5), but the verified vocabulary is loops, routines, and workflows — and that is the vocabulary this guide uses.

Five-Minute Golden Path

Three commands take you from prompting to looping:

# 1. A goal loop: Claude keeps working until a SEPARATE model confirms the condition
/goal all tests pass and coverage is above 80%

# 2. A recurring local loop: re-runs on a schedule while your session is open
/loop 30m check CI on my open PRs and fix any failures

# 3. A cloud routine: runs on Anthropic's infrastructure whether your laptop is open or not
/schedule every morning at 7am: triage new issues, reproduce what you can, draft fixes as PRs

The difference between these and a prompt is structural, not cosmetic: each has a re-fire rule (a condition, a clock, a cron) and each needs a stop rule. Everything else in this guide is about making those two rules trustworthy.

The Core Loop and the One Rule

Every agentic system runs the same inner cycle, which Anthropic’s Agent SDK documentation canonizes as gather context → take action → verify work → repeat.⁷ Claude Code’s own process is a loop: evaluate the prompt, call tools, read results, repeat until a response has no tool calls.⁸

Loop engineering wraps outer loops around that inner one — and inherits its one non-negotiable rule, stated across every serious source in the field:

The agent doing the work never grades it.

• Anthropic’s /goal docs: “completion is decided by a fresh model rather than the one doing the work.”⁹
• Anthropic’s harness-design essay: “Separating the agent doing the work from the agent judging it proves to be a strong lever to address this issue.”¹⁰
• Cherny, on what practitioners miss: “The verification is probably the single most important thing that people do not get right.”³ His worked example, instructing a two-week Electron-to-Swift rewrite: “run the Electron app in the Mac virtual machine, screenshot it, and then look pixel by pixel. Compare it to the Swift version. Don’t stop until you’re done.”³

The reason is mechanical, not moral: a model asked “are you done?” exhibits positive self-grading bias, and a confident transcript can talk a model-judged exit condition into premature “done.”¹¹ External verification — a test suite, a compiler, a pixel diff, a fresh model with no stake in the answer — is the only signal that resists this.

The Autonomy Ladder

Loop surfaces in Claude Code form a ladder from “press enter again” to “runs without you.” Each ring trades more autonomy for more verification burden:

(The ring framing follows pardel.dev’s July 2026 taxonomy, the cleanest independent map of the space.¹¹)

The ladder’s discipline: enter at the lowest ring that solves your problem, and climb only when a ring’s verification is proven. A /goal that can’t state its condition as something checkable is not ready to be a routine.

The Loop Surfaces, In Detail

(This guide covers the loop surfaces themselves. The Claude Code guide is the full CLI reference — configuration, permissions, hooks, MCP — and the Agent Architecture guide covers how harness components compose; loops are what you run on top of both.)

/goal — the evaluator-optimizer loop

/goal <condition> keeps Claude working until the condition holds: “After each turn, a small fast model checks whether the condition holds. If not, Claude starts another turn instead of returning control to you.”⁹ The evaluator (Haiku by default) returns yes/no plus a reason that Claude takes as next-turn guidance. It runs headless too: claude -p "/goal ..." executes the loop to completion.

Craft notes: make the condition observable (“tests pass,” “the endpoint returns 200,” “zero TypeScript errors”) rather than aspirational (“the code is clean”). A vague verifier gives the loop no direction — and a model-judged condition can be argued into agreement by a confident transcript, so pair /goal with a machine check whenever one exists.¹¹

/loop — recurring local runs

/loop [interval] <prompt> re-runs a prompt on a schedule: fixed (/loop 5m check the deploy), self-paced (Claude picks the next delay from what it observed), or bare /loop for a built-in maintenance pass. Under the hood are CronCreate/CronList/CronDelete (5-field cron, 50 tasks per session, 7-day expiry) and the Monitor tool, which streams a background script’s output instead of polling.¹² Cherny’s own launch example: “/loop babysit all my PRs. Auto-fix build issues and when comments come in, use a worktree agent to fix them.”¹³

The limitation that matters: /loop lives in your session. Close the terminal and the loop dies — that’s what routines are for.

The Ralph plugin — iterate until the promise is kept

Anthropic’s official ralph-wiggum plugin productizes the community’s favorite brute-force pattern: a Stop hook intercepts Claude’s attempt to end the session and re-injects the prompt, so the model iterates continuously in one session. /ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<string>" starts it; /cancel-ralph aborts. The README is explicit that --max-iterations is “your primary safety mechanism” — exact-string completion matching can fail forever.¹⁴

Dynamic workflows — Claude writes the graph

Introduced with Claude Code v2.1.154 (May 2026) and detailed in Anthropic’s June 2, 2026 launch post, dynamic workflows are the biggest conceptual jump: “Claude can now write its own harness on the fly, custom-built for the task at hand.”¹⁵ You describe the task (or just say “use a workflow”); Claude writes a JavaScript orchestration script — agent() spawns a subagent with optional JSON-schema outputs, pipeline() runs items through stages, plain await/loops/conditionals hold the control flow — and a runtime executes it in the background. “A workflow moves the plan into code… A workflow script holds the loop, the branching, and the intermediate results itself, so Claude’s context holds only the final answer.”¹⁶

Limits and shape: 16 agents concurrent, 1,000 per run (“prevents runaway loops”), no mid-run user input; scripts saved to .claude/workflows/ become reusable slash commands; runs are resumable with cached agent results.¹⁶ The signature topology is fan-out / refute / converge: independent finders, then adversarial verifiers prompted to refute each finding, iterating until answers survive. The launch’s headline result: Bun’s port of its 535,496-line Zig codebase to Rust — yielding a Rust codebase past a million lines — in eleven days (May 3-14, 2026) by 64 parallel agents, per Jarred Sumner’s account.¹⁵

Agent teams — the peer graph

Behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (research preview since v2.1.32, February 2026): a team lead plus teammates who “work independently, each in its own context window, and communicate directly with each other” — a peer graph rather than the subagent tree, coordinated through a shared task list with dependencies, file-lock claiming, and per-agent mailboxes. Hook-enforced quality gates (TaskCompleted exit-code-2 blocks) put machine checks between a teammate and “done.”¹⁷

Routines — loops that outlive your laptop

A routine is “a saved Claude Code configuration: a prompt, one or more repositories, and a set of connectors, packaged once and run automatically” on Anthropic-managed cloud or your own self-hosted runners.¹⁸ Three trigger types, combinable: cron schedule (1-hour minimum), API fire (POST .../routines/{id}/fire), and GitHub events. Created via /schedule or claude.ai/code/routines. Runs execute autonomously — no approval prompts — which is exactly why the docs’ caveat is load-bearing: a green run status “does not mean the task in your prompt succeeded. Open the run to read the transcript and confirm what Claude actually did.”¹⁸

Anthropic runs “every day maybe 20 or 30 of these routines” across its own codebases — dead-code cleanup, test coverage, shipping experiments.³

The supporting cast

Background subagents (default since v2.1.198) keep delegated work out of your context; the /agents panel monitors them. Cross-session messaging (v2.1.224) turns independent sessions into a message-passing graph via SendMessage, with security doctrine worth copying: a message from another session “never counts as your consent.”¹⁹ Self-hosted runners (v2.1.224, Team/Enterprise) execute cloud sessions and routines on your own machines — the substrate for org-scale fleets.²⁰

The Ralph Pattern

The community got here first. In July 2025, Geoffrey Huntley published the essay that named the technique after The Simpsons character: Ralph is literally

while :; do cat PROMPT.md | claude-code ; done

— his one-liner exactly as published — one repo, one task per iteration, fresh context every pass, with specs and progress files on the filesystem carrying state between iterations, and tests/lints acting as “backpressure.”²¹ The modern headless form of the same shape is claude -p "$(cat PROMPT.md)" in a shell loop, which is essentially what Anthropic’s own C-compiler harness ran.²³ His claimed results (a $50K contract’s MVP for $297 in tokens; six repos overnight at a hackathon) came with equally clear limits: greenfield only, placeholder and duplicate implementations as recurring failure modes, and “LLMs are mirrors of operator skill.”

Anthropic never uses the name in its engineering material, but the pattern is now official doctrine twice over: the November 2025 long-running-agents essay prescribes exactly this shape — an initializer agent creating feature lists and progress files, then fresh coding agents per context window that “start the session by reading the progress notes file and git commit logs”²² — and the February 2026 C-compiler project ran sixteen parallel Claude agents — “I built a harness that sticks Claude in a simple loop,” as Nicholas Carlini describes it — with file-based task locks and git as the sync layer, producing ~100K lines of Rust across ~2,000 sessions for about $20K.²³ The essay’s verification line is the pattern’s whole theory: “it’s important that the task verifier is nearly perfect.”

Why fresh context beats one long session: effectiveness degrades as a session’s context fills — practitioner consensus puts the drift threshold around 100K tokens — and compaction summaries are lossy paraphrases that launder errors into confident prose.²⁴ Ralph’s fresh-spawn-plus-files design sidesteps both. (The official plugin’s in-session looping trades some of this away for convenience; for long runs, the headless form with external state remains the stronger pattern.)

The pattern’s cautionary tale is also instructive: a practitioner ran the plugin with a vague prompt and max_iterations: 0 — which means infinite, not disabled — and Claude asked itself the same clarifying question 1,966 times, with the Stop hook hijacking every subsequent message.²⁵ Iteration caps are not optional.

When Loops Become Graphs

A single loop assumes its iterations are independent or strictly sequential. The moment parallel work has dependencies — task B needs A’s output, two agents would edit the same file — freeform loops collide, and you need explicit structure: a task list with dependency arrays, file claiming, merge discipline. That is the honest content of the loops-versus-graphs debate: loops for one repo and one goal; graphs when parallel work needs ordering.²⁶

The graph options, in ascending infrastructure:

1. Dynamic workflows — dependencies expressed in JavaScript control flow; barriers only where a stage genuinely needs all prior results. The topologies Anthropic names: fan-out-and-synthesize, adversarial verification, generate-and-filter, tournament (“Spawn N agents that each attempt the same task using different approaches,” then judge pairwise), and loop-until-done.¹⁵
2. Agent teams — a shared task list with dependency tracking and a lead who approves plans; the graph is data, not code.¹⁷
3. External orchestrators — the community scale-out: Steve Yegge’s Gas Town runs 20–30 Claude Code instances against DAGs of git-backed “beads” (75K lines of Go in 17 days, by his own telling also “a cash guzzler” demanding high operator skill);²⁷ claude-flow/Ruflo (~31K stars) wraps swarms in a queen/worker hierarchy; LangGraph-style engines put a typed state machine on top with Claude Code inside the nodes.

Cherny’s own formalization of the trajectory is the Steps of AI Adoption ladder, published via Anthropic in July 2026: Gated (0 agents) → Assisted (~1) → Parallel (~10) → Supervised autonomy (~100, where “most agents are kicked off by Claude, not humans”) → AI-native (1,000+). His advice with it: “at each step… you need to find and break down the next set of bottlenecks, and build up the next set of guardrails.”²⁸

Verification Engineering

Everything above is plumbing. This section is the product.

Anthropic’s escalation ladder, from the current best-practices doc: give Claude something that produces a pass or fail and “the loop closes on its own” → a /goal condition re-checked by a separate evaluator → a Stop hook as “a deterministic gate” → “a verification subagent or a dynamic workflow that checks its own findings has a fresh model try to refute the result, so the agent doing the work isn’t the one grading it.”²⁹ The evidence norm attached: “Have Claude show evidence rather than asserting success.”

The three feedback classes, from the Agent SDK essay: rules-based feedback (“clearly defined rules for an output, then explaining which rules failed and why” — the best form), visual feedback (screenshots, pixel diffs), and LLM-as-judge (fuzzy rubrics — in Anthropic’s words, “generally not a very robust method”).⁷ Prefer them in that order; a deterministic check that exists beats a judge that opines.

Convergence conditions. The sharpest critical treatment of loops — Yoko Li’s August 2026 analysis — reduces convergence to four requirements: a defined target state, an observable current state, precise local edits, and stopping rules outside the generator. Her instrumented experiment is the number to remember: 67% of the loop’s token spend produced zero improvement, because nothing told the loop that returns had gone logarithmic.³⁰ Budget caps are not merely cost control; they are a stopping rule of last resort.

Test integrity. From Anthropic’s long-running-agents doctrine: “It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.”²² Loops game specifications — passing the visible tests while failing the hidden intent — so the verifier itself needs protection from the agent it judges.

Grade outcomes, not paths. From the evals essay: “Grade what the agent produced, not the path it took,” use code-based graders where objective and model-based graders for rubrics, and calibrate: “You won’t know if your graders are working well unless you read the transcripts and grades from many trials.”³¹

One more distinction most of the discourse misses: when every check in a loop is deterministic, no model belongs in the loop at all. A drift watcher that compares timestamps, a link checker, a build sentinel — these are shell scripts on a schedule: zero tokens, seconds per run, perfectly repeatable. Reserve model-driven loops for iterations that need judgment. The cheapest loop is the one that never calls a model.

Cost and Safety Discipline

The loudest community objection to loop engineering is cost, and the postmortem genre backs it up: a subagent-spawning bug burning 4M tokens in five minutes; overnight loops consuming thousands of dollars; usage limits hit “way faster than expected.”³² The discipline that emerged, each piece mapping to a shipped control:

That last row deserves its own paragraph, because it is how the most aggressive practitioners stay safe: make the pull request the blast radius. Cherny’s standing background agents — one continuously improving architecture, one hunting duplicated abstractions — submit PRs without human triggers;² nothing merges without review. An always-on loop whose worst case is “an unmerged branch” can run hot; a loop that writes to main cannot. Promote loops gradually: start observe-only (reports, no writes), earn trust across boring runs, then graduate to proposing changes — with the ordering proof (“purge runs only after verification returns the new marker”) and an exhaustive blast-radius declaration written down before the schedule is installed. The economics of this promotion path are the subject of Loops Win Where Verification Is Cheap: verification cost, not loop construction, decides what can run unattended.

The deepest objection is not cost but review capacity — loops produce code faster than humans can meaningfully review it.³³ There is no clever answer; there is only scoping honesty: unattended loops belong exactly where verification is machine-checkable, and nowhere else. “If you can’t verify it, don’t ship it.”²⁹

Running a Fleet

The end state of loop engineering is not one loop; it is a standing fleet. What the practice looks like when it stabilizes:

• Specs as files. Each loop is a versioned spec — name, tier, schedule, goal, verifier, allowed tools, budget, timeout — living in the repo it serves. If you have typed the same manual check three times, it becomes a spec.
• Two tiers, earned promotion. Observe loops read anything, write only to their own report directory, and schedule immediately. Act loops touch the world and require the ordering proof, the blast-radius declaration, and a verifier that is not the maker — written before the schedule exists. Loops start life as observe and earn promotion.
• The exec/model split. Deterministic checks run as scripts (zero tokens, 1–2 seconds); model loops are reserved for judgment. A fleet’s daily heartbeat can cost nothing.
• Report contracts. One line per check, PASS|FAIL <check>: <reason>, appended to a dated report file. If you cannot define the glanceable PASS line, the loop is not ready. A digest loop reads the fleet’s reports so the human reads one page, not thirty.
• Self-maintaining baselines. The best drift watchers derive expectations from the artifact they guard — a guide’s own recorded timestamps, a lockfile’s own hashes — so updating the artifact updates the watcher, and there is no second source of truth to forget.
• Scheduling that survives. Local fleets run on the OS scheduler (launchd, cron, systemd timers) invoking a runner script; cloud fleets are routines. Session-bound loops (/loop) are for work you are present for.

This is Cherny’s “my job is to write loops,” made concrete: the human’s work shifts to specifying checks, verifiers, and budgets — and reading the reports.

The First Two Loops Worth Building

If you are starting a fleet from zero, two loops pay for themselves immediately — both proven in this site’s own harness:

The gate loop — maker-checker for anything you publish. A fresh evaluator (no memory of prior rounds) scores the artifact against an explicit bar; you apply every named finding; a new evaluator re-scores; the loop stops at the bar or a hard round cap. Two field notes from running it across a fifteen-post sprint: repairs can introduce new defects (one round’s fix misattributed a figure that the next round’s evaluator caught), and evaluators err in both directions — one confidently “corrected” a true claim, so specific corrections get verified at the source before they are applied. The checker is not the authority; the source is.

The groundskeeper — the act-tier entry point. One small, objectively verifiable fix per run, on a branch, tests green before the PR opens, and the loop never merges. Two rules keep it safe: anything ambiguous gets flagged, not fixed (the first supervised run correctly declined a detector false positive), and a pre-existing failure on main is reported as such, never absorbed into the loop’s diff.

One fleet-operations detail worth stealing: give unattended model loops a session lease — defer any run while an interactive session is active in the same repo. Two writers with one checkout will eventually interleave commits; the lease makes the loop yield to the human by construction.

FAQ

What is loop engineering?

The practice of making AI agents repeat cycles of work until a stop condition is met, instead of prompting them turn by turn. The engineer’s job moves from writing prompts to designing the loop: its re-fire rule (a condition, a schedule, an event), its state between iterations, its verifier, and its budget. Anthropic named the discipline in June 2026; its Claude Code surfaces are /goal, /loop, the Ralph plugin, routines, and dynamic workflows.

What is a Ralph loop?

A brute-force autonomy pattern named by Geoffrey Huntley in July 2025: run Claude Code in a shell while loop, feeding it the same prompt with fresh context each iteration, with progress files and git carrying state between passes and tests acting as backpressure. Anthropic ships an official ralph-wiggum plugin that does the looping in-session via a Stop hook, with --max-iterations as the primary safety mechanism.

How do I run Claude Code in a loop?

Pick the lowest ring that fits: /goal <condition> to iterate until a separate evaluator confirms a condition; /loop <interval> <prompt> for recurring runs while your session is open; /ralph-loop to iterate on one task until a completion promise; /schedule to create a cloud routine that runs on cron without your machine. Headless, claude -p inside a shell loop with an external check is the classic form.

Do loops replace prompting?

The prompt does not disappear — it moves. You write it once, into the loop’s spec, and the loop re-fires it; increasingly (dynamic workflows, Cherny’s “it’s actually another Claude that does the prompting”) an orchestrating agent writes the per-task prompts. What replaces prompt-crafting as the human’s craft is verification design: stating conditions a machine or a fresh model can check.

What is the difference between a loop, a routine, and a workflow in Claude Code?

A loop (/loop) re-runs a prompt on a schedule inside your local session and dies with it. A routine is the same idea packaged to run on cloud infrastructure — cron, API, or GitHub-event triggered, no laptop required. A workflow is a single run’s orchestration graph: a JavaScript script Claude writes that spawns and coordinates up to 1,000 subagents with loops and branching held in code rather than context.

How much do agent loops cost?

The honest range is “zero to ruinous,” and the variable is design. Deterministic watchers cost nothing — they are scripts on a schedule. Model loops are metered by iteration: cap them (--max-iterations, --max-budget-usd), make returns observable so the loop can stop at diminishing returns, and treat every cap as a stopping rule, not an inconvenience. The failure postmortems — thousands of dollars overnight, 4M tokens in minutes — share one root cause: no external stop condition.

When should a loop become a graph?

When parallel work develops dependencies: one task needs another’s output, or two agents would touch the same files. Loops handle one repo and one goal; graphs (dynamic workflows, agent teams, external orchestrators) add dependency ordering, file claiming, and merge discipline. Enter graphs only when collisions actually appear — the added structure costs observability and setup.

Changelog