# The Ralph loop underneath everything

The oldest loop is a bash while-loop that feeds one prompt file to an agent forever. Fresh context, one task per iteration and tests as backpressure are why it works, and having no stop condition is why it needs the rest of this course.

## The loop is almost embarrassingly small

Geoffrey Huntley published the technique on 2025-07-14 and called it Ralph. In its purest form it is a bash while-loop that pipes one prompt file into a coding agent, then does it again, forever.

```bash
while true; do
  cat PROMPT.md | <your coding agent command>
done
```

There is no orchestrator, no framework and no memory inside the process. When Nicholas Carlini built a C compiler with a team of Claudes, the base was the same: a while-true bash loop that restarts Claude Code with a prompt file.

Why study something so small? Because every command in the previous lesson is this loop with better parts. `/goal` adds a checker, `/loop` adds a clock. The shape underneath did not change.

## Three choices that make it work

**Fresh context every iteration.** Each pass starts with an empty context window. The agent does not carry a long, cluttered conversation forward, so it does not degrade as the run goes on. Whatever must survive lives on disk.

**One task per iteration.** The agent reads a prioritized plan file, picks the single most important item and does only that. Huntley treats the plan file as disposable: when it drifts, regenerate it. Specs live as separate files that are read on every pass, and a short file records how to build and run the project.

**Backpressure.** Huntley's word for everything that pushes back on bad output: tests, builds, type checkers, analyzers. They reject wrong work so the loop can move fast and still stay correct. He runs only the tests for the touched unit, and the prompt forbids placeholder implementations, which closes the easy way out.

```flow loop
Read the prompt, the specs and the plan
Pick the single most important task
Implement it
Backpressure: tests, build, type check
Commit if green, then start over empty
```

**Question:** Why does the Ralph loop start every iteration with a fresh context window?

- To save disk space
- So the agent does not drag a cluttered conversation forward, and state lives in files instead
- Because the agent cannot read files
- To make each iteration cheaper than the last

**Answer:** So the agent does not drag a cluttered conversation forward, and state lives in files instead. A fresh window avoids the decay of a long conversation. Anything that has to survive is written to disk: the plan, the specs and the commits.


## How it behaves in practice

Huntley's agent acts as a scheduler. Expensive work, such as searching the code or summarizing test output, goes to sub-agents, and he caps how many build and test sub-agents run in parallel. When Ralph does something wrong he does not argue with it. He adds a sign to the prompt, a short instruction that prevents that mistake next time. That is tuning, not conversation.

When a run goes off track he has two exits: regenerate the plan, or reset with git and restart. Git tags on green builds give him known good points to return to.

> **One testimonial, not a benchmark**
Huntley's page includes a contractor's report of a 50,000 USD contract delivered for 297 USD. It is a single story told on his own page. Treat it as a reason to be curious, not as a measurement.


## The known weakness

Ralph has no formal stop condition. It runs until the TODO list is empty or it goes off track, and a person is the one who notices. That is acceptable when you are sitting next to it. It is dangerous when nobody is.

Carlini's run shows what lives in that gap. New features broke old ones, so he added CI. All the agents got stuck on the same bug. One agent killed its own loop with `pkill`. These are the ordinary failures of a loop that has backpressure but no supervisor.

Loop engineering is the answer to that gap, and the answer is not a smarter model. It is the same shape plus the parts Ralph leaves out: a checker the agent cannot talk its way past, a stop condition written as evidence, a hard cap, and a rule for what to do when the same check keeps failing. The next three lessons add them one at a time.

> **Write the smallest Ralph on paper**
Do not run it yet. Write the three files it would need: the prompt, a plan with five items, and a one-line description of how to run your tests. Then write down what would stop it. If the answer is that you would watch and press Ctrl+C, you have found the weakness yourself.


**Question:** What is the known weakness of the plain Ralph loop?

- It cannot run tests
- It has no formal stop condition, so a person has to notice when it is done or off track
- It only works with one file
- It always costs more than a single prompt

**Answer:** It has no formal stop condition, so a person has to notice when it is done or off track. Ralph runs until the TODO list is empty or it goes off track. Without a stop condition and a cap, nothing ends a loop that cannot succeed.