ralph

What is ralph?

ralph runs AI coding agents in iterative loops. Instead of trying to one-shot prompts that hit context limits and get confused, ralph resets the context window between iterations while preserving the learning from each loop through your codebase.

ralph run -n 10 -p ./plans/PROMPT.md

The AI does work, commits changes, saves insights,exits, ralph checks if done, resets context, and loops—until your task is complete.

Full documentation can be found at https://wiggum.dev.

Why "Ralph Wiggum"?

The technique was coined by Geoffrey Huntley:

"Ralph is a Bash loop."

Named after Ralph Wiggum from The Simpsons—embodying the philosophy of persistent iteration despite setbacks. "Me fail English? That's unpossible!"

Installation

npm install -g @wiggumdev/ralph

You'll also need an AI CLI tool:

# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code

# Or OpenCode
npm i -g opencode-ai

Supported Adapters

| Adapter | Status | ACP Command | |---------|--------|-------------| | Claude Code | Complete | claude-code-acp | | OpenCode | Complete | opencode acp | | Gemini CLI | Under Development | gemini --experimental-acp |

All adapters communicate via ACP (Agent Client Protocol).

Quick Start

# Initialize in your project
cd your-project
ralph init

# Use your agent to generate a plan and write
zed .plans/prd.json

# Edit your prompt to your specific needs
zed .plans/PROMPT.md

# Run the loop
ralph run

Features

• Context Reset — Fresh context window each iteration
• State Persistence — Progress via git, files, and tests
• Completion Detection — AI signals when done with <promise>COMPLETE</promise>
• Lifecycle Hooks — Run commands at key points in the loop

How It Works

flowchart TD
    Start --> RunAI[Run AI];
    RunAI --> Check;
    Check --> Learn;
    Learn --> Done{Done?};
    Done -->|No| Reset;
    Reset --> Start;
    Done -->|Yes| Exit;

    Note[State persists via:<br/>git, files, tests]

Each iteration:

1. AI starts with fresh context
2. Reads codebase to understand state
3. Does work (writes code, runs tests)
4. ralph checks for completion marker
5. If not done, reset and loop

Configuration

ralph uses TOML config at .ralph/config.toml:

adapter = "claude"
maxIterations = 20
plansDir = ".plans"
debug = false
tui = true
yolo = false
transportLog = false

[hooks]
ralph_start = ""
ralph_loop_end = "npm run lint:fix"
ralph_complete = "say 'Ralph is done!'"

Project Structure

After ralph init:

project/
├── .ralph/
│   └── config.toml      # Configuration
└── .plans/
    ├── prd.json         # Feature requirements
    ├── PROMPT.md        # Your ralph loop prompt
    └── progress.txt     # Learning log

Commands

ralph init              # Initialize ralph in a project
ralph run               # Start the agentic loop
ralph check             # Validate prd.json schema

Run Options

ralph run --max-iterations 10   # Limit iterations
ralph run --once                # Single iteration (no loop)
ralph run --prompt TASK.md      # Use specific prompt file
ralph run --debug               # Write debug log to file
ralph run --yolo                # Auto-approve all permissions
ralph run --transport-log       # Log raw ACP transport messages

Loop Prompt Example

Your prompt in .plans/PROMPT.md should include:

@.plans/prd.json @.plans/progress.txt

1. Find the highest-priority feature to work on and work ONLY on that feature. This should be the one YOU decide has the highest priority - not necessarily the first in the list

2. Before making changes, search codebase (don't assume not implemented).

3. Implement the requirements for the selected feature using TDD.

3. Run typecheck and tests: `bun run typecheck && bun run test`

4. Update prd.json marking completed work (CAREFULLY!)

**YOU CAN ONLY MODIFY ONE FIELD: "passes"**

After thorough verification, change:
\`\`\`json
"passes": false
\`\`\`
to:
\`\`\`json
"passes": true
\`\`\`

5. Append learning to .plans/progress.txt for future iterations.

6. Commit changes: `jj commit -m "description"`

ONLY WORK ON A SINGLE FEATURE PER ITERATION.

If all features complete, output <promise>COMPLETE</promise>

When you learn something new about how to run commands or patterns in the code make sure you update @CLAUDE.md using a subagent but keep it brief.

Remember: You have unlimited time across many sessions. Focus on quality over speed. Production-ready is the goal.

Documentation

Full documentation at wiggum.dev

Based On

• The original Ralph concept by Geoffrey Huntley
• Anthropic's research on effective harnesses for long-running agents
• Matt Pocock's explanation of the technique

License

MIT