Eric Zakariasson
e87eaecc7b
* Add Ralph Loop plugin Port of the Ralph Wiggum technique from Claude Code to Cursor. Runs Cursor in a self-referential loop, feeding the same prompt back after every turn until a completion condition is met. Components: - Stop hook that intercepts session exit and re-injects the prompt - Setup script for initializing loop state - Skills for starting, cancelling, and explaining the loop Co-authored-by: Cursor <cursoragent@cursor.com> * Comply with Cursor hooks API - Rewrite hooks.json to Cursor format (version 1, lowercase event names, flat structure, loop_limit: null) - Replace Claude Code stop hook output (decision/block/reason) with Cursor's followup_message API - Add afterAgentResponse hook to detect completion promise without depending on transcript format - Use CURSOR_PROJECT_DIR env var for reliable state file paths - Remove setup script; ralph-loop skill now instructs the agent to create the state file directly - Update cancel-ralph skill to clean up done flag file Co-authored-by: Cursor <cursoragent@cursor.com> * Move state files to .cursor/ralph/ subdirectory State file: .cursor/ralph/scratchpad.md Done flag: .cursor/ralph/done Cancel cleans up with rm -rf .cursor/ralph Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
2.4 KiB
Ralph Loop
Ralph Loop runs Cursor in a self-referential loop, feeding the same prompt back after every turn until the task is complete. It implements the Ralph Wiggum technique pioneered by Geoffrey Huntley.
How it works
Two hooks drive the loop. An afterAgentResponse hook watches each response for a <promise> tag matching the completion phrase. A stop hook fires when Cursor finishes a turn. If the promise hasn't been detected and the iteration limit hasn't been reached, the stop hook sends the original prompt back as a followup_message, starting the next iteration. Cursor sees its own previous edits in the working tree and git history, iterates on them, and repeats. The prompt never changes. The code does.
Installation
agent install ralph-loop
Quick start
Start a ralph loop: "Build a REST API for todos. CRUD operations, input validation, tests. Output COMPLETE when done." --completion-promise "COMPLETE" --max-iterations 50
Cursor will implement the API, run tests, see failures, fix them, and repeat until all requirements are met.
Skills
ralph-loop starts the loop. Provide a prompt and options:
Start a ralph loop: "Refactor the cache layer" --max-iterations 20 --completion-promise "DONE"
--max-iterations <N>stops after N iterations (default: unlimited)--completion-promise <text>sets the phrase that signals completion
cancel-ralph removes the state file and stops the loop.
ralph-loop-help explains the technique and usage in detail.
Writing good prompts
Define explicit completion criteria. Vague goals like "make it good" give Cursor nothing to verify against.
Build a REST API for todos.
When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- Output: <promise>COMPLETE</promise>
Break large tasks into phases. Encourage self-correction by including test/fix cycles in the prompt. Always pass --max-iterations to prevent runaway loops.
When to use Ralph Loop
Works well for tasks with clear, verifiable success criteria: getting tests to pass, completing a migration, building a feature from a spec. Not a good fit for tasks that need human judgment or have ambiguous goals.
Learn more
License
MIT