Ralph: A Bash Loop That Runs AI Coding Tools Repeatedly Until All PRD Items Complete

The Problem Ralph Solves and Who It Is For

AI coding tools like Amp CLI and Claude Code run inside a single context window. When a feature is large enough to require more tokens than one context can hold, the tool runs out of context partway through and produces incomplete or poor-quality code. The developer must then restart the tool, re-explain the project context, and continue from where things stopped, often losing coherence between the earlier and later parts of the implementation.

Ralph addresses this by treating each AI coding session as one iteration of a loop. Each iteration spawns a fresh AI instance with a clean context, assigns it a single user story from a prd.json file, asks it to implement that story, run quality checks (typecheck and tests), and commit if the checks pass. The loop then reads the updated prd.json, finds the next incomplete story, and starts a new iteration.

The target audience is developers who are already using Amp CLI or Claude Code for feature development and who want to automate the loop between coding sessions. The README attributes the pattern to Geoffrey Huntley's Ralph pattern at ghuntley.com/ralph. This project is a TypeScript repository containing the bash script, prompt templates, and supporting skill files.

How the Loop Maintains State Across Fresh AI Instances

Each iteration of the Ralph loop spawns a fresh AI instance with no memory of previous iterations. The loop maintains continuity through three files that the AI instance reads at the start of each session.

The prd.json file contains the list of user stories, each with a passes field. At the end of a successful iteration, the AI updates prd.json to mark the completed story as passes: true. The loop reads this file at the start of the next iteration to find the next story where passes is false.

The progress.txt file is an append-only log of learnings from each iteration. At the end of each session, the AI appends observations about the codebase, patterns it discovered, and gotchas it encountered. Future iterations read this file to benefit from what earlier iterations learned.

Git history serves as the third memory mechanism. Each completed iteration ends with a commit, so the AI instance can read git log to understand what code was added in previous sessions. The README notes that AGENTS.md files in the repository are also updated with learnings after each iteration, because AI coding tools automatically read these files at the start of a session.

The stop condition is explicit: when all user stories have passes: true, the AI outputs the string COMPLETE wrapped in promise tags, and the bash loop exits. If the loop reaches its maximum iteration count before all stories are complete, it stops without completing the remaining stories.

Installing and Running Ralph

Ralph supports three installation paths. The first copies the script files directly into a project:

mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
chmod +x scripts/ralph/ralph.sh

The second installs Ralph's skills globally for Amp or Claude Code so they are available across all projects:

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

The third uses the Claude Code marketplace:

/plugin marketplace add snarktank/ralph

Once installed, running the loop with Amp (the default) or with Claude Code:

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

The loop requires jq to be installed (the README suggests brew install jq on macOS), an initialized git repository, and either Amp CLI or Claude Code installed and authenticated. The --tool flag selects between amp and claude as the AI tool. The default tool is Amp.

Before running the loop, the workflow is: use the prd skill to generate a Product Requirements Document, then use the ralph skill to convert that document into the prd.json format. The README gives the exact prompts: "Load the prd skill and create a PRD for [your feature description]" and "Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json".

Task Size and Feedback Loop Requirements

Ralph only works reliably when each user story in prd.json is small enough to complete within a single context window. The README gives concrete examples of right-sized stories: adding a database column and migration, adding a UI component to an existing page, updating a server action with new logic, and adding a filter dropdown to a list.

Stories that are too large for a single context window produce poor code because the AI runs out of context before finishing. The README lists stories that should be split up: building an entire dashboard, adding authentication, and refactoring an API are all too large for a single iteration.

The loop depends on feedback loops to catch errors before they compound across iterations. The README specifies that each iteration runs typecheck and tests after the implementation step, and only commits if these checks pass. Broken code that is committed will carry forward into subsequent iterations, where future AI instances must also handle the broken state.

For frontend stories, the README specifies that acceptance criteria should include browser verification using the dev-browser skill. This requires the dev-browser skill to be available to the AI tool.

The Context Window Handoff Configuration for Amp

When using Ralph with Amp CLI, the README recommends enabling automatic context handoff by adding a setting to ~/.config/amp/settings.json:

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

This setting triggers Amp to automatically create a new AI instance when the context fills to 90% of its capacity, passing along a summary of what was accomplished so far. Ralph can then handle stories that would exceed a single context window even within one iteration, because Amp handles the transition internally.

This configuration is described as recommended in the README and is marked experimental. It is specific to Amp and has no equivalent for Claude Code in the current README.

For debugging a stalled or failed run, the README provides three diagnostic commands:

cat prd.json | jq '.userStories[] | {id, title, passes}'
cat progress.txt
git log --oneline -10

These show which stories have been completed, what the AI learned in previous iterations, and the git history of the run.

Maintenance Status and License

The last push to the Ralph repository was on 2026-02-02. The repository has no GitHub releases. The README lists no maintainer contact or contribution guidelines beyond what is implied by the open-source LICENSE file.

The repository is licensed under the MIT license, which permits use, modification, and distribution without restriction. The README attributes the underlying concept to Geoffrey Huntley's Ralph pattern and links to an article by the repository owner on X (formerly Twitter) describing how they use Ralph in practice.

The project contains a .claude-plugin/ directory, which suggests it is intended for discovery through the Claude Code marketplace, and a flowchart/ subdirectory with source code for an interactive visualization of the loop at snarktank.github.io/ralph. The flowchart source requires npm install and npm run dev to run locally.

Editorial conclusion

Ralph is a practical utility for developers who have experienced AI coding tools running out of context partway through a multi-story feature. The loop pattern solves a specific, real problem: keeping an AI tool productive across more work than a single context window can hold. The repository's last push was on 2026-02-02, and the README does not describe a current maintainer or contribution process beyond Geoffrey Huntley's original pattern. Developers who adopt Ralph should expect to maintain their own fork if the upstream does not receive updates.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository