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