| name | ralph-wiggum |
| description | Long-running iterative development loops with pacing control and verifiable progress. Use when tasks require multiple iterations, many discrete steps, or periodic reflection with clear checkpoints; avoid for simple one-shot tasks or quick fixes. |
Ralph Wiggum - Long-Running Development Loops
Use the ralph_start tool to begin a loop:
ralph_start({
name: "loop-name",
taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2",
maxIterations: 50, // Default: 50
itemsPerIteration: 3, // Optional: suggest N items per turn
reflectEvery: 10, // Optional: reflect every N iterations
compactEachRound: true // Default: compact context before each new round
})
Loop Behavior
- Write the task file: Create
.ralph/<name>.md with the task content. The tool does NOT create this file—you must write it yourself using the Write tool.
- Work on the task and update the file each iteration.
- Record verification evidence (commands run, file paths, outputs) in the task file.
- By default, Ralph compacts context before queuing the next iteration unless
compactEachRound: false is used.
- Call
ralph_done to proceed to the next iteration.
- Output
<promise>COMPLETE</promise> when finished.
- Stop when complete or when max iterations is reached (default 50).
User Commands
/ralph start <name|path> [--no-compact-each-round] - Start a new loop./ralph resume <name> - Resume loop./ralph stop - Pause loop (when agent idle)./ralph-stop - Stop active loop (idle only)./ralph status - Show loops./ralph list --archived - Show archived loops./ralph archive <name> - Move loop to archive./ralph clean [--all] - Clean completed loops./ralph cancel <name> - Delete loop./ralph nuke [--yes] - Delete all .ralph data.
Press ESC to interrupt streaming, send a normal message to resume, and run /ralph-stop when idle to end the loop.
Task File Format
# Task Title
Brief description.
## Goals
- Goal 1
- Goal 2
## Checklist
- [ ] Item 1
- [ ] Item 2
- [x] Completed item
## Verification
- Evidence, commands run, or file paths
## Notes
(Update with progress, decisions, blockers)
Best Practices
- Write a clear checklist with discrete items.
- Update checklist and notes as you go.
- Treat the task file as canonical memory, especially with default per-round compaction.
- Capture verification evidence for completed items.
- Reflect when stuck to reassess approach.
- Output the completion marker only when truly done.
