README

Ralph

!Ralph

Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, progress.txt, and prd.json.

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

 Prerequisites

- One of the following AI coding tools installed and authenticated:
  - Amp CLI (default)
  - Claude Code (npm install -g @anthropic-ai/claude-code)
- jq installed (brew install jq on macOS)
- A git repository for your project

 Setup

 Option 1: Copy to your project

Copy the ralph files into your project:

bash
 From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

 Copy the prompt template for your AI tool of choice:
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md     For Amp
 OR
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md     For Claude Code

chmod +x scripts/ralph/ralph.sh


 Option 2: Install skills globally (Amp)

Copy the skills to your Amp or Claude config for use across all projects:

For AMP
bash
cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/


For Claude Code (manual)
bash
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/


 Option 3: Use as Claude Code Marketplace

Add the Ralph marketplace to Claude Code:

bash
/plugin marketplace add snarktank/ralph


Then install the skills:

bash
/plugin install ralph-skills@ralph-marketplace


Available skills after installation:
- /prd - Generate Product Requirements Documents
- /ralph - Convert PRDs to prd.json format

Skills are automatically invoked when you ask Claude to:
- "create a prd", "write prd for", "plan this feature"
- "convert this prd", "turn into ralph format", "create prd.json"

 Configure Amp auto-handoff (recommended)

Add to ~/.config/amp/settings.json:

json
{
  "amp.experimental.autoHandoff": { "context": 90 }
}


This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.

 Workflow

 1. Create a PRD

Use the PRD skill to generate a detailed requirements document:


Load the prd skill and create a PRD for [your feature description]


Answer the clarifying questions. The skill saves output to tasks/prd-[feature-name].md.

 2. Convert PRD to Ralph format

Use the Ralph skill to convert the markdown PRD to JSON:


Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json


This creates prd.json with user stories structured for autonomous execution.

 3. Run Ralph

bash
 Using Amp (default)
./scripts/ralph/ralph.sh [max_iterations]

 Using Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]


Default is 10 iterations. Use --tool amp or --tool claude to select your AI coding tool.

Ralph will:
1. Create a feature branch (from PRD branchName)
2. Pick the highest priority story where passes: false
3. Implement that singl

Top issues