ralph-local

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

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)

🔄 Synced from Upstream (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"