If you have been paying attention to long-running coding agent workflows lately, snarktank/ralph is a project worth a close look. It is not another model wrapper or another chat UI. Instead, it organizes Claude Code or Amp into an autonomous loop that keeps running through stories in a PRD until everything is done.
Its core idea is simple: do not force the same agent to keep working inside an increasingly long and messy context. Start a brand-new AI coding session for every iteration instead. That keeps context from bloating and makes task boundaries much clearer.
01 What Ralph Is
Ralph describes itself very clearly: it is an autonomous AI agent loop that repeatedly runs an AI coding tool until the items in a PRD are complete.
The repository currently supports two tools:
Amp CLIClaude Code
Each iteration starts a fresh instance. In other words, it does not depend on one endlessly extended conversation. Instead, it keeps memory in external state:
- git history
progress.txtprd.json
That detail matters a lot. When people let an agent run on large tasks, the main problem is often not that the model cannot code. It is that the session becomes heavier over time, starts losing context, forgets requirements, and repeats work. Ralph is designed almost entirely around that problem.
02 How It Works
Ralph’s workflow has three steps.
1. Write a PRD first
The README suggests starting with the bundled prd skill to generate a requirements document and break the feature into smaller stories.
2. Convert the PRD into prd.json
Then the ralph skill converts the Markdown PRD into a structured prd.json. That file stores the user stories and whether each one has passed.
3. Run the loop script
The actual execution is handled by ralph.sh. The commands look like this:
|
|
The default is 10 iterations. In each round, Ralph roughly does the following:
- Create a branch from
branchName - Pick the highest-priority story where
passes: false - Implement only that story
- Run quality checks such as typecheck and tests
- Commit if the checks pass
- Update
prd.json - Append learnings to
progress.txt - Continue to the next round
So Ralph is not trying to finish everything in one go. It compresses work into many small loops that can fit inside a single context window.
03 What Makes Ralph Interesting
1. Every round uses fresh context
This is Ralph’s defining design choice. The README emphasizes that every iteration is a brand-new AI instance, and cross-iteration memory lives only in git, progress.txt, and prd.json.
That is very different from the common pattern of keeping Claude Code or another tool inside one long conversation. Once tasks get larger, that approach often slows down under its own history and gradually loses focus. Ralph accepts that no single round should remember everything, then moves memory into files instead.
2. It forces tasks to stay small
The docs explicitly say that each PRD item must be small enough to finish within one context window. Tasks like adding a filter, updating a server action, or adding a database column are about the right size. Tasks like rebuilding the whole API or creating an entire dashboard are too large.
That constraint is practical. Many autonomous agent loops fail not because the loop is bad, but because the task slicing is too coarse and each round carries too much at once.
3. It preserves learnings, not just code
Beyond progress.txt, the README also stresses updating AGENTS.md. The reason is straightforward: future iterations and future developers will read those notes, so patterns, gotchas, and conventions discovered in each round should be written down in the project itself.
Put differently, Ralph is not only trying to keep an agent coding continuously. It is also trying to help the agent build working memory about the codebase over time.
04 When It Fits Best
Ralph is a good fit when your task looks like this:
- It can already be broken into a clear set of user stories
- The codebase has reliable feedback loops such as tests, typecheck, or CI
- You want the agent to keep moving forward without putting everything into one long conversation
- You are fine with iterative progress instead of demanding a one-shot completion
On the other hand, if the requirement is still vague, or the work depends on frequent discussion and constant changes of direction, Ralph may not be the first thing to reach for. It fits better once the requirements are already shaped and execution needs to be steady.
05 How It Differs from Normal Claude Code Usage
With plain Claude Code, the usual pattern is simple: open a session and let it keep reading code, editing files, and running commands. That works very well for small and medium tasks, but larger tasks often hit two problems:
- Context keeps growing
- Intermediate decisions are harder to preserve in a structured way
Ralph turns Claude Code or Amp into something closer to a batch executor:
- The task source is
prd.json, not ad hoc chat instructions - Each iteration recognizes only one story
- Completion state is written back to files
- Learnings go into
progress.txt - Code changes are preserved in git
So in practice, it feels less like a new AI assistant and more like an iteration controller added on top of a coding agent.
06 One Important Requirement
Whether Ralph works well depends less on the loop itself and more on the quality of your feedback loops. The README says this very directly: without typecheck, tests, and CI, errors will compound across later iterations.
For frontend tasks, the repository even recommends adding browser verification to the acceptance criteria. Without real verification, an agent can easily confuse “it looks done” with “it actually works.”
That point is important. Ralph is not magical automation. It is more like a force multiplier for the engineering discipline you already have. If your project already has clear task breakdowns and reliable checks, Ralph becomes much more useful. If those foundations are missing, the loop will only repeat the confusion.
07 One-Sentence Summary
What makes Ralph worth studying is not that it introduces a huge amount of new infrastructure. It takes a simple but useful idea and turns it into a practical workflow: let Claude Code or Amp handle one small story per round, keep focus with fresh context, and preserve continuity through git, prd.json, and progress.txt.
If you are already using coding agents in real projects and keep getting stuck on how to push long tasks forward reliably, Ralph’s approach is well worth borrowing.
References
- GitHub repository: https://github.com/snarktank/ralph
- Interactive flowchart: https://snarktank.github.io