Skip to main content
Ralph Logo

​
Welcome to 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.

​
Key Features

Fresh Context Per Iteration

Each iteration spawns a new AI instance with clean context for optimal performance

Structured Task Execution

Convert PRDs to JSON format for systematic, autonomous task completion

Built-in Quality Checks

Automatic typecheck, tests, and linting ensure code quality across iterations

Progress Tracking

Track progress via git history, progress.txt, and prd.json status updates

PRD Skills

Built-in skills for generating PRDs and converting them to Ralph format

Multi-Tool Support

Works with both Amp and Claude Code AI coding tools

​
How It Works

Ralph follows a simple but powerful loop:
  1. Read the PRD — Pick the highest priority story where passes: false
  2. Implement — Work on that single user story
  3. Quality Check — Run typecheck, tests, and lint
  4. Commit — If checks pass, commit the changes
  5. Update — Mark story as passes: true in prd.json
  6. Learn — Append learnings to progress.txt
  7. Repeat — Continue until all stories pass
Each iteration is a fresh AI instance with no memory of previous context. The only persistence is through git history, progress.txt, and prd.json.

​
Quick Start

Get started with Ralph in minutes:
1

Install Prerequisites

Install Amp CLI or Claude Code, plus jq for JSON processing
2

Copy Ralph Files

Copy ralph.sh and the prompt template to your project
3

Create a PRD

Use the PRD skill to generate requirements for your feature
4

Run Ralph

Execute ./ralph.sh to start the autonomous loop

Get Started Now

Follow our quickstart guide to set up Ralph in your project

​
Why Ralph?

Traditional AI coding workflows struggle with large features that exceed a single context window. Ralph solves this by:
  • Breaking work into small stories that fit in one context window
  • Spawning fresh instances to avoid context pollution
  • Using git as memory so each iteration builds on clean commits
  • Enforcing quality gates to prevent broken code from compounding
  • Capturing learnings in progress.txt for future iterations
Ralph works best when stories are right-sized: small enough to complete in one iteration, but meaningful enough to be tested and verified independently.

​
Use Cases

Ralph excels at:
  • Feature development — Break down PRDs into incremental stories
  • Refactoring — Systematically update code patterns across a codebase
  • Migration — Step-by-step migration of APIs or frameworks
  • Bug fixes — Tackle multiple related bugs with consistent patterns

​
Next Steps

Quickstart Guide

Set up Ralph in your project

Core Concepts

Understand how Ralph works

Workflow Guide

Learn the full workflow

CLI Reference

Explore command-line options