# Ralph Wiggum Loop

> Ralph Wiggum Loop is an open-source MCP server for developer tools. Worker and reviewer models take turns on a coding task until the reviewer says SHIP. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Linux, macOS, Windows, self-hosted, API
- **Website:** https://sheldonrobinson.github.io/ralph-wiggum-loop
- **Repository:** https://github.com/sheldonrobinson/ralph-wiggum-loop
- **MCP Registry name:** io.github.sheldonrobinson/ralph-wiggum-loop
- **Categories:** developer tools
- **Listing updated:** 2026-11-15

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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"
      ]
    }
  }
}
```

## Tools

- `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.

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/ralph-wiggum-loop
