tomevault-io 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
})
Loop Behavior
- Write the task file: Create
.ralph/<name>.mdwith 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.
- Call
ralph_doneto 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>- 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.
- Capture verification evidence for completed items.
- Reflect when stuck to reassess approach.
- Output the completion marker only when truly done.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.