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
But here is the key: you are going to let the AI to 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
Further tweaks to the TODO list concept
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’
The ceiling is whatever you want it to be
But just starting easy with a bulleted todo list, with read 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 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!