Ralph Wiggum - Long-Running Development Loops
Long-running iterative development loops with pacing control.
When to Use
- Complex tasks requiring multiple iterations
- Tasks with many discrete steps that build on each other
- Work that benefits from periodic reflection
Do NOT use for simple one-shot tasks or quick fixes.
Agent Tool
Call ralph_start to begin a loop on yourself:
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
useSubagents: true, // Optional: delegate each task to subagent
subagentAgent: "default" // Optional: subagent name (default: 'default')
})Loop Behavior
- Task content is saved to
.ralph/<name>.md - Each iteration: work on task, update file
- Call
ralph_donetool to proceed to next iteration - When complete: output
<promise>COMPLETE</promise> - Loop ends on completion or max iterations (default 50)
User Commands
/ralph start <name|path>- 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
During streaming: press ESC to interrupt, 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
## Notes
(Update with progress, decisions, blockers)Subagent Mode
Delegate each checklist task to a separate subagent thread:
/ralph start my-tasks --use-subagents --subagent-agent defaultHow it works:
- Extracts uncompleted checklist items (
- [] Task) - Each task is delegated to a fresh subagent thread (1 task = 1 subagent)
- Subagent completes task and marks it done (
- [x] Task) - Main loop orchestrates and tracks progress
- Automatic retry logic for failures (2 attempts)
Benefits:
- Fresh context per task (no pollution)
- Isolated execution (failures don't cascade)
- Clear task tracking and progress reporting
- Suitable for independent, discrete tasks
When to use:
- Tasks are independent (no shared state)
- Each task is substantial enough for separate execution
- You want clean separation between tasks
- Task list is well-defined upfront
Best Practices
- Clear checklist: Break work into discrete items
- Update as you go: Mark items complete, add notes
- Reflect when stuck: Use reflection to reassess approach (normal mode)
- Complete properly: Only output completion marker when truly done
- Subagent mode: Use for independent tasks with clear boundaries