Ralph

Ralph is an autonomous AI agent loop that runs an AI worker (default: Amp, optional: Cursor CLI) repeatedly until all PRD items are complete. Each iteration is a fresh worker invocation with clean context. Memory persists via git history, scripts/ralph/prd.json, and the shared context file specified by prd.json (contextFile).

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

Prerequisites

• One worker installed:
  • Amp CLI installed and authenticated, and/or
  • Cursor CLI (cursor) installed and authenticated
• jq installed (brew install jq on macOS)
• A git repository for your project

Setup

Option 1: Copy to your project

Copy the Ralph templates into your project:

# From your project root
mkdir -p scripts/ralph
cp -R /path/to/ralph/scripts/ralph/* scripts/ralph/
chmod +x scripts/ralph/ralph.sh
chmod +x scripts/ralph/cursor/convert-to-prd-json.sh

Option 2: Install skills globally

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

cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

Configure Amp auto-handoff (recommended)

Add to ~/.config/amp/settings.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

If you use Amp skills, 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.

If you use Cursor in the IDE, you can also generate a PRD using the repo's Cursor rules (see .cursor/rules/).

2. Convert PRD to Ralph format

If you use Amp skills, 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

Alternatively, you can convert PRD markdown to a Ralph *.prd.json using the Cursor helper script:

./scripts/ralph/cursor/convert-to-prd-json.sh tasks/prd-[feature-name].md

This is a multi-stage conversion that generates sidecar planning artifacts next to your input PRD, all with the same base name:

• <base>.execution-order.md: dependency-ordered phases with acceptance criteria
• <base>.context.md: slim shared context (durable patterns + facts)
• <base>.steps.md: bite-sized steps with verifiable acceptance criteria (one iteration per step)
• <base>.prd.json: the final prd.json for Ralph

Example:

• dashboard.prd.md
• dashboard.execution-order.md
• dashboard.context.md
• dashboard.steps.md
• dashboard.prd.json

3. Run Ralph

./scripts/ralph/ralph.sh [max_iterations] [--worker amp|cursor] [--cursor-timeout SECONDS]

Default is 10 iterations.

The runner loop will invoke the selected worker repeatedly. The worker prompt instructs it to:

• Read scripts/ralph/prd.json and the shared context file specified by prd.json (contextFile)
• Implement one story per iteration, run checks, commit, and update passes: true
• Stop by outputting <promise>COMPLETE</promise> when all stories pass

Examples:

# Default worker is Amp
./scripts/ralph/ralph.sh 10

# Run with Cursor CLI (with a per-iteration timeout)
./scripts/ralph/ralph.sh 10 --worker cursor --cursor-timeout 1800

Note: --cursor-timeout only applies if a timeout binary is available on your PATH. If it isn't, Ralph will run Cursor without a hard timeout.

Key Files

File	Purpose
scripts/ralph/ralph.sh	The bash loop that spawns fresh worker invocations
scripts/ralph/prompt.md	Instructions given to each Amp iteration
scripts/ralph/cursor/prompt.cursor.md	Instructions given to each Cursor iteration
scripts/ralph/cursor/convert-to-prd-json.sh	Multi-stage PRD builder (PRD → execution-order → context → steps → prd.json) via Cursor CLI
scripts/ralph/prd.json	User stories with passes status (the task list)
scripts/ralph/prd.json.example	Example PRD format for reference
contextFile (from prd.json)	Slim shared context carried across iterations (typically *.context.md)
logFile (from prd.json)	Append-only per-iteration run log (typically *.progress.log)
skills/prd/	Skill for generating PRDs
skills/ralph/	Skill for converting PRDs to JSON
flowchart/	Interactive visualization of how Ralph works

Flowchart

View Interactive Flowchart - Click through to see each step with animations.

The flowchart/ directory contains the source code. To run locally:

cd flowchart
npm install
npm run dev

Critical Concepts

Each Iteration = Fresh Context

Each iteration spawns a new worker invocation (Amp or Cursor) with clean context. The only memory between iterations is:

• Git history (commits from previous iterations)
• scripts/ralph/prd.json (which stories are done)
• The shared context file specified by prd.json (contextFile, typically *.context.md)

Small Tasks

Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.

Right-sized stories:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard"
• "Add authentication"
• "Refactor the API"

AGENTS.md Updates Are Critical

After each iteration, Ralph updates the relevant AGENTS.md files with learnings. This is key because Amp automatically reads these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions.

Examples of what to add to AGENTS.md:

• Patterns discovered ("this codebase uses X for Y")
• Gotchas ("do not forget to update Z when changing W")
• Useful context ("the settings panel is in component X")

Feedback Loops

Ralph only works if there are feedback loops:

• Typecheck catches type errors
• Tests verify behavior
• CI must stay green (broken code compounds across iterations)

Browser Verification for UI Stories

Frontend stories must include browser verification in acceptance criteria (e.g. "Verify in browser using browser MCP tools"). Ralph will use browser MCP tools (when configured) to navigate to the page, interact with the UI, and confirm changes work.

Stop Condition

When all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and the loop exits.

Debugging

Check current state:

# See which stories are done
cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'

# See shared context and per-iteration progress
# (file names come from prd.json: contextFile + logFile)
cat scripts/ralph/context.md
cat scripts/ralph/progress.log

# Check git history
git log --oneline -10

Customizing prompts

Edit the worker prompt(s) to customize Ralph's behavior for your project:

• Add project-specific quality check commands
• Include codebase conventions
• Add common gotchas for your stack

Worker prompt locations:

• Amp: scripts/ralph/prompt.md
• Cursor: scripts/ralph/cursor/prompt.cursor.md

Archiving

Ralph automatically archives previous runs when you start a new feature (different branchName). Archives are saved to scripts/ralph/archive/YYYY-MM-DD-feature-name/.

References

• Geoffrey Huntley's Ralph article
• Amp documentation