Skip to content
MCP server

Ralph Wiggum Loop

Worker and reviewer models take turns on a coding task until the reviewer says SHIP

Runs locallyStatus and history
Install
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.mcpb

Add 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"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

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"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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 stored
  • RALPH_RECIPE_DIRDirectory path containing workflow recipe JSON files
  • RALPH_STATE_BASEDirectory path where active Ralph Loop state and iteration history are stored
  • RALPH_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

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools