ralph-loop-mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ralph-loop-mcpstart a Ralph Loop session to implement JWT auth"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ralph Loop MCP Server
A cross-platform MCP (Model Context Protocol) server implementing the Ralph Loop — a multi-model iterative development technique where a "worker" model does the work and a "reviewer" model provides cross-model review, iterating until the reviewer says "SHIP".
Based on:
Ralph Wiggum as a "software engineer" by Geoffrey Huntley
Overview
The Ralph Loop implements a two-phase iterative workflow:
┌─────────────────────────────────────────────────────────────┐
│ RALPH LOOP │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ WORK PHASE ┌─────────┐ │
│ │ TASK │ ──────────────────▶ │ WORKER │ │
│ │ │ fresh context │ (Model A)│ │
│ └─────────┘ └────┬────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Submit Work + │ │
│ │ Summary │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ REVIEW PHASE ┌─────────┐ │
│ │ REVIEWER│ ◀─────────────────── │ WORK │ │
│ │(Model B)│ cross-model review │ OUTPUT │ │
│ └────┬────┘ └─────────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ │
│ │ DECISION│ │
│ │ SHIP │──────▶ COMPLETE ✓ │
│ │ REVISE │──────▶ Next Iteration (fresh context) │
│ └─────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘Related MCP server: ralph-wiggum-mcp
Features
Cross-platform: Works on Windows (PowerShell/cmd), Linux, and macOS (bash)
MCP Compliant: Uses official
@modelcontextprotocol/sdkwith JSON-RPC 2.0Session-based: Multiple concurrent Ralph Loop sessions supported
File-based State: Persistent state stored in
~/.goose/ralph/{sessionId}/9 Tools: Complete workflow control via MCP tools
Installation
# Clone and install
git clone <repository-url>
cd ralph-loop-mcp
npm install
npm run buildUsage with MCP Clients
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"ralph-loop": {
"command": "node",
"args": ["path/to/ralph-loop-mcp/dist/index.js"]
}
}
}Goose
goose session --mcp ralph-loop --command "node" --args "path/to/dist/index.js"Direct STDIO
node dist/index.jsAvailable Tools
Tool | Description |
| Initialize a new Ralph Loop session with a task |
| Get the current task for the worker phase |
| Submit work results and summary from worker |
| Get worker's submitted work for reviewer |
| Submit review decision (SHIP/REVISE) with feedback |
| Get reviewer feedback for next iteration |
| Get current session status (iteration, phase, state) |
| Reset/clear a session |
| Block current iteration with reason |
Workflow Example
1. Initialize a Session
{
"method": "tools/call",
"params": {
"name": "ralph_loop_initialize",
"arguments": {
"sessionId": "my-feature",
"task": "Implement user authentication with JWT tokens",
"maxIterations": 5
}
}
}2. Worker Phase - Get Task
{
"method": "tools/call",
"params": {
"name": "ralph_loop_get_task",
"arguments": { "sessionId": "my-feature" }
}
}3. Worker Phase - Submit Work
{
"method": "tools/call",
"params": {
"name": "ralph_loop_submit_work",
"arguments": {
"sessionId": "my-feature",
"iteration": 1,
"work": "// Complete JWT implementation...",
"summary": "Implemented JWT auth with access/refresh tokens, middleware, and tests"
}
}
}4. Reviewer Phase - Get Work
{
"method": "tools/call",
"params": {
"name": "ralph_loop_get_work",
"arguments": { "sessionId": "my-feature" }
}
}5. Reviewer Phase - Submit Review
{
"method": "tools/call",
"params": {
"name": "ralph_loop_submit_review",
"arguments": {
"sessionId": "my-feature",
"iteration": 1,
"decision": "REVISE",
"feedback": "Add token expiration handling and improve error messages"
}
}
}6. Next Iteration - Get Feedback
{
"method": "tools/call",
"params": {
"name": "ralph_loop_get_feedback",
"arguments": { "sessionId": "my-feature" }
}
}7. Check Status
{
"method": "tools/call",
"params": {
"name": "ralph_loop_get_status",
"arguments": { "sessionId": "my-feature" }
}
}State Management
State is stored in ~/.goose/ralph/{sessionId}/:
~/.goose/ralph/my-feature/
├── task.json # Original task
├── work.json # Current work submission
├── review.json # Current review
├── work-complete.txt # Worker completion flag
├── review-result.txt # SHIP/REVISE decision
├── review-feedback.txt # Reviewer feedback
├── RALPH-BLOCKED.md # Blocking reason (if blocked)
└── iteration.txt # Current iteration numberCross-Model Review Setup
For true cross-model review, use different models for worker and reviewer:
Worker (e.g., Claude Sonnet):
Gets fresh context each iteration
Receives only task + feedback
Does the actual work
Reviewer (e.g., GPT-4, Gemini, or another Claude):
Reviews worker's output
Provides SHIP/REVISE decision
Gives specific feedback for revision
Blocking
If the worker gets stuck, they can block the iteration:
{
"method": "tools/call",
"params": {
"name": "ralph_loop_block",
"arguments": {
"sessionId": "my-feature",
"reason": "Cannot proceed - missing API credentials for external service"
}
}
}This creates RALPH-BLOCKED.md and stops the loop until resolved.
API Reference
ralph_loop_initialize
{
sessionId?: string; // default: "default"
task: string; // required
maxIterations?: number; // default: 10, max: 50
}ralph_loop_get_task
{
sessionId?: string; // default: "default"
}ralph_loop_submit_work
{
sessionId?: string; // default: "default"
work: string; // required
summary: string; // required
iteration: number; // required, >= 1
}ralph_loop_get_work
{
sessionId?: string; // default: "default"
}ralph_loop_submit_review
{
sessionId?: string; // default: "default"
decision: "SHIP" | "REVISE"; // required
feedback?: string; // required for REVISE
iteration: number; // required, >= 1
}ralph_loop_get_feedback
{
sessionId?: string; // default: "default"
}ralph_loop_get_status
{
sessionId?: string; // default: "default"
}ralph_loop_reset
{
sessionId?: string; // default: "default"
}ralph_loop_block
{
sessionId?: string; // default: "default"
reason: string; // required
}Development
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run server
npm start
# Development (build + run)
npm run devLicense
MIT
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sheldonrobinson/ralph-loop-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server