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 (“project 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
You don’t even need the checkbox brackets if you want.
The important part is that you are going to let the AI also manage your TODO list. As it is working, it will be reading the TODOs, and writing what it has completed or discovered, and adding further TODOs.
You can optionally add extra context about larger project goals or branch goals in the PRD. You can also add text to the document to move completed items to a separate file, etc or whatever else you want also. In that sense, it can be more than just a mere TODO list, but start with a 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
Conclusion
This post might be a really obvious post for 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 a bash script like this
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, and do one task at a time, and
various other things.
Side note 1: 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.
Side note 2: the ralph github repo also uses a json format for prd.json and a
progress.txt but this stuff isn’t really needed since the plain markdown format
for the PRD.md is fine (feel free to also just call it todo.md)
Footnote 3
If this post, again, sounds obvious but you haven’t tried just giving Claude your entire todo list, try it.
You may want to spend a little bit curating your todo list before beginning. And like I said above…do ambitious things!