Skip to content
Get packs

Guide · Open source

How to use Ralph: set up, run the loop and track progress

Updated · written with AI from the project's own documentation and checked against our catalogue data

Ralph is an open-source autonomous AI agent loop, written as a shell script, that repeatedly launches Amp or Claude Code to work through the user stories in a product requirements file until they are all complete. It is aimed at developers who already have a feature plan and want an AI tool to implement it one small story at a time. After this guide you will know what to install, how to set up the script in a project, and how to run a loop and check its progress.

Ralphsnarktank/ralph · ★ 22.1k · MIT

Quick start

  1. 1Install prerequisites. Install Amp CLI or Claude Code, authenticate it, install jq, and make sure your project is a git repository.
  2. 2Copy the script. Create scripts/ralph in your project and copy ralph.sh and the matching prompt template into it.
  3. 3Make the script executable. Run chmod +x on scripts/ralph/ralph.sh.
  4. 4Create a PRD. Ask the PRD skill to write a requirements document, which is saved to tasks/prd-[feature-name].md.
  5. 5Convert to prd.json. Ask the Ralph skill to convert the PRD into prd.json with user stories that have passes status.
  6. 6Run the loop. Start ralph.sh with Amp by default or --tool claude, and optionally set a maximum number of iterations.
  7. 7Review the results. Check prd.json, progress.txt and git log to see what was completed and learned.

Check the prerequisites before you start

Ralph needs one of two AI coding tools installed and authenticated: Amp CLI (the default) or Claude Code. It also needs jq and a git repository for your project. The README suggests installing Claude Code with npm and jq with brew on macOS.

  • Amp CLI or Claude Code, installed and authenticated
  • jq installed (brew install jq on macOS)
  • A git repository for your project
npm install -g @anthropic-ai/claude-code brew install jq

Copy Ralph into your project

The simplest setup is to copy the script and a prompt template into a scripts/ralph folder in your project. Run these from your project root, replacing /path/to/ralph with wherever you cloned the repository. Use prompt.md for Amp or CLAUDE.md for Claude Code.

  • ralph.sh is the bash loop that starts fresh AI instances
  • prompt.md is the prompt template for Amp
  • CLAUDE.md is the prompt template for Claude Code
mkdir -p scripts/ralph cp /path/to/ralph/ralph.sh scripts/ralph/ cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md chmod +x scripts/ralph/ralph.sh

Write a PRD and convert it to prd.json

Ralph works from a list of small stories. The README describes a PRD skill that generates a requirements document, saved to tasks/prd-[feature-name].md, and a Ralph skill that converts that markdown into prd.json. The PRD skill is triggered by asking to create a PRD, and the Ralph skill is used to convert it.

Keep each story small enough to finish in one context window. The README gives examples such as adding a database column and migration, or adding a filter dropdown to a list. It says to split large items such as 'Add authentication' or 'Build the entire dashboard'.

  • Right-sized: add a UI component to an existing page
  • Too big: refactor the API (split it first)
Load the prd skill and create a PRD for [your feature description] Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

Run the loop

Run the script with Amp by default, or pass --tool claude to use Claude Code. The optional argument sets the maximum number of iterations, which defaults to 10.

On each iteration Ralph creates a feature branch from the PRD branchName, picks the highest priority story where passes is false, implements it, runs quality checks, commits if they pass, marks the story as passing, and appends learnings to progress.txt. It stops when all stories pass or the iteration limit is reached.

  • Amp (default): ./scripts/ralph/ralph.sh [max_iterations]
  • Claude Code: ./scripts/ralph/ralph.sh --tool claude [max_iterations]
./scripts/ralph/ralph.sh [max_iterations] ./scripts/ralph/ralph.sh --tool claude [max_iterations]

Check progress and understand the memory model

Each iteration starts a new AI instance with clean context. The only memory carried between iterations is git history, progress.txt, and prd.json. You can inspect all three from the terminal to see which stories are done and what was learned.

Ralph only works well with feedback loops: a typecheck, tests, and a green CI. The README notes that broken code compounds across iterations. Frontend stories should include the acceptance criterion 'Verify in browser using dev-browser skill'.

  • Stories done: cat prd.json | jq '.userStories[] | {id, title, passes}'
  • Learnings: cat progress.txt
  • History: git log --oneline -10
cat prd.json | jq '.userStories[] | {id, title, passes}' cat progress.txt git log --oneline -10

What people use it for

  • Implementing a feature plan split into small stories, such as a new database column followed by a UI filter
  • Letting an AI tool work through a backlog of well-defined tasks in a project that has strong tests and typechecks
  • Running the same loop with Claude Code instead of Amp by passing --tool claude
  • Building up AGENTS.md notes about a codebase's patterns and gotchas across iterations

Frequently asked questions

Is Ralph free to use?

Ralph is released under the MIT licence, as stated in the repository. The AI tools it runs, Amp CLI and Claude Code, need their own installation and authentication, so check their terms for any costs.

What do I need to install to use Ralph?

You need Amp CLI or Claude Code installed and authenticated, jq, and a git repository for your project. The README shows npm install -g @anthropic-ai/claude-code for Claude Code and brew install jq on macOS.

Can I use Ralph without git?

The source says Ralph is not for beginners without git or a test setup, because the loop relies on commits and quality checks to be useful. A git repository is listed as a prerequisite.

Does Ralph work with Claude Code as well as Amp?

Yes. Amp is the default, and you can select Claude Code by running ralph.sh with --tool claude. Copy CLAUDE.md into your project for Claude Code, or prompt.md for Amp.

How do I stop Ralph or know when it is finished?

Ralph stops when all stories have passes set to true, or when the maximum number of iterations is reached. When everything passes, it outputs <promise>COMPLETE</promise> and the loop exits.

Why does Ralph need small user stories?

Each iteration has a fresh context window. If a story is too big, the LLM can run out of context before finishing and produce poor code, so the README says to split large features such as authentication.

How is Ralph different from other tools?

The source lists no comparable projects. It is a shell script that loops over a PRD using Amp or Claude Code, so it is best judged against your own needs rather than a benchmark.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Ralph suits developers who already use Amp or Claude Code, have a well-split feature plan, and have tests and typechecks that can catch bad AI-written code. If you lack git, automated checks, or a clear list of small stories, it is not a good starting point, and you should first build those foundations or choose a more guided tool.

Install options & downloads