Ralph Wiggum Loop
Worker and reviewer models take turns on a coding task until the reviewer says SHIP
- Pricing
- Open source
- Platforms
- CLI, Linux, macOS
- Runs
- Locally
- Version
- 1.1.0
- Listing updated
- 2 days ago
About Ralph Wiggum Loop
Ralph Wiggum Loop is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
The Ralph Loop splits an implementation task between two roles. A worker model does the job with a fresh context and submits a summary, then an independent reviewer model from a different model checks it and returns SHIP to finish or REVISE to start another round. In in-session mode the loop finishes on a DONE promise instead.
It is a plugin written as shell and PowerShell scripts, with a polyglot runner that dispatches to bash on Linux and macOS and to PowerShell on Windows. It can run as a CLI, as a stdio MCP server, or as a streamable HTTP service on a local port. Stop hooks block a session from ending early until the loop reaches its exit condition.
Five quality profiles (lite, plus, pro, super, ultra) switch adaptively, with backoff when rate limits hit. State and iteration history live in a directory set by RALPH_STATE_BASE, and workflow recipes are JSON files in RALPH_RECIPE_DIR. The project is MIT licensed.
Install
Run in a terminal
claude mcp add ralph-wiggum-loop -- npx -y https://github.com/sheldonrobinson/ralph-wiggum-loop/releases/download/v1.1.0/ralph-wiggum-loop.sh.mcpbAdd to claude_desktop_config.json
{
"mcpServers": {
"ralph-wiggum-loop": {
"command": "npx",
"args": [
"-y",
"https://github.com/sheldonrobinson/ralph-wiggum-loop/releases/download/v1.1.0/ralph-wiggum-loop.sh.mcpb"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"ralph-wiggum-loop": {
"command": "npx",
"args": [
"-y",
"https://github.com/sheldonrobinson/ralph-wiggum-loop/releases/download/v1.1.0/ralph-wiggum-loop.sh.mcpb"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"ralph-wiggum-loop": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"https://github.com/sheldonrobinson/ralph-wiggum-loop/releases/download/v1.1.0/ralph-wiggum-loop.sh.mcpb"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"ralph-wiggum-loop": {
"command": "npx",
"args": [
"-y",
"https://github.com/sheldonrobinson/ralph-wiggum-loop/releases/download/v1.1.0/ralph-wiggum-loop.sh.mcpb"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"ralph-wiggum-loop": {
"command": "npx",
"args": [
"-y",
"https://github.com/sheldonrobinson/ralph-wiggum-loop/releases/download/v1.1.0/ralph-wiggum-loop.sh.mcpb"
]
}
}
}Configuration
RALPH_STATE_BASEDirectory path where active Ralph Loop state and iteration history are storedRALPH_RECIPE_DIRDirectory path containing workflow recipe JSON filesRALPH_STATE_BASEDirectory path where active Ralph Loop state and iteration history are storedRALPH_RECIPE_DIRDirectory path containing workflow recipe JSON files
Tools this server provides (11)
Taken from the project documentation; the running server may differ.
- ralph_loop_initialize
- Start a loop.
- ralph_loop_get_task
- Fetch the current task.
- ralph_loop_submit_work
- Worker submits work.
- ralph_loop_get_work
- Reviewer reads submitted work.
- ralph_loop_submit_review
- Reviewer submits a SHIP or REVISE verdict.
- ralph_loop_get_feedback
- Fetch reviewer feedback.
- ralph_loop_get_status
- Check loop status.
- ralph_loop_get_config
- Read loop configuration.
- ralph_loop_reset
- Reset the loop.
- ralph_loop_block
- Block the loop.
- ralph_loop_run
- Run the loop.
What it does
- Worker and reviewer split
- One model implements, a different model reviews, which gives cross-model checking.
- SHIP or REVISE decisions
- The reviewer's verdict either completes the task or triggers another iteration.
- Stop hooks
- Scripts stop a session from exiting before the loop is done.
- Five quality profiles
- lite, plus, pro, super and ultra, with adaptive switching and rate-limit backoff.
- Cross-platform runner
- One polyglot script runs on Linux, macOS and Windows PowerShell.
- Three run modes
- CLI, stdio MCP server, or streamable HTTP service.
Good for
- Implement a feature from a spec with automatic review rounds
- Add a second-opinion review step to an agent coding session
- Prevent an agent from stopping before work is verified
- Run an iterative loop as a local HTTP service for other clients
Pricing
Open source
MIT licensed
Prices change. Check sheldonrobinson.github.io before you buy.
Ralph Wiggum Loop FAQ
What does the loop do each round?
The worker submits work and a summary, the reviewer returns SHIP or REVISE, and REVISE starts the next iteration.
Which platforms does it run on?
Linux and macOS through bash, and Windows through PowerShell 5.1 or 7+.
How many tools does it expose?
The site says 11 MCP tools, including initialize, submit_work, submit_review, get_status and run.
What licence is it under?
MIT.
Is Ralph Wiggum Loop free?
Yes. Ralph Wiggum Loop is open source, so you can use and self-host it for free.
How do I add Ralph Wiggum Loop to Claude Code?
Run this command in your terminal: claude mcp add ralph-wiggum-loop -- npx -y https://github.com/sheldonrobinson/ralph-wiggum-loop/releases/download/v1.1.0/ralph-wiggum-loop.sh.mcpb
What are the best alternatives to Ralph Wiggum Loop?
The closest alternatives to Ralph Wiggum Loop are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to Ralph Wiggum Loop

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools