What Ralph Is: Turning Claude Code and Amp into a Repeatable Autonomous Development Loop

Mon, 27 Apr 2026 08:08:55 +0800

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 CLI
Claude 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.txt
prd.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:

1
2

./scripts/ralph/ralph.sh [max_iterations]
./scripts/ralph/ralph.sh --tool claude [max_iterations]

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

PRD on KnightLi Blog