Ralph CLI

Run AI coding agents in a loop. Based on Matt Pocock's Ralph Wiggum pattern.

What is Ralph?

Ralph runs Claude Code (or other AI CLIs) in a loop, letting it work autonomously on a list of tasks. You define what needs to be done in a PRD. Ralph figures out how - and keeps going until it's finished.

Iteration 1: Claude reads PRD, picks highest priority task, implements it, commits
Iteration 2: Claude reads PRD + progress, picks next task, implements, commits
...
Iteration N: Claude sees all tasks done, outputs COMPLETE, loop exits

Install

# Clone and install
git clone https://github.com/rathi/ralph-cli.git
cd ralph-cli
./install.sh

# Or one-liner
curl -fsSL https://raw.githubusercontent.com/rathi/ralph-cli/main/install.sh | bash

Quick Start

# 1. Initialize Ralph in your repo
cd your-project
ralph init

# 2. Edit the PRD with your tasks
vim .ralph/prd.md

# 3. Run Ralph
ralph run 10

Usage

ralph init                    # Set up Ralph in current repo
ralph run <iterations>        # Run the loop
ralph run 10 -p custom.md     # Use custom PRD file
ralph generate tests          # Auto-generate PRD from codebase
ralph status                  # Show progress
ralph reset                   # Clear progress and start over
ralph --help                  # See all options

PRD Format

# My Feature PRD

## Overview
What you want Ralph to accomplish.

## Tasks (Priority Order)

- [ ] CRITICAL: Set up database schema
      Create migrations for users and posts tables.
      Source: src/db/

- [ ] HIGH: Add user authentication
      Implement login/logout with JWT.
      Source: src/auth/

- [ ] MEDIUM: Build API endpoints
      REST endpoints for CRUD operations.

- [ ] LOW: Add tests
      Unit tests for auth module.

## Completion Criteria
All endpoints working, tests passing.

How It Works

1. PRD File (.ralph/prd.md): Your task list with priorities
2. Progress File (ralph-progress.txt): Tracks what's done between iterations
3. Loop: Each iteration, Claude:
   • Reads PRD and progress
   • Picks highest priority incomplete task
   • Implements it
   • Updates progress file
   • Commits changes
4. Completion: When all tasks done, outputs <promise>COMPLETE</promise> and exits

Options

Flag	Description
-p, --prd <file>	Custom PRD file (default: .ralph/prd.md)
--docker	Run in Docker sandbox (safer for AFK)
--dry-run	Show what would happen

Tips

1. Start with HITL: Run ralph run 1 and watch before going AFK
2. Small tasks: One logical unit per PRD item
3. Priority matters: CRITICAL > HIGH > MEDIUM > LOW
4. Feedback loops: Add "run tests" to your PRD tasks
5. Check progress: ralph status or cat ralph-progress.txt

Requirements

• Claude Code CLI
• Bash 3.x+ (macOS default works)
• Optional: Docker Desktop 4.50+ for sandboxed runs

Credits

Based on Matt Pocock's Ralph Wiggum pattern.

License

MIT