| name | ralph-cursor |
| description | Implements the Ralph Wiggum autonomous iteration technique with deliberate context management. Use when building greenfield projects, iterating on well-defined tasks, or when continuous autonomous development is needed. Manages context like memory - tracks allocations, prevents redlining, and knows when to start fresh. |
| license | MIT |
| compatibility | Designed for Cursor (nightly). Requires Node.js 18+, cursor-agent CLI, git. |
| metadata | {"author":"Based on Geoffrey Huntley's Ralph technique","version":"1.0.0","original":"https://ghuntley.com/ralph/"} |
Ralph Wiggum: Autonomous Iteration with Context Engineering
Ralph is a technique for autonomous AI development. In its purest form, Ralph is a loop that repeatedly feeds the same prompt to an AI agent, letting it iterate on a task until completion. The key insight is that context is like memory - when you malloc() data into the context window, it cannot be free()'d except by starting fresh.
Core Philosophy
"That's the beauty of Ralph - the technique is deterministically bad in an undeterministic world."
Ralph will make mistakes. That's expected. Each mistake is an opportunity to add a "sign" (guardrail) that prevents that mistake in the future. Like tuning a guitar, you adjust Ralph until it plays the right notes.
The malloc/free Metaphor
- Context is memory: Everything loaded into the LLM's context window stays there
- You cannot free() context: The only way to clear context is to start a new conversation
- One task per context: Mixed concerns lead to autoregressive failure
- Don't redline: Pushing context to limits degrades performance
- Gutter detection: Once the bowling ball is in the gutter, start fresh
How This Skill Works
State Files (The Persistent Memory)
Ralph tracks state in files, NOT in context:
.ralph/
├── state.md # Current iteration, task, completion criteria
├── guardrails.md # Accumulated "signs" from observed failures
├── context-log.md # What's been loaded into context
├── failures.md # Failure patterns for learning
└── progress.md # What's been accomplished
The Iteration Cycle
- Read state files to understand current task and progress
- Check guardrails for relevant "signs" to follow
- Work on the task - implement, test, refine
- Update progress in files (not just context)
- Commit checkpoint via git
- Evaluate completion against criteria
- If not complete: Signal for next iteration
- If stuck: Detect gutter, suggest fresh context
Guardrails ("Signs")
When Ralph makes a mistake, add a sign:
## Sign: Don't Jump Off The Slide
- **Trigger**: When implementing authentication
- **Instruction**: Always validate tokens before trusting claims
- **Added after**: Iteration 5 - security vulnerability introduced
Signs accumulate in guardrails.md and are injected into future iterations.
Usage
Starting a Ralph Loop
Create a RALPH_TASK.md file in your project root:
---
task: Build a REST API for task management
completion_criteria:
- All CRUD endpoints working
- Input validation implemented
- Tests passing with >80% coverage
- API documentation complete
max_iterations: 50
---
## Requirements
Build a task management API with the following endpoints:
- POST /tasks - Create a task
- GET /tasks - List all tasks
- GET /tasks/:id - Get a task
- PUT /tasks/:id - Update a task
- DELETE /tasks/:id - Delete a task
## Constraints
- Use TypeScript
- Use Express.js
- Use SQLite for storage
- Follow REST conventions
Then tell Cursor: "Start a Ralph loop on this task"
Monitoring Progress
Check .ralph/progress.md to see what's been accomplished:
## Iteration 1
- Created project structure
- Implemented POST /tasks endpoint
- Status: Partial progress
## Iteration 2
- Added GET endpoints
- Fixed validation bug
- Status: Continuing
When to Start Fresh
Ralph will detect "gutter" situations:
- Same error repeated 3+ times
- Context approaching limits
- Circular failure patterns
When detected, Ralph will suggest: "Context is polluted. Recommend starting fresh conversation."
Best Practices
1. Clear Completion Criteria
❌ Bad: "Make a good API"
✅ Good: "All tests passing, coverage >80%, docs complete"
2. Incremental Goals
❌ Bad: "Build complete e-commerce platform"
✅ Good: Phase 1: Auth, Phase 2: Products, Phase 3: Cart
3. Let Failures Teach
Don't intervene too quickly. Let Ralph fail, then add signs.
4. Trust the Files
Progress is in files and git, not in your head or the context.
5. Fresh Context is Cheap
Don't hesitate to start fresh. State persists in files.
Integration with Cursor Hooks
This skill uses Cursor hooks for:
- beforeSubmitPrompt: Inject guardrails and context awareness
- beforeReadFile: Track context allocations
- afterFileEdit: Update progress tracking
- stop: Evaluate completion, trigger next iteration or fresh start
Use the Node CLI (npx ralph-cursor or ralph-cursor) for init, run, loop, once, task, doctor, status, and logs.
Learn More
