Ralph Wiggum Plugin for OpenCode

Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in OpenCode.

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 loop 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 OpenCode plugin implements Ralph using manual continuation to prevent freezing:

# Start a loop:
/ralph-loop "Your task description" 20 "DONE"

# Work on the task...

# Continue to next iteration:
/ralph-continue

# Repeat until completion or cancel:
/cancel-ralph

This creates a self-referential feedback loop where:

• The prompt never changes between iterations
• Your previous work persists in files
• Each iteration sees modified files and git history
• The AI autonomously improves by reading its own past work

Installation

Option 1: Quick Setup with NPX (Recommended)

The fastest way to get started:

# Navigate to your project directory
cd /path/to/your/project

# Initialize Ralph Wiggum with one command
npx opencode-ralph-wiggum init

This will:

• ✅ Create/update .opencode/config.json with Ralph plugin
• ✅ Add sample workflow examples
• ✅ Set up your project for iterative AI development
• ✅ Show you exactly what to do next

Option 2: Manual Configuration

Add the plugin to your OpenCode config manually:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-ralph-wiggum"]
}

Then restart OpenCode to install the plugin automatically.

Option 3: Local Development

git clone https://github.com/opencode-community/opencode-ralph-wiggum.git
cd opencode-ralph-wiggum
bun install

Then point your config to the local checkout:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/to/opencode-ralph-wiggum"]
}

Quick Start

After installation, start OpenCode and try Ralph:

# Start OpenCode in your project
opencode

# Try a simple Ralph loop
/ralph-loop "Add unit tests to this project" 10

# Work on your task normally...

# Continue to next iteration when ready  
/ralph-continue

# Or cancel if needed
/cancel-ralph

Advanced examples:

# Basic usage with safety limits
/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." 50 "COMPLETE"

# Simple task with iteration limit only
/ralph-loop "Fix the authentication bug" 10

# Test-driven development
/ralph-loop "Implement user registration following TDD: write tests, implement, verify all pass" 25 "ALL TESTS PASSING"

Commands

/ralph-loop

Start a Ralph loop in your current session.

Syntax:

/ralph-loop "<prompt>" [max-iterations] [completion-promise]

Arguments:

• prompt (required) - The task description to iterate on
• max-iterations (optional) - Stop after N iterations (default: 50, 0 for unlimited)
• completion-promise (optional) - Phrase that signals completion when found in <promise> tags

/ralph-continue

Manually continue the Ralph loop to the next iteration.

Syntax:

/ralph-continue

Note: Automatic session.idle handling has been disabled to prevent OpenCode freezing. Use this command when ready to proceed to the next iteration.

/cancel-ralph

Cancel the active Ralph loop.

Syntax:

/cancel-ralph

Usage Workflow

Getting Started

1. Initialize: npx opencode-ralph-wiggum init (first time setup)
2. Start OpenCode: opencode
3. Start Loop: /ralph-loop "task description" 10
4. Work on Task: Complete your work normally
5. Continue: /ralph-continue to proceed to next iteration
6. Review: See your previous work and continue improving
7. Complete: Output <promise>TASK COMPLETED</promise> or /cancel-ralph

Safety Features

Default Limits

• Max iterations: 50 (prevents infinite loops)
• State validation: Robust error recovery for corrupted state
• Manual control: No automatic session.idle to prevent freezing
• Auto-cleanup: State cleanup on cancellation

Monitoring

# Check current state
cat .opencode/ralph-state.json

# View current iteration
grep '"iteration"' .opencode/ralph-state.json

# Check sample workflows (created by npx init)
cat .opencode/samples/ralph-examples.md

# Manual cleanup (if needed)
rm .opencode/ralph-state.json

Prompt Writing Best Practices

1. Clear Completion Criteria

❌ Bad:

/ralph-loop "Build a todo API and make it good."

✅ Good:

/ralph-loop "Build a REST API for todos.

When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- README with API docs
- Output: <promise>COMPLETE</promise>" 40 "COMPLETE"

2. Incremental Goals

✅ Good:

/ralph-loop "Phase 1: User authentication (JWT, tests)
Phase 2: Product catalog (list/search, tests)
Phase 3: Shopping cart (add/remove, tests)

Output <promise>ALL PHASES COMPLETE</promise> when all phases done." 60 "ALL PHASES COMPLETE"

3. Self-Correction

✅ Good:

/ralph-loop "Implement feature X following TDD:
1. Write failing tests
2. Implement feature
3. Run tests
4. If any fail, debug and fix
5. Refactor if needed
6. Repeat until all green
7. Output: <promise>TESTS PASSING</promise>" 25 "TESTS PASSING"

When to Use Ralph

Good for:

• Well-defined tasks with clear success criteria
• Tasks requiring iteration and refinement (e.g., getting tests to pass)
• Greenfield projects where you can walk away
• Tasks with automatic verification (tests, linters)
• Learning and experimentation

Not good for:

• Tasks requiring human judgment or design decisions
• One-shot operations
• Tasks with unclear success criteria
• Production debugging (use targeted debugging instead)

Technical Details

Architecture

• TypeScript: Full type safety and modern ES modules
• Manual control: Prevents OpenCode freezing with manual continuation
• State management: JSON-based persistence with validation
• Error recovery: Graceful handling of corrupted state
• Zero dependencies: Uses only OpenCode plugin API and Node.js built-ins

State Management

The plugin stores state in .opencode/ralph-state.json:

{
  "active": true,
  "iteration": 5,
  "maxIterations": 50,
  "completionPromise": "DONE",
  "startedAt": "2025-01-01T12:00:00Z",
  "originalPrompt": "Build a REST API",
  "sessionId": "session-123"
}

Troubleshooting

Plugin Not Loading

# Initialize plugin in your project
npx opencode-ralph-wiggum init

# Check OpenCode config
cat .opencode/config.json

# Verify plugin installation
ls ~/.cache/opencode/node_modules/opencode-ralph-wiggum

Loop Won't Start

# Check for existing loop
cat .opencode/ralph-state.json

# Cancel if needed
/cancel-ralph

# Try again
/ralph-loop "Your prompt" 20

Loop Won't Continue

# Use manual continuation
/ralph-continue

# If that fails, check state
cat .opencode/ralph-state.json

# Cancel and restart if needed
/cancel-ralph

Contributing

We welcome contributions! Here's how to get started:

Development Setup

git clone https://github.com/opencode-community/opencode-ralph-wiggum.git
cd opencode-ralph-wiggum
bun install
bun run type-check
bun test

Making Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes with tests
4. Run the full test suite: npm test && npm run type-check
5. Test the npx script: node bin/init.js --help
6. Submit a pull request

Release Process

This project uses automated CI/CD for releases:

• CI/CD Pipeline: Tests on Node 18, 20, 22 with full test coverage
• Automated Publishing: NPM publishing on GitHub releases
• Security Scanning: Weekly dependency audits
• Quality Gates: TypeScript, tests, and NPX functionality validation

See CONTRIBUTING.md for detailed development and release workflows.

Real-World Results

From the original Ralph technique:

• Successfully generated 6 repositories overnight in Y Combinator hackathon testing
• One $50k contract completed for $297 in API costs
• Created entire programming language ("cursed") over 3 months using this approach

Learn More

• Original technique: https://ghuntley.com/ralph/
• Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
• OpenCode Documentation: https://opencode.ai/docs/plugins/

Credits

• Original concept: Geoffrey Huntley (https://ghuntley.com/ralph/)
• Claude plugin: Daisy Hollman [email protected]
• OpenCode port: OpenCode Community

License

MIT License - see LICENSE for details.