A design framework for AI agent loops built on three questions — when should it run (schedule), what does done mean (goal), and who does the isolated pieces (subagents) — with worked examples in Claude Code and Codex.
Design framework: choose schedule (when), goal (what done means), subagents (who does isolated pieces) — with worked examples in Claude Code and Codex.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
The two-layer answer to how do I run this overnight: /goal drives in-session work to done, while a scheduled Routine keeps recurring unattended work running on Anthropic's cloud with your laptop closed.
/schedule a Routine (runs on Anthropic cloud, laptop closed) for recurring unattended work, and use `/goal` for in-session iterate-to-done — the two-layer overnight pattern.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
The spec-driven maturation of the Ralph loop: each fresh-context iteration reads PLAN.md, implements the highest-priority unchecked item, checks it off, and commits — so the spec file evolves alongside the codebase.
Ralph variant where the loop prompt is "read PLAN.md, pick highest-priority unchecked item, implement, check it off, commit, exit" — spec file evolves with the codebase.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Keep changes minimal and never touch files outside the task’s scope.
A hands-free ops loop that polls your deploy every two minutes, runs the smoke test the moment it goes live, and stops with a report if any check fails.
/loop every 2 minutes: check deploy status; when it's live, run the smoke test and summarize; if smoke test fails, report the failing check and stop
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Keep changes minimal and never touch files outside the task’s scope.
Anthropic's first-party file-as-memory harness for long-running agents: every fresh-context session recovers state from a progress file and the git log, does one unit of work, updates the file, commits, and exits.
Long-running agent harness: each fresh-context session starts by reading `claude-progress.txt` + git log to recover state, does one unit of work, updates the progress file, commits, exits. Initializer session sets up the file; coder sessions loop.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
Anthropic's first-party take on the Ralph loop: a Claude Code plugin that runs the iterate-fresh-context pattern with a managed stop and iteration mechanism built in.
Install the `ralph-wiggum` plugin from the anthropics/claude-code repo; it wraps the Ralph loop with a managed stop/iteration mechanism inside Claude Code.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
The canonical Ralph Wiggum loop by Geoffrey Huntley: a bash while-loop that feeds Claude Code one fresh-context iteration at a time, using the filesystem and git as memory. Run it only in a sandboxed environment with permissions configured — never with permission checks disabled.
`while :; do cat PROMPT.md | claude -p ; done` — PROMPT.md holds the spec + "pick ONE task from the plan, implement, test, commit, exit." Fresh context every iteration; filesystem + git = memory.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Keep changes minimal and never touch files outside the task’s scope.
Move the project to the current Node LTS across .nvmrc, CI config, Dockerfiles, and engines, fixing deprecations until everything is green on the new runtime.
/goal the project runs on the current Node LTS — update .nvmrc, the engines field, CI workflow files, and any Dockerfile base images to the LTS version, then run install, build, lint, and the full test suite on it, fixing deprecation warnings and breakages one at a time; stop when all are green or after 15 turns
Drive a suspected memory leak to ground: reproduce growth under a repeated workload, capture heap snapshots, and fix the retention until memory stays flat.
/goal heap usage stays flat (within 5%) across 500 repetitions of the failing workload in the leak-repro script — capture heap snapshots before and after, identify what is being retained and by which reference chain, fix the leak, and re-run the repro to confirm; stop after 10 turns
Rewrite the commit messages on your feature branch to conventional-commit format with meaningful bodies before opening the PR, leaving the code untouched.
/goal every commit on this branch (ahead of main) has a conventional-commit subject under 72 characters and a body explaining why — use interactive rebase to reword only (no code changes, no commits dropped), verify with `git log main..HEAD`, and confirm the diff against the original branch tip is empty; stop after 5 turns
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
Document one undocumented public module per fresh-context iteration, verifying every code sample compiles and accumulating style rules in guardrails so the docs read like one author wrote them.
/loop fresh context each iteration: read docs-backlog.json, docs/STYLE.md, and .ralph/guardrails.md; pick the top undocumented module, write its reference page with a runnable example, execute the example to prove it works, and mark the module done; add any style or structure decision to .ralph/guardrails.md; stop when the backlog is empty or after 20 turns
Break a large refactor into a JSON backlog of modules and let fresh-context iterations convert one module per pass, with guardrails capturing every pattern decision so the result stays consistent.
/loop fresh context each iteration: read refactor-plan.json and .ralph/guardrails.md, take the next module not marked converted, migrate it to the target pattern described in PROMPT.md, run tests and typecheck, and mark it converted only when green; record every convention decision you make (naming, file layout, error handling) in .ralph/guardrails.md so later modules match earlier ones; stop when all modules are converted or after 30 turns
Iterate over a prioritized list of untested modules with fresh context each pass, writing real behavioral tests for one module at a time and banking lessons in a guardrails file.
/loop each iteration with fresh context: read .ralph/test-backlog.json and .ralph/guardrails.md, pick the top unfinished module, write behavioral tests for its public API (no snapshot-only tests), run the suite, and mark the module done only when its tests pass and coverage for it exceeds 80%; append any discovered testing gotcha (fixtures, mocking rules, async traps) to .ralph/guardrails.md; stop when the backlog is empty or after 25 turns
The canonical Ralph loop: each iteration starts fresh, reads the PRD and guardrails, ships exactly one backlog item end-to-end, and records what it learned.
/loop start each iteration with fresh context: read PROMPT.md, prd.json, and .ralph/guardrails.md; pick the single highest-priority item in prd.json not marked done, implement it with tests, run the full check suite, commit and mark it done only if green; if blocked or a check fails twice the same way, append the lesson to .ralph/guardrails.md and move on; stop when every item is done or after 30 turns
/goal CHANGELOG.md has a complete entry for the next release — read every commit since the last version tag, group changes into Added, Changed, Fixed, and Removed, write user-facing descriptions (not commit messages), link PR numbers, and flag anything that looks like a breaking change; stop after 5 turns
/goal `gitleaks detect --no-git` reports zero findings — for each finding, tell me whether it looks like a real credential (flag it for rotation and replace it with an env var lookup) or a false positive (add it to the baseline with a comment); never print the secret value itself; stop after 8 turns
/goal every path in openapi.yaml has a contract test asserting its status codes and response schema — add tests for one untested endpoint per turn, run the suite, and fix either the spec or the handler when they disagree (tell me which you chose); stop when all paths are covered or after 15 turns
Instrument the test suite with query logging, find endpoints issuing N+1 queries, and fix them with eager loading or batching until the hot paths are clean.
/goal no endpoint in the integration test suite issues more than 10 SQL queries per request — enable query logging in the test environment, find the worst N+1 offender, fix it with eager loading or a batched query, verify the count dropped and tests still pass, then move to the next; stop after 12 turns
/goal `npm outdated` lists no minor or patch updates — upgrade exactly one package per turn, run tests, lint, and build after each, commit if green, and pin the previous version with a note in UPGRADE-BLOCKERS.md if it fails; stop after 20 turns
/goal `npx knip` reports no unused files or exports — remove one cluster of dead code at a time, run the full test suite and typecheck after each removal, and revert any deletion that breaks them; stop after 15 turns
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
A Ralph-style loop that writes its own rules: when a check fails the same way twice, the failure pattern gets appended to a guardrails file that every later iteration reads first.
/loop read .ralph/guardrails.md before doing anything, then run the full check suite and fix the first failure; if a check fails twice with the same error, append the failure pattern and a one-line rule for avoiding it to .ralph/guardrails.md before retrying; stop when all checks pass or after 15 turns
/goal all database migrations apply cleanly — run them, fix schema or SQL errors, repeat until `npx prisma migrate status` is clean; stop after 6 turns
/goal the recent diff is clean and convention-aligned — review it for debug code, dead branches, and bad names, fix with minimal edits until `npm run lint && npm test` passes; stop after 4 turns
/goal a PR is open for this change and every CI check passes — implement it, test locally, push, open the PR with `gh pr create`, then keep fixing failures (re-check with `gh pr checks`) until green; stop after 10 turns