Iterative Runner
Runs Claude in a persistent loop that keeps retrying until tests pass or the task is complete.
When to Use
- Running TDD loops that iterate until all tests pass
- Overnight builds that need to keep trying until successful
- Any task requiring repeated attempts until completion criteria are met
- Automated retry for flaky or complex implementations
Core Concept
while :; do cat PROMPT.md | claude ; done
Keep iterating until task is complete.
Workflow
Step 1: Define Completion Criteria
Specify clear success conditions:
- All tests passing
- No linter errors
- Specific output marker (e.g.,
<promise>DONE</promise>)
Step 2: Set Safety Limits
Always use --max-iterations to prevent infinite loops.
Step 3: Run the Loop
# Basic loop
iterative-runner "Build feature X" --completion-promise "DONE" --max-iterations 30
# TDD loop
iterative-runner "Implement feature using TDD.
1. Write failing test
2. Implement to pass
3. Run tests
4. Fix if failing
5. Repeat
Output <promise>DONE</promise> when all tests green." --max-iterations 50
Prompt Best Practices
- Clear completion criteria - Define what "done" means
- Incremental goals - Break into phases
- Self-correction - Include retry logic
- Escape hatch - Always use --max-iterations
Template
Implement [FEATURE].
Requirements:
- [Requirement 1]
- [Requirement 2]
Success criteria:
- All tests passing
- No linter errors
After 15 failed iterations:
- Document blockers
- List attempted approaches
Output <promise>COMPLETE</promise> when done.