Ralph Wiggum Plugin for OpenCode

!Version
!License
!TypeScript
!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.

$3

This OpenCode plugin implements Ralph using manual continuation to prevent freezing:

``bash


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

$3

The fastest way to get started:

`bash


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

$3

Add the plugin to your OpenCode config manually:

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

Then restart OpenCode to install the plugin automatically.

$3

`bash
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:

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

Quick Start

After installation, start OpenCode and try Ralph:

`bash


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:

`bash


Basic usage with safety limits

/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output COMPLETE 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

$3

Start a Ralph loop in your current session.

Syntax:
`bash
/ralph-loop "" [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 tags

$3

Manually continue the Ralph loop to the next iteration.

Syntax:
`bash
/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.

$3

Cancel the active Ralph loop.

Syntax:
`bash
/cancel-ralph
`

Usage Workflow

$3


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

Safety Features

$3

- 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

$3

`bash


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

$3

❌ Bad:
`bash
/ralph-loop "Build a todo API and make it good."
`

✅ Good:
`bash
/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: COMPLETE" 40 "COMPLETE"
`

$3

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

Output ALL PHASES COMPLETE when all phases done." 60 "ALL PHASES COMPLETE"
`

$3

✅ Good:
`bash
/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: TESTS PASSING" 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

$3

- 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

$3

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

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

Troubleshooting

$3

`bash


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
`

$3

`bash


Check for existing loop

cat .opencode/ralph-state.json

Cancel if needed

/cancel-ralph

Try again

/ralph-loop "Your prompt" 20
`

$3

`bash


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:

$3

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

$3

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

$3

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
- OpenCode port: OpenCode Community

License

MIT License - see LICENSE for details.