AI-agnostic agentic loop CLI
Reset context. Persist learnings. Ship code.
Installation •
Quick Start •
Documentation •
Why Ralph?
What is ralph?
ralph runs AI coding agents in iterative loops. Instead of trying to one-shot prompts that hit context limits and get confused, ralph resets the context window between iterations while preserving the learning from each loop through your codebase.
ralph run -n 10 -p ./plans/PROMPT.md
The AI does work, commits changes, saves insights,exits, ralph checks if done, resets context, and loops—until your task is complete.
Full documentation can be found at https://wiggum.dev.
Why "Ralph Wiggum"?
The technique was coined by Geoffrey Huntley:
"Ralph is a Bash loop."
Named after Ralph Wiggum from The Simpsons—embodying the philosophy of persistent iteration despite setbacks. "Me fail English? That's unpossible!"
Installation
npm install -g @wiggumdev/ralph
You'll also need an AI CLI tool:
# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code
# Or OpenCode
npm i -g opencode-ai
Supported Adapters
| Adapter | Status |
|---|
| Claude Code | Complete |
| OpenCode | Complete |
| Gemini CLI | Under Development |
Quick Start
# Initialize in your project
cd your-project
ralph init
# Use your agent to generate a plan and write
zed .plans/prd.json
# Edit your prompt to your specific needs
zed .plans/PROMPT.md
# Run the loop
ralph run
Features
- Context Reset — Fresh context window each iteration
- State Persistence — Progress via git, files, and tests
- Completion Detection — AI signals when done with
<promise>COMPLETE</promise>
- Lifecycle Hooks — Run commands at key points in the loop
How It Works
flowchart TD
Start --> RunAI[Run AI];
RunAI --> Check;
Check --> Learn;
Learn --> Done{Done?};
Done -->|No| Reset;
Reset --> Start;
Done -->|Yes| Exit;
Note[State persists via:<br/>git, files, tests]
Each iteration:
- AI starts with fresh context
- Reads codebase to understand state
- Does work (writes code, runs tests)
- ralph checks for completion marker
- If not done, reset and loop
Configuration
ralph uses TOML config at .ralph/config.toml:
adapter = "claude"
maxIterations = 20
plansDir = ".plans"
verbose = false
tui = true
[hooks]
ralph_start = ""
ralph_loop_end = "npm run lint:fix"
ralph_complete = "say 'Ralph is done!'"
Project Structure
After ralph init:
project/
├── .ralph/
│ └── config.toml # Configuration
└── .plans/
├── prd.json # Feature requirements
├── PROMPT.md # Your ralph loop prompt
└── progress.txt # Learning log
Commands
ralph init # Initialize ralph in a project
ralph run # Start the agentic loop
ralph check # Validate prd.json schema
Run Options
ralph run --max-iterations 10 # Limit iterations
ralph run --once # Single iteration (no loop)
ralph run --prompt TASK.md # Use specific prompt file
ralph run --no-tui # Plain text output (for CI)
ralph run --verbose # Debug output
Loop Prompt Example
Your prompt in .plans/PROMPT.md should include:
@.plans/prd.json @.plans/progress.txt
1. Find the highest-priority feature to work on and work ONLY on that feature. This should be the one YOU decide has the highest priority - not necessarily the first in the list
2. Before making changes, search codebase (don't assume not implemented).
3. Implement the requirements for the selected feature using TDD.
3. Run typecheck and tests: `bun run typecheck && bun run test`
4. Update prd.json marking completed work (CAREFULLY!)
**YOU CAN ONLY MODIFY ONE FIELD: "passes"**
After thorough verification, change:
\`\`\`json
"passes": false
\`\`\`
to:
\`\`\`json
"passes": true
\`\`\`
5. Append learning to .plans/progress.txt for future iterations.
6. Commit changes: `jj commit -m "description"`
ONLY WORK ON A SINGLE FEATURE PER ITERATION.
If all features complete, output <promise>COMPLETE</promise>
When you learn something new about how to run commands or patterns in the code make sure you update @CLAUDE.md using a subagent but keep it brief.
Remember: You have unlimited time across many sessions. Focus on quality over speed. Production-ready is the goal.
Documentation
Full documentation at wiggum.dev
Based On
