Claude Code Loops: The Definitive Introduction

You've used Claude Code the normal way: type a prompt, watch it work, type the next prompt. That's a conversation. A loop is different — you hand the agent a goal, an exit condition, and a budget, then walk away. The agent keeps iterating until the condition is met or the budget runs out.

That one change — *run until done, not run once* — is the difference between an assistant and an automation. This guide covers what loops are, the four types you'll actually use, and how to run them without waking up to a trashed repo.

What is a loop?

A loop is a Claude Code (or Codex) session with three parts:

1. A goal — a concrete, checkable outcome. Not "improve the tests." Something like "all tests pass and lint is clean." 2. An exit condition — the machine-checkable signal that the goal is met. Usually an exit code: npm test && npm run lint returning 0. 3. A budget — a cap on iterations, time, or spend, so a stuck agent stops instead of burning tokens forever.

The simplest loop is embarrassingly small:

while :; do
  claude -p "Fix the failing tests. Run 'npm test' to check. Stop when it passes." \
    --dangerously-skip-permissions
  npm test && break
done

That works, and it's roughly what every loop harness compiles down to. But raw while true has no budget, no guardrails, and no memory between iterations. The rest of this guide — and this site — is about doing it properly.

The four loop types

Every loop in [the directory](/loops) is one of four types. Learn these and you can read any loop at a glance.

### 1. Goal loops — run until a condition is true

The workhorse. You state an outcome and a verifiable check, and the agent iterates until the check passes.

/goal all tests pass and lint is clean
exit: npm test && npm run lint → exit 0
budget: 15 iterations

See it in the wild: [fix-tests-and-lint](/loops/fix-tests-and-lint) is exactly this loop. [kill-flaky-tests](/loops/kill-flaky-tests) is the harder cousin — the exit condition is "test suite passes 10 consecutive runs," which forces the agent to actually fix flakiness rather than get lucky once.

Browse all of them at [/type/goal](/type/goal).

### 2. Timed loops — poll on an interval

Sometimes there's no single exit condition — you want the agent to check something repeatedly and act when it changes. That's a timed loop:

/loop 20m /review-pr 1234

Every 20 minutes, the agent re-reviews PR #1234: new commits, new CI results, new review comments. It responds to what changed and goes back to sleep. [babysit-a-pr](/loops/babysit-a-pr) is the canonical example; [ship-pr-until-green](/loops/ship-pr-until-green) combines a timed poll with a goal — keep pushing fixes until CI is green, then stop.

More at [/type/loop](/type/loop).

### 3. Scheduled loops — cron for agents

A schedule loop runs on a calendar instead of a condition:

/schedule weekdays 9am
task: triage new issues — label, dedupe, flag anything urgent
budget: 30 minutes per run

[morning-issue-triage](/loops/morning-issue-triage) does your first hour of GitHub janitorial work before you've had coffee. [nightly-e2e-run](/loops/nightly-e2e-run) and [weekly-dependency-audit](/loops/weekly-dependency-audit) are the same pattern at different cadences. Browse [/type/schedule](/type/schedule).

### 4. Ralph loops — brute-force a backlog

The Ralph Wiggum loop (named and popularized by Geoffrey Huntley — ghuntley.com/ralph) is the maximalist version: run the *same prompt* in a while true, fresh context each iteration, and let the agent chew through a backlog one item at a time. State lives in files, not in the conversation.

while :; do
  claude -p "$(cat prompt.md)" --dangerously-skip-permissions
done

It sounds dumb. It is dumb. It also ships. The key refinement is a guardrails file the agent reads at the start and appends learnings to at the end of every iteration — see [ralph-guardrails-learning](/loops/ralph-guardrails-learning), and the full explainer in our Ralph guide. All Ralph-style loops live at [/type/ralph](/type/ralph).

Anatomy of a good loop

The loops that work share the same skeleton. When you write your own, fill in all five slots:

GOAL:    one sentence, concrete outcome
CHECK:   a command whose exit code verifies the goal
BUDGET:  max iterations AND max wall-clock time
SCOPE:   which files/dirs the agent may touch
STOP:    what to do on repeated failure (usually: write notes, halt)

The CHECK is the part people skip, and it's the part that matters most. If the agent can't *verify* success mechanically, it will declare success rhetorically. "Refactor the auth module" is a wish. "Refactor the auth module; npm test passes and npx tsc --noEmit is clean" is a loop.

Safe loops, not runaway agents

An agent in a loop with --dangerously-skip-permissions will do whatever gets it closer to the exit condition — including deleting the failing test instead of fixing it. Minimum viable safety:

Hard budgets. Iteration caps and timeouts, enforced by the harness, not by asking the model nicely.
Scope limits. Run in a worktree or container. The blast radius of a bad iteration should be git worktree remove, not a production incident.
An evaluator gate. Before accepting the result, check it — did the diff touch only allowed paths? Did test *count* go down? Default-fail: if the evaluator can't tell, reject.
Handoff notes. Have the agent append what it tried to a progress file each iteration, so a stuck loop leaves a trail instead of a mystery.

We go deep on this in the agent loop safety guide. If your loop needs to notify you when it finishes or gets stuck, wiring email into an agent is its own rabbit hole — ConnectMyEmail exists so your loop can just send the email and get back to work.

Where to start

Pick one annoying, verifiable chore. Failing CI is the classic:

/goal the build is green
exit: CI passes on the current branch
budget: 10 iterations, 45 minutes
scope: src/, tests/ — never touch .github/workflows

That's [get-the-build-green](/loops/get-the-build-green), more or less. Run it in a worktree, watch the first few iterations, then stop watching. That last part is the whole point.

Ready to write your own? The [loop builder](/builder) walks you through goal, exit condition, budget, and guardrails, and hands back a harness you can run tonight. Start there.

Claude Code Loops: The Definitive Introduction