init

2026-04-15 07:04:48 +00:00 · 2026-01-22 14:46:48 -05:00 · 2026-01-22 14:46:48 -05:00 · f1df2259ca
commit f1df2259ca
3 changed files with 515 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,122 @@
+# 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