Parallel Ralph loop: PRD → ralph_start → keep chatting → merged. Run multiple PRDs simultaneously in isolated worktrees with auto quality gates and merge.
Based on Geoffrey Huntley's Ralph pattern.
Step 1: Generate PRD
User: "Create a PRD for user authentication"
Claude: [Generates tasks/prd-auth.md]
Step 2: Execute
User: "Start" or "Execute this PRD"
Claude: ralph_start → Task Agent handles everything automatically
That's it. Ralph MCP automatically handles: branch creation, worktree isolation, code implementation, quality checks, commits, merge, and doc sync.
| Without Ralph | With Ralph |
|---|---|
| One feature at a time | Multiple features in parallel |
| Manual PRD writing | Claude generates PRD for you |
| Manual git branch management | Automatic worktree isolation |
| Lost progress on restart | Persistent state (JSON) |
| Manual merge coordination | Auto merge with conflict resolution |
| No visibility into progress | Real-time status tracking |
| Blocked while waiting | Keep chatting while agents work |
Ralph MCP extends snarktank/ralph with production-grade automation while preserving its core strengths.
| Feature | Original Ralph | Ralph MCP |
|---|---|---|
| Agent Lifecycle | One process per User Story | One long-lived agent per PRD |
| Execution Model | Manual script invocation | Background Runner + MCP integration |
| Parallel PRDs | Sequential only | 5+ PRDs simultaneously |
| Dependency Management | Manual coordination | Auto-triggered when dependencies complete |
| Stagnation Detection | None | Auto-detects stuck agents, marks as failed |
| Agent Memory | None | Progress Log persists learnings across stories |
| Merge Coordination | Manual | Serial merge queue with conflict resolution |
| Notifications | None | Windows Toast on completion |
| Claude Code Integration | Requires wrapper scripts | Native MCP tools (ralph_start, ralph_status, etc.) |
Ralph MCP keeps the battle-tested foundations:
- PRD-Driven Development - Structured requirements with User Stories and Acceptance Criteria
- Iterative Execution - One User Story at a time with quality gates
- Git Worktree Isolation - Zero conflicts between parallel features
- Quality Gates - Type check, lint, build before every commit
- Automatic Merge - Hands-free integration when all stories pass
- Long-Lived Agents: One agent completes all User Stories in a PRD (not spawning new processes per story)
- Runner Automation: Background process manages execution lifecycle, no manual script running
- MCP Native: Direct integration with Claude Code via MCP protocol
- State Persistence: JSON-based state survives restarts and enables parallel execution tracking
- 2-Step Workflow - Just create PRD and run
ralph_start, everything else is automatic - Parallel Execution - Run 5+ PRDs simultaneously with Claude Code Task tool
- Dual Agent Support - Use Claude Code or Codex CLI for agent execution
- Git Worktree Isolation - Each PRD runs in its own worktree, zero conflicts
- Dependency Management - PRDs can depend on other PRDs, auto-triggered when dependencies complete
- Stagnation Detection - Auto-detects stuck agents (no progress, repeated errors) and marks as failed
- Agent Memory - Persistent "Progress Log" learns from mistakes across User Stories
Ralph MCP supports two agent providers for PRD execution:
Uses Claude Opus 4 via Claude CLI for agent execution.
Requirements:
- Claude Code CLI installed
- LiteLLM proxy running on
localhost:4000(optional, for custom models)
Configuration:
# .ralph.yaml
agent:
provider: claude
coAuthor: "Claude Opus 4.6 <noreply@anthropic.com>"Uses GPT-5.3 Codex via Codex CLI for agent execution.
Requirements:
- Codex CLI installed
- LiteLLM proxy running on
localhost:4000 - Environment variables:
export OPENAI_BASE_URL=http://localhost:4000/v1 export OPENAI_API_KEY=<your-litellm-master-key>
Configuration:
# .ralph.yaml
agent:
provider: codex
coAuthor: "GPT-5.3 Codex <noreply@openai.com>"
codex:
# Path to Codex CLI (default: "codex")
codexPath: "codex"
# Approval policy for command execution
# Options: never, on-request, on-failure, untrusted
approvalPolicy: on-request
# Sandbox mode for filesystem access
# Options: read-only, workspace-write, danger-full-access
sandboxMode: workspace-write
# Execution level (L1=Executor, L2=Builder, L3=Autonomous, L4=Specialist)
level: L2
# Max auto-recovery attempts when stalled
maxRecoveryAttempts: 2
# Minutes of inactivity before detecting stall
stallTimeoutMinutes: 5| Feature | Claude Code | Codex |
|---|---|---|
| Context Window | 200k tokens | 128k tokens |
| Code Generation | Excellent | Excellent |
| Reasoning | Strong | Strong |
| Tool Use | Native MCP | CLI-based |
| Approval Policy | Skip permissions | Configurable |
| Sandbox Mode | N/A | Configurable |
| Best For | MCP integration, large context | CLI workflows, fine-grained control |
To switch between agents, update your .ralph.yaml:
# Use Claude Code
agent:
provider: claude
# Use Codex
agent:
provider: codexThen restart the Ralph MCP server or run ralph_doctor to verify configuration.
Ralph MCP's long-lived agent design differs from the original Ralph pattern. This section explains the reasoning behind both approaches.
Geoffrey Huntley designed Ralph with a clear constraint in mind: context window limits (~170k tokens at the time). His philosophy:
- One User Story per agent process - Each story gets a fresh agent with focused context
- Avoid multi-agent complexity - No inter-agent communication or coordination overhead
- Fast feedback loops - Quick iterations without context bloat
- Simple orchestration - Script-based execution, easy to understand and debug
This design was optimal for the constraints of 2024: limited context windows meant doing one thing well was better than trying to do everything at once.
Ralph MCP adopts long-lived agents (one agent per PRD) because the constraints have evolved:
1. Larger Context Windows (200k+ tokens)
- Modern Claude models can handle entire PRDs with multiple User Stories
- Context window is no longer the bottleneck for multi-story execution
2. Learning Accumulation
- Progress Log persists learnings across User Stories within the same PRD
- Later stories benefit from discoveries made in earlier stories
- Example: "US-001 found that
pnpm db:migrate:devmust run after schema changes" → US-003 knows this upfront
3. Reduced Startup Overhead
- Spawning a new agent 8000 process per story adds latency (model loading, context injection)
- Long-lived agents amortize this cost across all stories in a PRD
4. Context Continuity
- Agent remembers architectural decisions from previous stories
- No need to re-explain project structure or conventions for each story
- Natural conversation flow: "continue with the same approach from US-002"
| Aspect | Original Ralph | Ralph MCP |
|---|---|---|
| Context Window | 170k tokens | 200k+ tokens |
| Agent Lifecycle | Short (per User Story) | Long (per PRD) |
| Learning Accumulation | None (fresh start each story) | Progress Log persists across stories |
| Startup Overhead | High (every story) | Low (once per PRD) |
| Context Continuity | None (stateless) | Full (agent remembers previous stories) |
| Complexity | Simple (script-based) | Moderate (background runner + state management) |
| Best For | Small context windows, simple PRDs | Large context windows, multi-story PRDs |
Original Ralph is better when:
- Context window is limited (<200k tokens)
- PRDs are simple (1-3 User Stories)
- You prefer script-based simplicity over automation
- Each User Story is independent with no shared learnings
Ralph MCP is better when:
- Context window is large (200k+ tokens)
- PRDs are complex (5+ User Stories)
- You want parallel execution of multiple PRDs
- Later stories benefit from earlier discoveries
- You need background execution with state persistence
Both approaches respect the same core principle: structured, iterative execution with quality gates. The difference is in how they manage agent lifecycle:
- Original Ralph: "Do one thing well, then exit" (optimal for 2024 constraints)
- Ralph MCP: "Do all related things in one session" (optimal for 2025+ capabilities)
Ralph MCP doesn't replace the original pattern—it extends it for environments where context windows and automation infrastructure support longer-lived agents.
- Context Injection - Inject project rules (CLAUDE.md) into agent context
- Auto Quality Gates - Type check, lint, build before every commit
- Auto Merge - Merges to main when all User Stories pass
- Merge Queue - Serial merge queue to avoid conflicts
- Notifications - Windows Toast when PRD completes
Ralph maintains a ralph-progress.md file in each worktree that persists learnings across User Stories. This gives agents "memory" of what worked and what didn't.
- When an agent completes a User Story, it records learnings in the
notesfield ofralph_update - Ralph appends these notes to
ralph-progress.mdin the worktree - When the next User Story starts, the agent receives this log in its prompt
- The file is automatically git-ignored (via
.git/info/exclude)
## [2024-01-15 14:30] US-001: Setup Database Schema
- Used Prisma with PostgreSQL
- Added index on `userId` for faster queries
- Note: Must run `pnpm db:migrate:dev` after schema changes
## [2024-01-15 15:45] US-002: User Registration API
- Reused validation patterns from existing auth module
- BCrypt rounds set to 12 for password hashing
- Integration test requires test database to be runningThis allows later stories to benefit from earlier discoveries without re-learning.
npm install -g ralph-mcpgit clone https://github.com/G0d2i11a/ralph-mcp.git
cd ralph-mcp
npm install
npm run buildAdd to ~/.claude/mcp.json:
{
"mcpServers": {
"ralph": {
"command": "npx",
"args": ["ralph-mcp"]
}
}
}Or if installed from source:
{
"mcpServers": {
"ralph": {
"command": "node",
"args": ["/path/to/ralph-mcp/dist/index.js"]
}
}
}Restart Claude Code to load.
ralph-runnernow launches PRDs through the SDK backend layer undersrc/agent-sdk/- The default provider is
codex - Set
agent.provider: claudeto switch the runner to the Claude SDK backend - Legacy
agent.codex.codexPathremains in the schema for compatibility, but the SDK runner ignores it
Copy examples/ralph.config.example.yaml to .ralph.yaml in your project, or to ~/.ralph/config.yaml for a global default:
agent:
provider: codex
codex:
approvalPolicy: never
sandboxMode: workspace-write
level: L2
# Optional: switch the runner to Claude SDK instead
# agent:
# provider: claudeFor the best experience, create a skill file that teaches Claude how to use Ralph.
See SKILL-EXAMPLE.md for a complete, copy-paste ready skill configurationQuick Setup
# 1. Create skill directory
mkdir -p .claude/skills/ralph
# 2. Copy the example (adjust path as needed)
cp /path/to/ralph-mcp/SKILL-EXAMPLE.md .claude/skills/ralph/SKILL.md
# 3. Customize quality check commands for your project## Skills
| Skill | Trigger |
|-------|---------|
| `ralph` | PRD execution (generate PRD → start → auto merge) |This enables Claude to automatically use Ralph when you mention PRD execution.
| Tool | Description |
|---|---|
ralph_start |
Start PRD execution (parse PRD, create worktree, return agent prompt) |
ralph_batch_start |
Start multiple PRDs with dependency resolution |
ralph_status |
View all PRD execution status |
ralph_get |
Get single PRD details |
ralph_update |
Update User Story status (called by agent) |
ralph_stop |
Stop execution |
ralph_merge |
Merge to main + cleanup worktree |
ralph_merge_queue |
Manage serial merge queue |
ralph_set_agent_id |
Record agent task ID |
ralph_retry |
Retry a failed PRD execution |
ralph_reset_stagnation |
Reset stagnation counters after manual interion |
User: Help me finish the Speaking module from TODO.md
Claude: Let me check TODO.md... Found 3 incomplete items:
- Speaking dialogue practice
- Speaking scoring optimization
- Speaking question bank
I'll create 3 PRDs...
[Generates prd-speaking-dialogue.md]
[Generates prd-speaking-scoring.md]
[Generates prd-speaking-qb.md]
User: Start
Claude:
[ralph_start × 3]
[Task Agent × 3 running in parallel]
3 PRDs started. They'll auto-merge when complete.
Use ralph_status to check progress.
--- Some time later ---
User: Progress?
Claude: [ralph_status]
✅ prd-speaking-dialogue - Merged
✅ prd-speaking-scoring - Merged
🔄 prd-speaking-qb - US-003/005 in progress
User: 👍
// 1. Start PRD execution
ralph_start({ prdPath: "tasks/prd-feature.md" })
// 2. Check status anytime
ralph_status()
// 3. Manual merge if needed (usually automatic)
ralph_merge({ branch: "ralph/prd-feature" })// Start PRD execution (returns agent prompt)
ralph_start({ prdPath: "tasks/prd-feature.md" })
// Start multiple PRDs in parallel
ralph_batch_start({ prdPaths: ["tasks/prd-a.md", "tasks/prd-b.md"] })
// View all PRD status
ralph_status()
// Get single PRD details
ralph_get({ branch: "ralph/prd-feature" })
// Update User Story status (called by agent)
ralph_update({ branch: "ralph/prd-feature", storyId: "US-1", passes: true, notes: "..." })
// Stop execution
ralph_stop({ branch: "ralph/prd-feature" })
// Merge to main
ralph_merge({ branch: "ralph/prd-feature" })
// Record Task agent ID (for tracking)
ralph_set_agent_id({ branch: "ralph/prd-feature", agentTaskId: "abc123" })
// Retry a failed execution
ralph_retry({ branch: "ralph/prd-feare" })
// Reset stagnation counters (after manual fix)
ralph_reset_stagnation({ branch: "ralph/prd-feature" })Ralph parses markdown PRD files. Example:
---
title: User Authentication
priority: high
---
# User Authentication
Implement user login and registration.
## User Stories
### US-1: User Registration
Users can create new accounts.
**Acceptance Criteria:**
- [ ] Email validation
- [ ] Password strength check
- [ ] Confirmation email sent
### US-2: User Login
Users can log into their accounts.
**Acceptance Criteria:**
- [ ] Email/password authentication
- [ ] Remember me option
- [ ] Forgot password flowralph_merge supports these strategies:
| Strategy | Behavior |
|---|---|
auto_theirs |
git merge -X theirs, prefer main |
auto_ours |
git merge -X ours, prefer branch |
notify |
Pause, notify user to resolve manually |
agent |
Launch merge subagent to resolve (default) |
- State:
~/.ralph/state.json - Logs:
~/.ralph/logs/
Override data directory with RALPH_DATA_DIR environment variable.
| Option | Default | Description |
|---|---|---|
prdPath |
required | Path to PRD markdown file |
projectRoot |
cwd | Project root directory |
worktree |
true |
Create isolated git worktree |
autoStart |
true |
Return agent prompt for immediate execution |
autoMerge |
true |
Auto add to merge queue when all stories pass |
notifyOnComplete |
true |
Show Windows notification on completion |
onConflict |
"agent" |
Conflict resolution: auto_theirs, auto_ours, notify, agent |
contextInjectionPath |
undefined |
Optionalfile (e.g. CLAUDE.md) to inject into prompt |
ignoreDependencies |
false |
Skip dependency check and start even if dependencies are not satisfied |
queueIfBlocked |
false |
If dependencies are not satisfied, create a pending execution instead of failing |
ralph_start({
prdPath: "tasks/prd-feature.md",
autoMerge: true, // Auto-merge when done
notifyOnComplete: true, // Windows Toast notification
onConflict: "auto_theirs" // Prefer main on conflicts
})Start multiple PRDs with dependency resolution and serial pnpm install.
| Option | Default | Description |
|---|---|---|
prdPaths |
required | Array of paths to PRD markdown files |
projectRoot |
cwd | Project root directory |
worktree |
true |
Create worktrees for isolation |
autoMerge |
true |
Auto add to merge queue when all stories pass |
notifyOnComplete |
true |
Show Windows notification on completion |
onConflict |
"agent" |
Conflict resolution strategy |
contextInjectionPath |
undefined |
Path to file (e.g. CLAUDE.md) to inject into prompt |
| heat` | true |
Run pnpm install serially beforeting agents |
ralph_batch_start({
prdPaths: [
"tasks/prd-auth.md",
"tasks/prd-dashboard.md",
"tasks/prd-settings.md"
],
contextInjectionPath: "CLAUDE.md",
autoMerge: true
})Retry a failed PRD execution. Resets stagnation counters and generates a new agent prompt to continue from where it left off.
// Retry a failed execution
ralph_retry({ branch: "ralph/prd-feature" })
// Returns: { success, branch, message, previousStatus, agentPrompt, progress }Reset stagnation counters after manual intervention. Use when you've fixed an issue and want the agent to continue.
| Option | Default | Description |
|---|---|---|
branch |
required | Branch name |
resumeExecution |
true |
Also set status back to 'running' if currently 'failed' |
// Reset counters and resume
ralph_reset_stagnation({ branch: "ralph/prd-feature" })
// Reset counters only (keep failed status)
ralph_reset_stagnation({ branch: "ralph/prd-feature", resumeExecution: false })- Verified completedUS skip logic: Confirmed that ralph-mcp's database-driven architecture automatically skips completed User Stories via
stories.filter((s) => !s.passes)in agent prompt generation. Unlike ralph-cli which required manualcompletedUS.includes()checks, ralph-mcp's design inherently prevents re-execution of completed stories. - Fixed progress detection false positives
- Added commit count tracking to distinguish real progress from stagnation
- Prevents agents from being marked as stagnant after successfully committing code
- Geoffrey Huntley - Original Ralph pattern
- Anthropic - Claude Code & MCP protocol
MIT