ralph

ralph

AI-agnostic agentic loop CLI
Reset context. Persist learnings. Ship code.

Installation • Quick Start • Documentation • Why 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
Claude Code	Complete
OpenCode	Complete
Gemini CLI	Under Development

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"
verbose = false
tui = true

[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 --no-tui              # Plain text output (for CI)
ralph run --verbose             # Debug output

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