# Ralph CLI

Run AI coding agents in a loop. Based on [Matt Pocock's Ralph Wiggum pattern](https://www.aihero.dev/posts/tips-for-ai-coding-with-ralph).

## 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

```bash
# 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

```bash
# 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

```bash
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

```markdown
# 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](https://docs.anthropic.com/en/docs/claude-code)
- Bash 3.x+ (macOS default works)
- Optional: Docker Desktop 4.50+ for sandboxed runs

## Credits

Based on [Matt Pocock's Ralph Wiggum pattern](https://www.aihero.dev/posts/tips-for-ai-coding-with-ralph).

## License

MIT