# What is a loop? Canonical: https://loopmaster-ai.pages.dev/learn/what-is-an-agent-loop If you already drive Claude Code or Codex one chat at a time, you have run the raw material of a loop. This guide is about turning that one-off work into something repeatable you can trust to run again. An agent loop is an agent repeating a cycle of work — do it, check it, go again — until a clear stop condition is met. The shape is simple: do the work, check it, go again — until it's done. The check is the whole trick. It's what turns "an agent trying repeatedly" into "an agent you can walk away from": the result of the check — not your attention — decides whether the loop continues or stops. A loop is not just "AI doing stuff" on repeat. It is repeated work with a stated shape: a **goal**, the **context and inputs** it may touch, **checks** that run each pass, **state and logs** that outlive any one session, a **trigger or cadence** that starts it, a **budget and stop condition**, and plain **evidence of done**. Miss those and you don't have a loop you can trust — you have an agent you have to babysit. Loops stop for three reasons: the check finally succeeds, the agent needs your input, or it runs out of the budget you gave it. ## The progression The same seven parts scale from a single chat to a loop that improves itself. Each step adds one thing and keeps the rest: - **Chat loop** — the one-off session you already run: you steer, you check, you decide when it's done. - **Task loop** — one bounded job with a check that decides when it stops, so you don't have to re-prompt "keep going." - **Scheduled loop** — the same task, started by a trigger or cadence (a cron job, a CI step) instead of by hand. - **Self-improving loop** — a meta-loop that reads its own run logs and tunes the goal, checks, or budget for next time. You don't jump to the end. Get a task loop trustworthy first; add a schedule only once its check and stop condition hold on their own. ## You might not need a loop A one-off small task is a prompt, not a loop. Start simple. Add the loop when you catch yourself re-prompting "keep going," checking the same result again, or asking the agent to try until a clear condition is met. If the work only needs one answer, ask once. If the work needs repeated tries until a check passes, give the agent a loop. ## Start a loop in your own repo You don't need this site, or any new tool, to run a loop. If you use Claude Code or Codex, you already have one. Both can keep working, check their own result, and stop on a condition you set — inside your own project, on your own machine. The path is short: **choose Claude Code or Codex**, **define a real task** (not a toy), **define the check** that says it passed, decide where **state and logs** live, set a **cadence or trigger** — for a first run, "by hand, once" is fine — then **run it once**. If the run earned its keep, keep it and improve it; if it didn't, throw it away. That last step is the loop part: you only schedule what already works by hand. The fastest way to feel it: open a terminal in a repo that has a failing test, and give the agent a goal with a built-in stop. ### Claude Code In your repo, run `claude`, then give it a goal. Claude Code's `/goal` keeps working and checks a completion condition after each turn, so it continues on its own until the condition is met or you stop it. - **Goal:** get the test suite to green. - **Inputs:** your repo and the command that runs the tests. - **Check (runs each pass):** `npm test` exits 0. - **Trigger:** you start it by hand, once, when you want the fix. - **State and logs:** the session transcript, plus the branch diff or commits you can read afterward. - **Stop condition:** green, or five turns spent, or a question only you can answer. - **Done means:** `npm test` exits 0 and the change touches app code, not the tests. ``` /goal Make `npm test` pass without editing or deleting any test. Run the suite after each change. Stop when it exits 0, after 5 turns, or when you hit something only I can decide — and tell me which one. ``` ### OpenAI Codex In the same repo, start Codex and set a Goal. A Codex Goal is a persistent objective with an outcome, a way to verify it, constraints, and a budget — it keeps attempting and checking until one of those conditions ends the run. - **Goal:** get the auth tests to green. - **Inputs:** your repo and the auth test command. - **Check (runs each pass):** `pytest tests/auth` exits 0. - **Trigger:** you start it by hand, once. - **State and logs:** the Codex thread, the branch diff, and any durable repo rules in `AGENTS.md`. - **Stop condition:** green, or six attempts, or a blocker that needs a credential or a decision. - **Done means:** `pytest tests/auth` exits 0 with the tests unchanged and edits kept to `src/auth/`. ``` Goal: Make the auth tests pass. Outcome: `pytest tests/auth` exits 0. Verify: run `pytest tests/auth` after each attempt and read the output. Constraints: don't change the tests; keep edits inside `src/auth/`. Budget: stop after 6 attempts or 20 minutes. Blocked: if a fix needs a credential or a product decision, stop and ask. ``` Both examples name the same seven things, and every loop worth trusting names them too: a **goal**, the **inputs** it may touch, a **check** that runs each pass, what **triggers** it, where its **state and logs** live, a **stop condition**, and a plain definition of **done**. Write those down before you start and the loop always has somewhere to stop. To move from "started by hand" to "runs on a schedule," keep the same seven parts and add a trigger — a cron job, a CI step, or a scheduled task. The cadence is the only thing that changes; the check and the stop condition stay exactly as they are. ## Loop, prompt, workflow Three words get used as if they were interchangeable. They aren't. - **A prompt** runs once. You ask, it answers, it's over. Nothing carries forward except what you copy out by hand. - **A workflow** runs steps in a fixed order. Step three follows step two because the diagram says so, not because a check decided the work needed another pass. When the last step finishes, the workflow is done — whether or not the work is. - **A loop** repeats a pass until a check and a stop condition say otherwise. The number of passes isn't known in advance; that's the point. It keeps going while the work needs it, and it stops for a stated reason. A workflow answers "what happens next?" with a diagram. A loop answers it with a check. ## Where this site fits loopmaster.ai is not a runtime, and it is not required to run a loop — the two examples above run entirely inside Claude Code or Codex. This site is optional support for after a real loop exists: a plain format for writing the loop down, a pass log for recording that a run actually met its check, and a way to share a loop other people can read. Build the loop in your own repo first; reach for the extras only if they earn their place. ## Read more Clear, current sources on the same idea: - [Anthropic — Getting started with loops](https://claude.com/blog/getting-started-with-loops): the on-ramp from a one-off Claude Code chat to a repeatable, scheduled loop. Start here. - [Claude Code — Keep Claude working toward a goal](https://docs.anthropic.com/en/docs/claude-code/goal): the `/goal` completion condition, checked after each turn. - [Codex — Using Goals in Codex](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex): outcome, verification, constraints, and budget for a Codex Goal. - [Codex — Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md): durable, per-repo rules every run reads. - [OpenAI — Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/): what the agent loop is actually doing under the hood. - [Anthropic — Building effective agents](https://www.anthropic.com/research/building-effective-agents): when a simple workflow beats a loop, and the simplest pattern that works. - [Simon Willison — An LLM agent runs tools in a loop to achieve a goal](https://simonwillison.net/2025/Sep/18/agents/): the shortest useful definition of the idea. - [Addy Osmani — Loop Engineering](https://addyosmani.com/blog/loop-engineering/): designing the recurring system around the model, not just the prompt. ## Do this next Reading about loops is not running one. Pick one of the two examples above, run it in a repo you already have, and watch it stop for a stated reason. Prefer a guided path with a checked log? [Start from the Quick Start](/quick-starts/qs1-first-task-loop).