Lesson 3 · 18 min
There are five common ways to put an agent in a loop, and they answer two questions differently: what triggers the next turn and who decides when to stop. Choosing wrong gets expensive: a /loop waiting for a condition that never comes, a /goal that believes what the agent said. Here is only what the official documentation confirms, read on 10/19/2026.
Start the lesson
Goal: choose the right loop engine for a task by knowing where it runs, what triggers the next turn, who decides when to stop, and the limit of each one.
Click each engine: what triggers the next turn, who decides when to stop, and the limit the official docs give.
Scroll the page: each step below lights up its part of the diagram.
After each turn, a small model judges your condition: met, not met, or impossible. It's a prompt-based Stop hook, per session. Limit: the evaluator doesn't run commands or read files, it only judges the conversation; the proof has to be printed out. It doesn't change the permission mode. With -p it runs to the end in a single call.
Repeats a prompt at a fixed interval (/loop 5m …) or at one Claude picks on each round, from 1 minute to 1 hour. Limits: it belongs to the session and only fires while Claude Code is open and idle; minimum of 1 minute; a recurring task expires after 7 days; the self-paced one doesn't come back on --resume. It's for watching, not for chasing a condition.
A technique described by Geoffrey Huntley: in its pure form, a bash loop that calls the agent with the same prompt, endlessly. Each session is disposable; what remains is in the files and in git. Anthropic cites the pattern as a community convergence. Limit: it has no stop or verification out of the box; you add those yourself (lessons 6 and 7).
A saved configuration (prompt, repositories, connectors) that runs on Anthropic's infrastructure, with your laptop closed. Limits: it's in research preview (behavior and limits may change); it works on a fresh clone, with no access to your local files; minimum interval of 1 hour on the schedule.
Runs Codex without an interface: it takes the request as an argument or via stdin, works, and exits. By default the sandbox is read-only; --sandbox workspace-write allows editing. --json gives the events as JSONL, -o saves the last message, exec resume --last continues the previous one. Limit: it isn't a loop; the loop, the test, and the stop live in a script of your own (the headless loop is course 2).
Does the next turn come from a condition, a clock, or a loop of your own? And who decides to stop: an evaluator that reads the conversation, you, or a test that actually runs? The engine that runs the test outside the conversation is the hardest to fool.
Sources: official Claude Code docs (/goal, scheduled tasks, routines) and Codex docs (non-interactive mode), read on 10/19/2026; ghuntley.com/ralph.
A rule of thumb based on the limits above.
Migrate a module until it compiles and the tests pass, empty a queue of issues. The condition needs an end state, the command that proves it, and what must not change along the way.
Put a cap on the condition itself, as the doc suggests: "or stop after 20 turns".
python3 -m pytest -q tests/ prints 6 passed, no file in tests/ was modified, or stop after 15 turns
Did the deploy finish? Did the CI pass? Did a comment arrive on the PR? Time triggers the next round, and each round looks again.
Close the terminal and it stops. To last longer than the session, use a cloud schedule, the Desktop app, or GitHub Actions, as the doc itself points out.
Each cycle is a new session that rereads the state from a file; what decides whether to continue is the test run by the script, not the conversation.
This is what the execucao-longa kit does, with a cap on time and memory (course 2).
PR review on an event, nightly issue triage: repeatable work in a repository, without depending on the files on your machine.
Since it is in research preview, check the limits in the doc before depending on it.
Commands from the official documentation and from the Ralph article. Run only the ones you will actually use.
/goal python3 -m pytest -q tests/ prints 6 passed and git diff --stat -- tests/ comes out empty, or stop after 15 turns /goal clear claude -p "/goal CHANGELOG.md has an entry for each PR this week" --output-format stream-json --verbose
/loop 5m check whether the deploy finished and tell me what happened /loop check whether CI passed and reply to the review comments
while :; do cat PROMPT.md | claude-code ; done
codex exec "count the .md files in this folder and reply with just the number" codex exec --sandbox workspace-write "create ola.txt with the word ola" codex exec --json "summarize the repository structure" > eventos.jsonl codex exec resume --last "now fix what you found"
As written, the loop has no stop and no verification: it runs until you press Ctrl+C. The executable name in the article is the author's; on your machine it would be claude -p or codex exec -. In lessons 6 and 7 you add the done criterion and the caps that are missing.
The execucao-longa kit uses /goal in Codex as well (with /goals and /goal pause|resume). This track's research did not find the official page with its date and limits; so this course claims nothing beyond the use in the kit.
On your machine. These are short runs: they use little of your quota.
In an empty folder with git initialized, open Claude Code and run: /goal the file ola.txt exists and cat ola.txt prints ola in the conversation, or stop after 5 turns.
Done when: cat ola.txt → ola, and the goal status in Claude Code shows the condition as met, with the turn count.
In the same folder, ask Codex in headless mode to count files, writing the last message to a file.
Done when: codex exec -o resposta.txt "how many .txt files are in this folder? answer with just the number"; echo "saída: $?" → saída: 0, and grep -cE '^[0-9]+$' resposta.txt → 1 (the answer is a single line with just a number; the criterion checks the format, not what the model answered).
List three real tasks of yours in a file motores.md, one per line, in the format task → engine → why (trigger and who decides to stop).
Done when: grep -c '→.*→' motores.md → 3, and no task with a verifiable end was left with /loop.
Question 1 of 5
Your /goal condition is "all tests pass". The agent writes "I ran the tests, all pass" without showing the output. What happens?competency
Question 2 of 5
You want to check the CI every 10 minutes during the afternoon, with the terminal open. Which engine?
Question 3 of 5
Why is a routine not suited to running the tests of a project that only exists on your laptop?
Question 4 of 5
What is missing from Ralph in its pure form, while :; do cat PROMPT.md | claude-code ; done?competency
Question 5 of 5
Will a recurring /loop created today still run a month from now?
Choose one answer. The explanation appears after you try.