snarktank/ralph

What it does

Ralph wraps an AI coding CLI (Amp by default, or Claude Code) in a bash loop. You give it a PRD converted to prd.json, and it spawns a fresh agent instance per iteration to implement one story, run typecheck and tests, commit if they pass, flip that story to passes: true, and append notes to progress.txt. The loop exits when every story passes or the iteration cap is hit. The approach derives from Geoffrey Huntley's Ralph pattern.

Memory is intentionally thin: each iteration starts with clean context, and continuity comes only from git history, progress.txt, and prd.json. Ralph also updates relevant AGENTS.md files with conventions and gotchas discovered during work.

Quick start

Prerequisites: an authenticated Amp CLI or Claude Code, jq, and a git repository.

1. Copy the loop and prompt into your project:

mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # Amp
# or: cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh

2. Generate a PRD with the /prd skill, then convert it with /ralph into prd.json. Options 2 and 3 in the README cover installing the skills globally for Amp/Claude Code or adding the Claude Code marketplace.

3. Run the loop from the project root:

./scripts/ralph/ralph.sh 20              # default tool: Amp, 20 iterations
./scripts/ralph/ralph.sh --tool claude 20

When all stories are passes: true, the script prints <promise>COMPLETE</promise> and stops. Debug with cat prd.json | jq '.userStories[] | {id, title, passes}', cat progress.txt, and git log --oneline -10.

For Amp, the README recommends enabling auto-handoff in ~/.config/amp/settings.json with "amp.experimental.autoHandoff": { "context": 90 }.

Constraints

• Stories must be small enough to finish in one context window; oversized items ("build the entire dashboard", "add authentication") degrade output.
• The loop relies on real feedback: typecheck and tests must run and CI must stay green, since broken code compounds across iterations.
• UI stories need browser verification in their acceptance criteria; the README assumes a dev-browser skill.
• Each run creates a branch from the PRD's branchName; starting a feature with a different branch archives the previous run under archive/YYYY-MM-DD-feature-name/.
• Requires jq, a git repo, and an authenticated Amp or Claude Code installation. Licensed under MIT.

HotRepo's take

The project recorded 22,155 stars and 2,098 forks on 2026-11-08, gaining 17 stars that day and reaching position 10 on the TypeScript daily list. Only one snapshot is available, so that ranking is a single-day observation, not evidence of a sustained trend. The interesting design choice is the fresh-context loop: instead of one long session, Ralph turns PRD backlog management and git commits into the persistence layer, which fits teams already using Amp or Claude Code and willing to keep stories small and tests green.