AI Agent Loop Prompt BuilderTurn a one-shot task into a self-checking loop prompt
Fill the 9 slots, get a copy-paste loop prompt scored for safety. Works with Claude Code, Cursor, Codex, Factory (Droid), and Devin.
Published June 21, 2026 · By Jim Liu(verified in production agent loops)
TL;DR
- A loop prompt is not a one-shot prompt. It instructs an agent to repeat a fixed cycle: inspect, change one thing, check, record. It keeps going until a success gate is met or a budget runs out.
- Use a loop when the goal has a measurable check. Failing tests, slow routes, stale content. Anything with a concrete pass/fail signal. For open-ended tasks with no clear check, a one-shot prompt is safer.
- The 9 slots are: trigger, fresh inputs, action criteria, acceptance check, state file, budget, success gate, escalation condition, deliverable. Each slot has a distinct job. Missing any one of the first four produces an unsafe loop.
- Safety rule: score your loop before scheduling it. A loop without a budget cap and an escalation condition can run forever and take destructive actions. The builder on this page scores your loop from 0 to 100 and lists each missing guardrail.
Loop prompt builder
Fill the 9 slots below. The prompt assembles live and the safety score updates as you type. No signup, no network calls.
The 9 loop slots
Needs guardrails
Score breakdown
Generated loop prompt
When [trigger condition], inspect [fresh inputs]. Choose one bounded, reversible action using [action criteria] and make the change. Run [acceptance check] under the same conditions each time. Record changes and evidence in [state file]. Repeat while progress is measurable and [budget] remains. Stop when [success gate] is true or no useful change remains. Ask for approval when [escalation condition]. Finish with [deliverable].
Where to put this in Claude Code
Paste this prompt into a CLAUDE.md Routine or run it with /loop. Store standing rules in CLAUDE.md so the loop re-reads them on each pass.
Example loops
5 ready-to-load templatesClick any card to load all 9 slots into the builder above. Edit before copying.
Anatomy of an agent loop prompt
Each slot has a single job. Conflating two slots in one field makes the prompt ambiguous and produces worse agent behavior. Fill them separately, then let the builder assemble the canonical sentence.
- 1. Trigger
- The condition that starts the loop. For a goal loop, this is a problem state: "any test is red" or "p95 exceeds 50ms". For a scheduled loop, this is a time or event: "every Monday at 09:00 UTC" or "on each new GitHub release". Keep the trigger testable from the outside so you can verify it without running the loop.
- 2. Fresh inputs
- The data the agent reads at the start of each pass. Name the file, report, or API call explicitly. "The current state of the codebase" is too vague; "the test runner output from the previous run" is specific and re-runnable. Fresh inputs must be different from the state file. They are read-only source material, not the agent's own notes.
- 3. Action criteria
- The rule the agent uses to pick exactly one bounded, reversible change per pass. The "one change" constraint is the most important part of loop engineering. Agents that make multiple changes per pass create a tangled state file and make it impossible to tell which change caused an improvement. State the priority rule (highest-impact first, fewest dependencies first) and the reversibility constraint (no schema changes, no deleting production data).
- 4. Acceptance check
- The fixed, deterministic test run at the end of every pass. It must be re-runnable under the same conditions each time and produce a comparable result. A test suite, a load test with numeric thresholds, a linting rule count. Anything with a concrete number or exit code. A subjective check ("the output looks good") makes the loop incomparable across passes and removes the agent's ability to detect regression.
- 5. State file
- Where the agent records what it changed and what the acceptance check returned after each pass. A simple markdown file at the project root is enough. The state file is the loop's memory. Without it, a restart loses all history. It also gives you an audit trail for the changes made under autonomous control.
- 6. Budget
- The hard cap on iterations, time, or scope. Examples: "10 iterations or 30 minutes, whichever comes first", "5 packages", "files in the src/ directory only". The budget is a safety net, not a target. A well-designed loop should hit its success gate before hitting the budget on most problems. If it consistently hits the budget instead, the acceptance check or action criteria need tightening.
- 7. Success gate
- The condition that means the loop is genuinely done, independent of budget. Three consecutive green test runs. p95 under 50ms for two passes in a row. Zero items in the stale-content list. Without a distinct success gate, a loop that hits its budget looks the same as a loop that solved the problem. The agent reports "done" either way and you cannot tell which happened from the state file alone.
- 8. Escalation condition
- When should the agent stop and ask a human instead of making a change? List the risky or irreversible situations: schema migrations, deleting production data, changing a third-party API contract, fixing a test by weakening its assertions. The escalation condition is your control surface. It defines where autonomous action ends and human judgment begins.
- 9. Deliverable
- The artifact handed off when the loop exits, whether via success gate or budget. Name the file or report specifically. A clean state file and the final acceptance check output together make a complete deliverable for most goal loops. Scheduled loops typically deliver a summary report appended to the state file.
Goal loops vs scheduled loops
The two loop types differ in trigger structure and what happens after a pass completes. Choosing the wrong type is the most common setup mistake. A goal loop running on a schedule wastes budget when there is nothing to fix.
| Goal loop | Scheduled loop | |
|---|---|---|
| Trigger | A problem state: "tests are red", "p95 over 50ms" | A time or event: "every Monday 09:00 UTC" |
| Runs when | Immediately, on demand | At the next scheduled time, whether or not a problem exists |
| Exits when | Success gate met or budget exhausted | Pass complete; waits for the next trigger |
| State file use | Tracks progress toward the goal across passes | Tracks session history across multiple scheduled runs |
| Best for | Fixing a known problem: failing tests, performance regressions, outdated deps | Maintenance tasks: content freshness, nightly scans, weekly reports |
| Risk if misused | Runs until budget is exhausted if the success gate is unreachable | Makes changes when no problem exists; state file accumulates noise |
Where to run your agent loop prompt
Each tool has a different home for loop rules and a different mechanism for recurring runs. The builder output panel shows the setup note for your selected tool automatically.
Claude Code
Use the /loop command inside a session, or store the prompt in a CLAUDE.md Routine for persistent loop rules.
Best for: Goal loops during active development sessions; standing loops via Routines.
Not ideal for: Long-running overnight scheduled loops without a session open.
Cursor
Add the prompt as a named rule in .cursor/rules, then wire it to a Cursor Automation on the desired trigger.
Best for: IDE-resident loops that respond to file changes or test failures inside Cursor.
Not ideal for: Loops that need to run outside the IDE or access external services not available in the Cursor sandbox.
Codex
Place the prompt in AGENTS.md at the repo root. Codex Worktree threads read AGENTS.md on each task spawn.
Best for: Parallel goal loops across multiple worktrees; dep-upgrade and test-fix patterns.
Not ideal for: Scheduled loops that need a persistent process between runs.
Factory (Droid)
Load the prompt as a Droid CLI task with the appropriate autonomy level. Set budget as a hard constraint in the Droid config.
Best for: Autonomous goal loops with clear acceptance checks and well-defined escalation boundaries.
Not ideal for: Loops that require interactive human input mid-pass.
Devin
Add the loop as a Playbook in your Devin workspace. Scheduled loops map to Devin scheduled sessions.
Best for: Scheduled maintenance loops like content refreshes and nightly scans.
Not ideal for: Loops that need tight real-time interaction with a local development environment.
Common loop failures and how to avoid them
Vague goal
The trigger or success gate is subjective ("make the code cleaner"). The agent has no way to measure progress and will either do nothing useful or make arbitrary changes.
Fix: Replace subjective goals with measurable checks. "Test suite exits 0" is concrete; "code looks better" is not.
Drifting acceptance check
The acceptance check changes between passes. The agent re-runs tests with a different seed, or checks a different file. Results become incomparable and the loop cannot detect regression.
Fix: Lock the acceptance check to the same command with the same flags and inputs every pass. No randomness, no side effects.
No budget
Without a budget cap, the loop runs until the success gate is met or an external process kills it. On a hard problem this means unlimited compute cost and potential destructive drift.
Fix: Set a budget that is realistic for the problem size. "10 iterations or 30 minutes" is a sensible default for most goal loops.
No escalation on destructive actions
The agent is allowed to delete files, migrate schemas, or change API contracts without asking. One wrong pass can cause irreversible damage.
Fix: List every action type that is hard to reverse in the escalation condition. The agent will stop and ask rather than proceed autonomously.
Never run by hand first
The trigger condition is mis-specified, the state file path does not exist, or the acceptance check fails immediately because the environment is wrong. The first scheduled run fails silently.
Fix: Run the loop once manually before scheduling. Fix any setup errors before handing off to the scheduler.
Frequently asked questions
- How do I write an agent loop prompt?
- An agent loop prompt needs 9 parts: trigger, fresh inputs, action criteria, acceptance check, state file, budget, success gate, escalation condition, and deliverable. Use the builder above to fill each slot. The canonical shape is: "When [trigger], inspect [fresh inputs]. Choose one bounded, reversible action using [action criteria] and make the change. Run [acceptance check] under the same conditions each time. Record changes and evidence in [state file]. Repeat while progress is measurable and [budget] remains. Stop when [success gate] is true or no useful change remains. Ask for approval when [escalation condition]. Finish with [deliverable]."
- What is the difference between a goal loop and a scheduled loop?
- A goal loop starts immediately and runs until its acceptance check passes or the budget runs out. Use it when you have a known problem to fix: failing tests, a slow route, outdated deps. A scheduled loop fires on a recurring trigger and reports before waiting for the next event. Use it for maintenance tasks that run regardless of whether a problem is active: weekly content freshness checks, nightly scans, daily performance monitoring.
- How do I stop an AI agent loop from running forever?
- Define two hard limits: a budget cap (for example, "10 iterations or 30 minutes, whichever comes first") and an escalation condition that fires when no progress has been made for N consecutive passes. The budget cap prevents runaway cost; the escalation condition hands control back to a human when the agent is stuck. Without both, the loop can exhaust your compute budget before you notice.
- What is an acceptance check for an AI agent?
- A fixed, deterministic test or benchmark the agent runs at the end of every pass to measure progress. It must produce a comparable result each time so the agent can tell whether the last change helped or hurt. Good examples: a test suite that exits 0, a load test with a p95 threshold, a linting rule count. A vague check ("the code looks better") breaks the loop because the agent has no objective signal.
- Should I run an agent loop prompt manually first?
- Yes. A manual run catches three common failure modes: a trigger that never fires because the condition was mis-specified, an acceptance check that fails immediately because the environment is wrong, and a state file path that does not exist. Manual runs take about 5 minutes and prevent wasted scheduled runs that fail silently.
- Does Claude Code have a loop command?
- Yes. Claude Code supports a /loop command for running a prompt repeatedly within a session. For standing loop rules that should apply every session, store the loop prompt in a CLAUDE.md Routine. Routines load on session start so the agent can continue from the state file defined in the previous run.
Related agent tools on OpenAI Tools Hub
About the author
Built by Jim Liu, who uses agent loop prompts in production for SEO content pipelines, nightly dependency upgrades, and automated performance regression detection across a portfolio of web tools.