The “Ralph loop” is a popular workflow but nobody seems to explain it in layman’s terms.
The repo says stuff like this:
“Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.”
It references the term PRD repeatedly without ever defining it (feel free to search in their readme to see).
I’ve worked in software for many years now (ow my back) and hadn’t come across the word PRD…So wtf is it?
A PRD (“product requirements document”) is just a TODO list
Your “PRD” can just be a markdown file (e.g. PRD.md) with checkboxes like a
normal TODO list:
- Add priority column to tasks table
- Show priority badge on task cards
- Add priority selector to task edit modal
- Filter tasks by priority, persist in URL
But here is the key: you are going to let the AI both read and write your TODO list.
You be the Ralph
The Ralph concept, as originally proposed, uses an autonomous loop that keeps running to solve all the todo items.
However, you don’t have to use this to get a lot of the benefits.
Just use Claude like usual but start each session with:
read PRD.md, and continue working on tasks. update PRD.md when done
Variations
I used the TODO concept because it is dead simple, but you can also
- ask the AI to ‘whip the todo list into shape’
- say to move completed items to a separate file
- create multiple todo files, and tell agents which one to look at
- add priorities or organization to the document
- add extra branch level or project level goals to keep it on track
- tell it not to number the entries. there is often a lot of churn in this file and the numbering causes even more
- maintain multiple of these documents. you don’t need to call it ‘PRD.md’
- tell it to create architectural-decision-records for important decisions
The ceiling is whatever you want it to be.
But just starting easy with a bulleted todo list, with reading and writing, gives it a little memory to keep grinding away at your task list without you having to manually keep it fed.
Conclusion
This might be obvious to some, but I just wanted to convey that there is nothing mysterious behind the idea of the Ralph loop, and you don’t have to ‘use their repo’ to do most of what it does. Just make a TODO list and tell Claude about it.
If I’m missing something let me know. Enjoy :)
Footnote 1 - Why use this at all
I recently told myself that I need to be even more ambitious in my use of Claude for coding.
However, once you are trying to tackle very large tasks, you can end up having a lot of ongoing parallel todos. I was having some challenges keeping track of all this, and was juggling a lot of separate agent sessions.
This method helps with that. Hence, “Maximizing agentic coding”.
Footnote 2 - the Ralph loop
For reference the Ralph loop is roughly a bash script like this (the real one
uses a for loop with max iterations, but same idea)
while true ; do
OUTPUT =$( claude --dangerously-skip-permissions --print < CLAUDE.md)
if echo " $ OUTPUT " | grep -q "<promise>COMPLETE</promise>" ; then
exit 0
fi
done
So it’s a bash loop that just keeps running Claude until the literal string
<promise>COMPLETE</promise> is found in the output via grep, and then the
entire TODO list is done. The CLAUDE.md from the ralph repo (read the raw text
https://raw.githubusercontent.com/snarktank/ralph/refs/heads/main/CLAUDE.md) is
what tells it to output this special string, do one task at a time, and various
other things.
What is the <promise> tag? It is not explained in the ralph repo. It’s just an
arbitrary signal string for the grep. Could be anything as long as the agent
wouldn’t accidentally produce it in normal output.
The ralph repo also converts your markdown PRD into a prd.json (user stories
with a passes field for tracking completion) and keeps an append-only
progress.txt of learnings across iterations. For autonomous runs this gives
the loop something stable to read and write between iterations, but if you’re
just driving Claude manually you don’t need any of it. A plain PRD.md (or
todo.md) is fine.