Ralph Local
Forked from: claude-plugins-official/ralph-wiggum (Anthropic)
Enhancements: Parse error fixes, absolute path support for worktree isolation, Oracle Forum integration
📢 Upstream PR: #15853 - Session isolation fix contributed back to official plugin
Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Claude Code.
📦 Installation
Step 1: Add the marketplace
/plugin marketplace add Soul-Brews-Studio/ralph-local
Step 2: Install the plugin
/plugin install ralph-local@ralph-local
Or: Clone locally
# Clone into your project
git clone https://github.com/Soul-Brews-Studio/ralph-local.git plugins/ralph-local
# Add as local marketplace
/plugin marketplace add ./plugins/ralph-local
/plugin install ralph-local@ralph-local
🤖 AI Assistant Installation Prompt
Install the ralph-local plugin for iterative AI development loops.
Steps:
1. Add marketplace: /plugin marketplace add Soul-Brews-Studio/ralph-local
2. Install plugin: /plugin install ralph-local@ralph-local
3. Verify: /ralph-loop --help
4. Confirm to user:
- ✅ Ralph Local plugin installed
- ✅ Commands: /ralph-loop, /cancel-ralph, /check-updates
- ✅ Ready to use
Usage example:
/ralph-loop "Build a REST API with tests" --max-iterations 30 --completion-promise "COMPLETE"
🚀 Quick Start
# Start a Ralph loop
/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50
Claude will:
- Implement the API iteratively
- Run tests and see failures
- Fix bugs based on test output
- Iterate until all requirements met
- Output the completion promise when done
Why This Fork?
This is a local fork of the official ralph-wiggum plugin with significant engineering improvements.
🔧 What We Engineered (laris-co)
| Feature | Description | Files Changed |
|---|
| Extensive Error Handling | Validates numeric fields, handles corrupt state files gracefully, detailed error messages | hooks/stop-hook.sh |
| Worktree Isolation | Uses CLAUDE_PROJECT_DIR for multi-agent worktree support (MAW) | hooks/stop-hook.sh |
| Oracle Forum Integration | EXIT_LOOP signal support for multi-agent coordination | Pattern documentation |
| Write Tool Usage | Uses Write tool instead of bash to preserve special characters | commands/ralph-loop.md |
| Parse Error Fixes | Fixed backtick pattern that broke eval in cancel command | commands/cancel-ralph.md |
/check-updates Command | Track upstream changes and PR status | commands/check-updates.md |
| AI Installation Prompt | Ready-to-use prompt for AI assistants to install | README.md |
| Comprehensive Documentation | 500+ lines of docs with history, examples, troubleshooting | README.md |
🔄 Synced from Upstream (PR #15853)
| Feature | Description | Source |
|---|
| Session Isolation | Each session has own state file (state/${SESSION_ID}.md) | PR #15853 |
| SessionStart Hook | Captures session_id and persists as CLAUDE_SESSION_ID | PR #15853 |
| Plugin-relative State | State files in ${PLUGIN_ROOT}/state/ instead of .claude/ | PR #15853 |
📊 Engineering Stats
Total commits: 10
Lines added: 567+
Files modified: 8
New commands: 1 (/check-updates)
New hooks: 1 (SessionStart)
🎉 Contributing Back: We merged upstream session isolation from PR #15853 while keeping our extensive error handling and multi-agent features.
Credit: Original concept by Geoffrey Huntley. Base implementation by Anthropic's Claude Code team. Enhanced by laris-co.
What is Ralph?
Ralph is a development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: "Ralph is a Bash loop" - a simple while true that repeatedly feeds an AI agent a prompt file, allowing it to iteratively improve its work until completion.
The technique is named after Ralph Wiggum from The Simpsons, embodying the philosophy of persistent iteration despite setbacks.
Core Concept
This plugin implements Ralph using a Stop hook that intercepts Claude's exit attempts:
# You run ONCE:
/ralph-loop "Your task description" --completion-promise "DONE"
