# Ralph Cursor Guide **URL:** \ **Category:** Guides\ **Tags:** cli, terminal, context, plan-mode\ **Created:** [January 26, 2026, 9:02pm UTC](https://forum.cursor.com/t/ralph-cursor-guide/149998 "2026-01-26T21:02:16Z")\ **Posts on this page:** 2\ **Page:** 1
**Author:** ![cursor.pxjrc](https://avatars.discourse-cdn.com/v4/letter/c/b5ac83/32.png) [@cursor.pxjrc](https://forum.cursor.com/u/cursor.pxjrc)\ **Post date:** [January 26, 2026, 9:02pm UTC](https://forum.cursor.com/t/ralph-cursor-guide/149998/1 "2026-01-26T21:02:17Z")
# The Ralph Wiggum Technique: Running Autonomous Cursor Agents for Hours > “It’s better to fail predictably than succeed unpredictably.” — Geoffrey Huntley ## What is Ralph? Ralph (named after Ralph Wiggum from The Simpsons - persistently wrong but never giving up) is an autonomous AI coding pattern that solves two fundamental problems: 1. **LLMs grade their own homework poorly** - They say “done” when they’re not 2. **Context windows fill up and degrade** - Long conversations get expensive and confused ### The Core Innovation: Fresh Context, Persistent Code Traditional AI coding accumulates context. By turn 50, you’re paying for 200K+ tokens of conversation history, and the model is getting confused by all that context. Ralph keeps context fresh but code persists: - Iteration 1: 5K tokens → code saved to disk - Iteration 2: 5K tokens (fresh!) → sees previous code via files - Iteration 50: 5K tokens (still fresh!) → all progress in codebase **Even using the same expensive model, Ralph is dramatically cheaper because each iteration starts fresh.** * * * ## Why This Saves Money The savings come from: - **No context accumulation** - Each iteration is ~5K tokens, not 200K - **No “remembering” failures** - Dead ends are forgotten, not paid for - **Code is the memory** - Progress persists in git, not in tokens You can also use cheaper models for the execution phase for additional savings, but fresh context is the main win. * * * ## The Two-Phase Approach ### Phase 1: Smart Planning (Plan Mode) Use **Plan Mode** with your smartest model to break down work into atomic tasks. The goal is to create tasks so mechanical that a cheaper model can execute them without judgment. **Example prompt to start planning:** ```auto /mode plan I need to migrate all files using OldHook to use NewHook instead. Please: 1. Analyze the codebase to find all affected files 2. Define the EXACT transformation pattern (show before/after code) 3. Create a grep command that returns 0 when migration is complete 4. Write a prompt template for migrating one file at a time 5. Create a bash script that loops until done, spawning fresh Cursor CLI agents ``` **What you get from Plan Mode:** - A discovery command to find all files - Exact code patterns (before → after) - A verification command (e.g., `grep -r "OLD_PATTERN" src/ | wc -l`) - A prompt template for each iteration - A bash script that orchestrates the loop ### Phase 2: Cheap Execution (CLI Loop) The key insight: **you ask Cursor to write a script that calls the Cursor CLI in a loop**. **Example prompt after planning:** ```auto Now create a bash script called ralph_migrate.sh that: 1. Checks how many files still need migration using grep 2. If zero remain AND type checking passes, exit successfully 3. Otherwise, spawn a fresh agent using the Cursor CLI with the prompt we created 4. Run type checking after each iteration 5. Loop until done (with a max iteration safety limit) 6. Use --model grok for cost savings ``` Cursor will generate something like this: ```bash #!/bin/bash # Load API key source .env export PATH="$HOME/.local/bin:$PATH" MAX_ITERATIONS=50 ITERATION=0 # The prompt for each fresh agent PROMPT='Migrate ONE file from OldHook to NewHook. Find a file: grep -r "import OldHook from" src/ -l | head -1 Transformation: - OLD: import OldHook from "old-path" - NEW: import { newHook } from "new-path" Instructions: 1. Find ONE file still using OldHook 2. Read it to understand context 3. Apply the transformation 4. Stop after ONE file' while [$ITERATION -lt $MAX_ITERATIONS]; do REMAINING=$(grep -r "import OldHook from" src/ 2>/dev/null | wc -l) if ["$REMAINING" -eq 0]; then echo "Zero imports remaining, checking types..." if npx tsc --noEmit; then echo "SUCCESS: Migration complete!" exit 0 fi fi echo "=== Iteration $ITERATION: $REMAINING files remaining ===" # Spawn fresh agent with minimal context agent -p --model grok "$PROMPT" ITERATION=$((ITERATION + 1)) done echo "Reached max iterations" ``` Then just run it: ```bash chmod +x ralph_migrate.sh ./ralph_migrate.sh ``` * * * ## The Key Insight: External Verification **This is what makes Ralph work.** The loop doesn’t stop when the LLM says “done” - it stops when external tools confirm success. ```bash # BAD: Trust the LLM if agent_says_done; then exit; fi # GOOD: Trust external verification REMAINING=$(grep -r "OLD_PATTERN" src/ | wc -l) if [$REMAINING -eq 0] && npx tsc --noEmit; then exit 0 # Only grep + compiler decide when done fi ``` Good verification commands: - `grep -r "pattern" | wc -l` → Zero matches remaining - `npx tsc --noEmit` → TypeScript compiles - `npm test` → Tests pass - `npm run build` → Build succeeds * * * ## Plan Mode: Creating Atomic Tasks The planning phase should produce tasks that are **mechanical and verifiable** : **Bad task (requires judgment):** > “Refactor the authentication system” **Good task (mechanical):** > “Replace `import OldAuth from 'old-auth'` with `import { newAuth } from 'new-auth'`” > Verification: `grep -r "import OldAuth" src/ | wc -l == 0` **Prompt for Plan Mode:** ```auto Break this work into atomic tasks where each task: - Has an exact before/after code pattern - Has a grep command to verify completion - Requires zero judgment to execute - Can be done one file at a time ``` * * * ## Setup (All Via Cursor) ### Step 1: Install CLI Ask Cursor: ```auto Run the Cursor CLI installer: curl -fsSL https://www.cursor.com/install.sh | sh ``` ### Step 2: Authenticate Ask Cursor: ```auto Run: agent login ``` Or add `CURSOR_API_KEY` to your `.env` file. ### Step 3: Create Your Plan Switch to Plan Mode and describe your task. Let Cursor analyze the codebase and create the transformation patterns, verification commands, and loop script. ### Step 4: Run the Loop Ask Cursor to create the ralph script from your plan, then run it in the background. * * * ## When to Use Ralph **Good for:** - Large refactors with clear patterns (50+ files) - Library/framework migrations - Adding types across codebase - Renaming symbols project-wide - Any task with objective pass/fail criteria **Not for:** - Creative/design decisions - Architectural choices - Security-sensitive code - Tasks without clear “done” criteria * * * ## Common Mistakes **Letting LLM decide when done** → Use external verification (grep, tsc, tests) **One long conversation** → Use fresh context per iteration (Ralph loop) **Vague task descriptions** → Plan phase creates explicit before/after patterns **Writing scripts manually** → Ask Cursor to write scripts that use the Cursor CLI **Forgetting type checks** → Run tsc after each iteration * * * ## The Philosophy > "Ralph keeps what matters (code changes in git) and forgets what doesn’t (conversation context, failed attempts). > > Each iteration starts fresh but builds on persistent progress." The context window becomes a _working memory_, not a _permanent record_. Code is the memory. * * * ## Resources - [Geoffrey Huntley’s Original Ralph Post](https://ghuntley.com/ralph/) - [Cursor CLI Documentation](https://docs.cursor.com/agent/cli) - [Ralph Loop with Google ADK](https://medium.com/google-cloud/ralph-loop-with-google-adk-ai-agents-that-verify-not-guess-b41f71c0f30f) * * * _Questions or success stories? Share in the comments!_ ---
**Author:** ![luchillo17](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/luchillo17/32/80742_2.png) [@luchillo17](https://forum.cursor.com/u/luchillo17)\ **Post date:** [July 8, 2026, 4:50pm UTC](https://forum.cursor.com/t/ralph-cursor-guide/149998/3 "2026-07-08T16:50:37Z")
Is this still useful? with how competent latest models are I simply list all the work and tell an agent to orchestrate said work, it will then create subagents, and I would usually let it run while I go lunch or overnight.