Self-referential iterative development loops for Gemini CLI - Based on the Ralph Wiggum technique by Geoffrey Huntley.
Ralph Loop is a development methodology where:
- You give an AI agent a task once
- The agent works on the task, creating/modifying files
- Your changes persist in the workspace
- The loop continues, with the AI seeing its previous work
- Loop continues until completion or max iterations
The prompt never changes, but the context does. Each iteration, the AI sees the files it created/modified, learns from its mistakes, and improves.
- ✅ 6 repositories generated overnight at Y Combinator hackathon
- ✅ $50k contract completed for $297 in API costs
- ✅ Entire programming language created over 3 months
| Feature | Description |
|---|---|
| 🔄 Self-referential loops | AI builds on its own work across iterations |
| 👁️ Real-time monitoring | Watch progress with /ralph:monitor |
| ⏸️ Pause/Resume | Take breaks without losing progress |
| 💾 Checkpoints | Save and restore loop state |
| ⏮️ Rollback | Undo iterations when things go wrong |
| 📊 Progress tracking | Iteration counts, timing, estimates |
| 🔍 Completion detection | String patterns and file signals |
| 🛡️ Safety limits | Max iterations prevent runaway loops |
| 📝 Full history | Track every iteration with logs |
| 🔧 Diagnostics | Analyze stuck loops |
| 📋 Reports | Generate summary documentation |
Gemini-Ralph-Loop/
├── src/
│ └── mcp-server.ts # MCP server implementation (2400+ lines)
├── commands/
│ └── ralph/ # 19 slash command definitions
│ ├── start-loop.toml # Start a new development loop
│ ├── status.toml # Check current loop status
│ ├── monitor.toml # Real-time progress monitoring
│ ├── pause.toml # Pause the running loop
│ ├── resume.toml # Resume a paused loop
│ ├── complete.toml # Mark loop as completed
│ ├── cancel.toml # Cancel the current loop
│ ├── checkpoint.toml # Create a checkpoint
│ ├── restore.toml # Restore from checkpoint
│ ├── rollback.toml # Rollback iterations
│ ├── history.toml # View iteration history
│ ├── diagnose.toml # Diagnose stuck loops
│ ├── report.toml # Generate reports
│ ├── config.toml # View/modify configuration
│ ├── adjust.toml # Adjust settings mid-run
│ ├── iterate.toml # Manual iteration control
│ ├── retry.toml # Retry failed iteration
│ ├── reset.toml # Clear all state
│ └── help.toml # Show help information
├── dist/ # Compiled JavaScript output
├── gemini-extension.json # Extension manifest
├── GEMINI.md # Context file for Gemini CLI
├── package.json # Node.js package configuration
├── tsconfig.json # TypeScript configuration
└── LICENSE # MIT License
# Install the extension
gemini extensions install https://github.com/kranthik123/Gemini-Ralph-Loop
# Enable auto-updates (recommended)
gemini extensions install https://github.com/kranthik123/Gemini-Ralph-Loop --auto-update# Clone the repository
git clone https://github.com/kranthik123/Gemini-Ralph-Loop.git
cd Gemini-Ralph-Loop
# Install dependencies
npm install
# Build the MCP server
npm run build
# Link for development (changes reflect immediately)
gemini extensions link .# List installed extensions
gemini extensions list
# Start Gemini CLI and check commands
gemini
/ralph:help# Start Gemini CLI
gemini
# Start a Ralph Loop
/ralph:start-loop "Build a REST API for todos with CRUD operations and tests" --max-iterations 25
# Monitor progress in real-time
/ralph:monitor
# Check status anytime
/ralph:status# 1. Start a loop with clear requirements
/ralph:start-loop "Create a Node.js CLI calculator.
Requirements:
- Support +, -, *, / operations
- Handle invalid input gracefully
- Include --help flag
- Write tests with Jest
When complete: <done>DONE</done>" -m 20 -c "DONE"
# 2. Monitor progress
/ralph:monitor
# 3. Create checkpoint before risky changes
/ralph:checkpoint "stable-v1"
# 4. If something goes wrong, rollback
/ralph:rollback
# 5. Or restore from checkpoint
/ralph:restore "stable-v1"
# 6. Check what happened
/ralph:history
# 7. Generate final report
/ralph:report| Command | Description | Example |
|---|---|---|
/ralph:start-loop |
Start a new loop | /ralph:start-loop "task" -m 30 |
/ralph:status |
Check current status | /ralph:status |
/ralph:monitor |
Real-time monitoring | /ralph:monitor |
/ralph:pause |
Pause the loop | /ralph:pause |
/ralph:resume |
Resume paused loop | /ralph:resume |
/ralph:complete |
Mark as completed | /ralph:complete -s "Built API" |
/ralph:cancel |
Cancel the loop | /ralph:cancel -r "Wrong approach" |
| Command | Description | Example |
|---|---|---|
/ralph:iterate |
Manual iteration control | /ralph:iterate |
/ralph:retry |
Retry current iteration | /ralph:retry |
| Command | Description | Example |
|---|---|---|
/ralph:history |
View iteration history | /ralph:history -n 20 |
/ralph:diagnose |
Analyze stuck loops | /ralph:diagnose |
/ralph:report |
Generate summary report | /ralph:report -f markdown |
| Command | Description | Example |
|---|---|---|
/ralph:reset |
Clear all state | /ralph:reset --confirm |
/ralph:checkpoint |
Create save point | /ralph:checkpoint "v1" |
/ralph:restore |
Restore checkpoint | /ralph:restore "v1" |
/ralph:rollback |
Undo iterations | /ralph:rollback -s 2 |
| Command | Description | Example |
|---|---|---|
/ralph:config |
View/modify settings | /ralph:config |
/ralph:adjust |
Modify mid-run | /ralph:adjust -m 50 |
/ralph:help |
Show help | /ralph:help checkpoint |
Configure after installation:
# Set default max iterations
gemini extensions settings set gemini-ralph-loop "Default Max Iterations"
# Set default completion promise
gemini extensions settings set gemini-ralph-loop "Default Completion Promise"
# Set iteration delay (helps with rate limiting)
gemini extensions settings set gemini-ralph-loop "Iteration Delay Seconds"
# Enable auto-commit (commits after each iteration)
gemini extensions settings set gemini-ralph-loop "Auto Commit"| Setting | Default | Description |
|---|---|---|
| Default Max Iterations | 100 | Maximum iterations before stopping |
| Default Completion Promise | COMPLETE | Text that signals completion |
| Iteration Delay Seconds | 2 | Delay between iterations |
| Auto Commit | false | Git commit after each iteration |
| Auto Checkpoint Interval | 10 | Auto-checkpoint every N iterations |
| Max Log Size KB | 100 | Maximum iteration log size |
| Variable | Description |
|---|---|
RALPH_WORKSPACE |
Working directory for the loop |
RALPH_AUTO_COMMIT |
Enable automatic git commits |
RALPH_AUTO_CHECKPOINT_INTERVAL |
Checkpoint interval (iterations) |
RALPH_MAX_LOG_SIZE_KB |
Maximum log file size |
/ralph:start-loop "Build a Node.js REST API for user management.
## Requirements
- Express.js framework with TypeScript
- CRUD endpoints: GET/POST/PUT/DELETE /api/users
- Input validation with express-validator
- JWT authentication middleware
- MongoDB with Mongoose ODM
- Jest tests with >80% coverage
- Error handling middleware
- API documentation in README.md
## Project Structure
src/
├── index.ts
├── routes/users.ts
├── middleware/auth.ts
├── models/User.ts
└── tests/users.test.ts
## Verification Steps
1. npm run build - compiles without errors
2. npm test - all tests pass
3. npm start - server starts on port 3000
4. All endpoints return correct status codes
## Completion
When ALL of the above requirements are implemented and verified:
<done>COMPLETE</done>" --max-iterations 30 --completion-promise "COMPLETE"
/ralph:start-loop "Make a good user API"
- Be specific - List exact requirements
- Include verification - How to check if it works
- Define structure - What files/folders to create
- Set completion criteria - When is "done" really done
- Use phases - Break complex tasks into steps
The /ralph:monitor command provides a real-time dashboard:
╔══════════════════════════════════════════════════════════════╗
║ 👁️ RALPH LOOP MONITOR ║
╠══════════════════════════════════════════════════════════════╣
║ Status: 🔄 RUNNING Loop: ralph-2024-01-15 ║
╠══════════════════════════════════════════════════════════════╣
║ Progress: [████████████░░░░░░░░░░░░░░░░░░] 40% ║
║ Iteration: 8 / 20 Remaining: 12 ║
║ Elapsed: 5m 23s Est. Left: 8m 12s ║
╠══════════════════════════════════════════════════════════════╣
║ Recent Activity: ║
║ • [14:32] Iter 8: Created src/routes/users.ts ║
║ • [14:30] Iter 7: Added validation middleware ║
║ • [14:28] Iter 6: Fixed test failures ║
╠══════════════════════════════════════════════════════════════╣
║ Controls: Ctrl+C to exit | /ralph:pause | /ralph:cancel ║
╚══════════════════════════════════════════════════════════════╝
Exit: Use Ctrl+C - the loop continues in background.
| Use Case | Why It Works |
|---|---|
| Greenfield projects | Build from scratch, iterate until complete |
| Test-driven development | Write test → implement → repeat |
| Code generation | Generate boilerplate, refine iteratively |
| Bug fixing | Iterate until all tests pass |
| Refactoring | Gradual improvements with test verification |
| Documentation | Generate and refine docs |
| API development | Build endpoints incrementally |
| Use Case | Why It Doesn't Work |
|---|---|
| Subjective tasks | "Make it look good" has no clear completion |
| One-shot operations | No benefit from iteration |
| Production debugging | Needs human judgment |
| Security-critical code | Requires human review |
| Unclear requirements | Loop can't clarify with you |
| Issue | Solution |
|---|---|
| Loop exits immediately | Check Gemini CLI auth, run /ralph:diagnose |
| Loop never completes | Verify completion promise matches, check /ralph:history |
| Same output repeating | Run /ralph:diagnose, improve prompt specificity |
| Rate limiting | Increase iteration delay in settings |
| State corrupted | Run /ralph:reset --confirm |
# Check what's happening
/ralph:status
/ralph:history --limit 20
# Diagnose issues
/ralph:diagnose
# View detailed logs (check .ralph-state/ directory)
ls .ralph-state/
# Reset if needed
/ralph:reset --confirmRalph Loop stores state in the .ralph-state/ directory:
.ralph-state/
├── state.json # Current loop state
├── history.json # Iteration history
├── monitor.json # Monitor state
├── checkpoints/ # Saved checkpoints
├── iterations/ # Iteration logs
├── logs/ # Detailed logs
└── reports/ # Generated reports
npm run build # Compile TypeScript to JavaScript
npm run watch # Watch mode for development
npm run clean # Remove dist directory
npm run rebuild # Clean and rebuild
npm run lint # Run ESLint
npm run typecheck # Type check without emitting
npm run test # Run tests- TypeScript - Type-safe development
- MCP SDK - Model Context Protocol integration
- Zod - Runtime type validation
- Node.js 18+ - Runtime environment
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Geoffrey Huntley - Original Ralph technique (ghuntley.com/ralph)
- Anthropic - Claude Code Ralph Wiggum plugin inspiration
- Google - Gemini CLI and extension system
- The Simpsons - Ralph Wiggum character
MIT License - see LICENSE file.
"Me fail English? That's unpossible!" - Ralph Wiggum
Made with ❤️ by kranthik123