┌─────────────────────────────────────────────────────────────┐
│                    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)        │
│   └─────────┘                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# Clone the repository
git clone https://github.com/sheldonrobinson/ralph-loop-mcp
cd ralph-loop-mcp

# Make executable (Linux/macOS)
chmod +x ralph-loop-runner.sh

# Configure in Claude Desktop (MCP mode):
{
  mode):
{
  "mcpServers": {
    "ralph-loop": {
      "command": "/path/to/ralph-loop-runner.sh",
      "args": []
    }
  }
}

# Configure in claude_desktop_config.json:
{
  "mcpServers": {
    "ralph-loop": {
      "command": "powershell.exe",
      "args": ["-File", "C:\\path\\to\\ralph-loop-runner.ps1"]
    }
  }
}

# Linux/macOS - task as argument
./ralph-loop-runner.sh "Implement user authentication with JWT tokens"

# Linux/macOS - task from file
./ralph-loop-runner.sh ./task.md

# Windows
.\ralph-loop-runner.ps1 "Implement user authentication with JWT tokens"
.\ralph-loop-runner.ps1 .\task.md

RALPH_WORKER_MODEL=claude-3-5-sonnet \
RALPH_WORKER_PROVIDER=anthropic \
RALPH_REVIEWER_MODEL=gpt-4o \
RALPH_REVIEWER_PROVIDER=openai \
RALPH_MAX_ITERATIONS=5 \
./ralph-loop-runner.sh "Your task here"

./ralph-loop-runner.sh "Your task here" \
  --worker-model claude-3-5-sonnet \
  --worker-provider anthropic \
  --worker-agent goose \
  --reviewer-model gpt-4o \
  --reviewer-provider openai \
  --reviewer-agent goose \
  --max-iterations 5 \
  --work-guidelines ./recipes/ralph-work.yaml \
  --review-guidelines ./recipes/ralph-review.yaml \
  --session-id my-feature

# Linux/macOS
./ralph-loop-runner.sh

# Windows
powershell.exe -File ralph-loop-runner.ps1

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_run",
    "arguments": {
      "sessionId": "my-feature",
      "task": "Implement user authentication with JWT tokens",
      "maxIterations": 5,
      "workerModel": "claude-3-5-sonnet",
      "workerProvider": "anthropic",
      "workerAgent": "goose",
      "reviewerModel": "gpt-4o",
      "reviewerProvider": "openai",
      "reviewerAgent": "goose",
      "crossModelReviewEnforced": true,
      "workGuidelines": "/path/to/ralph-work.yaml",
      "reviewGuidelines": "/path/to/ralph-review.yaml"
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_initialize",
    "arguments": {
      "sessionId": "my-feature",
      "task": "Implement user authentication with JWT tokens",
      "maxIterations": 5,
      "workerModel": "claude-3-5-sonnet",
      "workerProvider": "anthropic",
      "workerAgent": "goose",
      "reviewerModel": "gpt-4o",
      "reviewerProvider": "openai",
      "reviewerAgent": "goose"
    }
  }
}

{
  "method": "tools/call",
  "params": { "name": "ralph_loop_get_task", "arguments": { "sessionId": "my-feature" } }
}

{
  "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"
    }
  }
}

{
  "method": "tools/call",
  "params": { "name": "ralph_loop_get_work", "arguments": { "sessionId": "my-feature" } }
}

{
  "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"
    }
  }
}

{
  "method": "tools/call",
  "params": { "name": "ralph_loop_get_feedback", "arguments": { "sessionId": "my-feature" } }
}

~/.goose/ralph/my-feature/
├── config.json           # Worker/reviewer model configuration
├── 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 number

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_block",
    "arguments": {
      "sessionId": "my-feature",
      "reason": "Cannot proceed - missing API credentials for external service"
    }
  }
}

{
  sessionId?: string;              // default: "default"
  task: string;                    // required
  maxIterations?: number;          // default: 10, -1 = unlimited
  workerModel?: string;            // e.g., "claude-3-5-sonnet"
  workerProvider?: string;         // e.g., "anthropic"
  workerAgent?: string;            // e.g., "goose"
  reviewerModel?: string;          // e.g., "gpt-4o"
  reviewerProvider?: string;       // e.g., "openai"
  reviewerAgent?: string;          // e.g., "goose"
  crossModelReviewEnforced?: boolean; // default: true
  workGuidelines?: string;         // path to work guidelines
  reviewGuidelines?: string;       // path to review guidelines
}

{ sessionId?: string; }  // default: "default"

{
  sessionId?: string;  // default: "default"
  work: string;        // required
  summary: string;     // required
  iteration: number;   // required, >= 1
}

{ sessionId?: string; }  // default: "default"

{
  sessionId?: string;           // default: "default"
  decision: "SHIP" | "REVISE";  // required
  feedback?: string;            // required for REVISE
  iteration: number;            // required, >= 1
}

{ sessionId?: string; }  // default: "default"

{ sessionId?: string; }  // default: "default"

{ sessionId?: string; }  // default: "default"

{ sessionId?: string; }  // default: "default"

{
  sessionId?: string;  // default: "default"
  reason: string;      // required
}

{
  sessionId?: string;              // default: "default"
  task: string;                    // required
  maxIterations?: number;          // default: 10, -1 = unlimited
  workerModel: string;             // required
  workerProvider: string;          // required
  workerAgent?: string;            // default: "goose"
  reviewerModel: string;           // required
  reviewerProvider: string;        // required
  reviewerAgent?: string;          // default: "goose"
  crossModelReviewEnforced?: boolean; // default: true
  workGuidelines?: string;         // path to work guidelines
  reviewGuidelines?: string;       // path to review guidelines
}