mirror of
https://github.com/harivansh-afk/ralph-cli.git
synced 2026-04-15 04:03:30 +00:00
122 lines
3.1 KiB
Markdown
122 lines
3.1 KiB
Markdown
# 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
|