Understanding ralph

The “Ralph” loop, created by Geoffrey Huntley took off in the AI Developer community in January 2026. These are my notes to try and understand how ralph works and why it is useful for long running AI tasks.

A summary:

• The ralph loop is a way to mitigate context rot in coding agents
• Instead of complex orchestration or context management strategies, it just executes the same prompt over and over
• This makes ralph more amenable to long range tasks that might take hours to complete.

Ralph basics

The simplest version of ralph is a loop, that submits a prompt, to an agent infinitely: while :; do cat PROMPT.md | claude; done

Let’s break this down into the loop, agent, and prompt

The while :; do ... ; done is shell syntax to create an infinite loop. The ... will be run over and over again, until the process is stopped.

Here, claude code is being used as the agent but it could be any coding agent that you can send a prompt to via a CLI.

Finally we have PROMPT.md which is the instructions the agent is actually passed. Note, this is the same prompt every time. We’ll come back to the prompt in a moment.

Let’s talk about the prompt

The loop and agent part of ralph are technically straightforward. Things get more interesting when we talk about the prompt.

The “prompt” in the ralph loop is actually two prompts: the PROMPT.md that is actually passed to the agent and a “plan” (some people call it PRD if they come from a PM background) that is referenced in the PROMPT.md file.

The specifics of the PROMPT.md will vary, but generally it instructs the agent to review the plan, select an item to work on, and finish that one item. When all items are completed, the agent is instructed to output some “completion marker” that can be used to stop the loop. There are also usually instructions to write progress to a file and save useful commands or architectural decisions for future reference.

Instead of some complex multi agent orchestrator, ralph effectively tells the agent to keep working on the plan until it finishes everything, then output some marker that it’s done.

ralph is like allocating a stack frame

Conceptually, each iteration of the ralph loop is like allocating a function call stack. The prompt serves as the instructions for the function with the plan and progress files serving as external state.

Based on the loop, the stack doesn’t get very deep since generally you instruct the agent to do one thing at a time.

Why is this interesting?

If you’ve used coding agents before, this might sound a bit like a “plan mode” or the “TODO_READ” and “TODO_WRITE” tools many agents support. In those setups, the agent breaks down a task and completes them one by one. So what is different about the ralph loop?

The issue you run into with the agent driven plans is that all the work stays in the same context window. This means the work to add say a UI component and an API call for a CRUD app will all fill up the same context window which will degrade performance.

There’s all kinds of clever strategies for compaction and prompt rewriting that you could use to solve this problem. The ralph loop sidesteps these approaches, it just starts with a brand new context every time. The prompt, plan, and progress files do take up context but much less than the actual work that happens when an agent writes code for example searching for tests, or running commands and interpreting outputs.

The end result is you can give agents much more complex pieces of work that can you for several hours or even days instead of being managed by a user in a single terminal.

What else could you do?

Ralph probably isn’t the end of agent “orchestration” techniques. So what are some possibilities to improve on it or change the implementation:

• You could probably do this natively with subagents that use a forked context. For example, each task would be dispatched to a single subagent with a fresh context window and then the subagent writes to a progress file
• Alternative plan sources, ralph doesn’t have to use the file system tasks could come from jira

The meta ralph is probably the most interesting modification. The idea of “reviewing a plan”, “work on it”, and “check the results” is pretty general. It’s basically the core of most agents, ralph is cleverly sidestepping some context issues. So, why couldn’t you run multiple ralphs at multiple levels of abstraction? One ralph can create the plan for an entire product that get fanned out to other ralphs for features until the work is complete. You can also have ralph loops with differing goals. You could have a ralph loop that calls another ralph loop to validate its output for example. Then the call stack does start to get pretty deep. It also introduces paralllelism which would need some flow control to integrate changes. But this can all happen in a single orchestrator.

This is when you starting getting into systems like gastown and more complex task tracker like beads.

Other things I didn’t cover

The original ralph post from Huntley goes into a lot more detail around things like back pressure and completion promises. These are used to let ralph exit as well as determine if work is complete