Developers already using Amp or Claude Code who have a git repo with typechecking and tests, and are comfortable with bash and jq.

What can you build with ralph?

Turn a written feature spec into a series of tested commits on a feature branch. Break a large feature into small stories and let an agent work through them unattended. Generate a PRD from a feature idea by answering a skill's clarifying questions. Build up an AGENTS.md file that records your codebase's conventions and gotchas. Run Claude Code or Amp repeatedly against a project that has typecheck and tests.

snarktank /

ralph

A bash loop that reruns an AI coding agent until every item in your PRD passes

22k stars
150 stars since 3 Oct
TypeScript
Updated 9 months ago
Some experience
Coding agents & dev tools

Open on GitHub (opens in a new tab) Website (opens in a new tab)

Coding agents run out of context when a task is large. Ralph works around this by splitting a feature into small user stories and starting a fresh agent instance for each one. It follows Geoffrey Huntley's Ralph pattern.

You write a product requirements document (PRD) with a skill, then convert it to prd.json. A bash script, ralph.sh, picks the highest-priority story that hasn't passed and asks the agent to implement it. It then runs typecheck and tests. If the checks pass, it commits and marks the story done.

Because every iteration starts with clean context, memory lives in three places: git history, a progress.txt file of learnings, and prd.json. Ralph also updates AGENTS.md files so later runs, and human developers, pick up the patterns it found. It works with Amp (the default) or Claude Code.

What it does

Fresh context each iteration
Every loop spawns a new Amp or Claude Code instance. State carries over only through git commits, progress.txt and prd.json.
PRD and conversion skills
A prd skill writes a requirements document after asking clarifying questions. A ralph skill converts it into prd.json with user stories.
One story per iteration
Ralph picks the top story with passes set to false, implements it, runs quality checks, commits on success and marks it passed.
Learnings written back
Each run appends notes to progress.txt and updates AGENTS.md files with patterns and gotchas it found.
Archiving and stop condition
Earlier runs are archived when the branch name changes. The loop exits when all stories pass or the max iteration count (default 10) is reached.

What you could build

Turn a written feature spec into a series of tested commits on a feature branch.
Break a large feature into small stories and let an agent work through them unattended.
Generate a PRD from a feature idea by answering a skill's clarifying questions.
Build up an AGENTS.md file that records your codebase's conventions and gotchas.
Run Claude Code or Amp repeatedly against a project that has typecheck and tests.

Get started

Install Amp or Claude Code and jq, then copy ralph.sh and the matching prompt template (prompt.md for Amp, CLAUDE.md for Claude Code) into your project and make the script executable. Create a PRD, convert it to prd.json with the skills, then run the script.

mkdir -p scripts/ralph

cp /path/to/ralph/ralph.sh scripts/ralph/

./scripts/ralph/ralph.sh --tool claude [max_iterations]

Commands are copied from the project's README. Read it on GitHub for the full setup.