Ralph
A bash loop that repeatedly runs an AI coding tool on one PRD story at a time until the task list is done.
- Stars
- 22.1k
- Forks
- 2.1k
- Licence
- MIT
- Language
- TypeScript
- Last update
- 9 months ago
- Type
- Dev tool
What it is
Ralph is a shell script that repeatedly launches a coding assistant (Amp or Claude Code), each time with a fresh context, to work through a list of user stories in a product requirements file. Progress is tracked through git commits, a progress.txt notes file, and a prd.json file that marks which stories pass. It is aimed at people who already have a feature plan and want an AI tool to implement it step by step.
- Turn a markdown PRD into prd.json and let Ralph implement stories on a feature branch
- Run Ralph overnight with a capped iteration count so it stops after a set number of attempts
- Use the included prd and ralph skills to generate and convert requirements for Claude Code
Great for
- Developers already using Amp or Claude Code who want to hand off a list of well-defined stories
- Teams with strong automated tests and typechecks that can catch bad AI-written code
- Projects that can be split into small, self-contained tasks
Not ideal for
- Beginners without git or a test setup, since the loop relies on commits and quality checks to be useful
- Large, vague features such as 'add authentication', which the README says should be split up first
- Anyone without an authenticated Amp or Claude Code install, since the script depends on one of them
How to get it
- 1
Clone and build from source
You'll need: One of: Amp CLI or Claude Code, installed and authenticated · jq · git · A git repository for your project
Copy ralph.sh into your project (Option 1)
mkdir -p scripts/ralph && cp /path/to/ralph/ralph.sh scripts/ralph/Copy the prompt template for Claude Code
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.mdMake the script executable
chmod +x scripts/ralph/ralph.sh - 2
Run it
- Install and authenticate Amp or Claude Code, plus jq
- Create a PRD with the prd skill and save it under tasks/
- Convert the PRD to prd.json with the ralph skill
- Run ./scripts/ralph/ralph.sh --tool claude [max_iterations] (default is 10)
- Check progress with cat progress.txt and git log
- 3
Get the most out of it
- Add your project's quality check commands to the prompt template so each story is verified before commit
- Keep AGENTS.md current, since Ralph updates it and the AI tools read it in later iterations
- Configure Amp auto-handoff (context 90) for larger stories, as described in the README
- Include 'Verify in browser using dev-browser skill' in acceptance criteria for UI stories
Downloads
Strengths
- Each iteration starts with clean context, which the README says keeps the AI focused on one story
- Progress is stored in plain files and git history, so it is easy to inspect and resume
- Supports two AI coding tools, Amp and Claude Code, selected with a command-line flag
Trade-offs
- Output quality depends heavily on the tests and typechecks in your project; the README stresses that without feedback loops it does not work well
- Relies on third-party AI tools that require their own accounts and authentication
- The README is focused on workflow and does not document failure handling or costs in detail
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.