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

Installation • Quick Start • Documentation • Why 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.

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!"

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

# 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

• 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

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

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!'"

After ralph init:

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

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

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

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.

Full documentation at wiggum.dev

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

MIT