Everyone is raving about Ralph. What is it?

Ralph is an autonomous AI coding loop that ships features while you sleep.

Created by @GeoffreyHuntley and announced in his original post, it runs @AmpCode (or your agent of choice) repeatedly until all tasks are complete.

Each iteration is a fresh context window (keeping Threads nice and small). Memory persists via git history and text files.

I ran it for the first time and shipped a feature last night. I love it.

How It Works

(Here's a complete GitHub repo for you to download and try.)

A bash loop that:

Pipes a prompt into your AI agent

Agent picks the next story from prd.json

Agent implements it

Agent runs typecheck + tests

Agent commits if passing

Agent marks story done

Agent logs learnings

Loop repeats until done

Memory persists only through:

Git commits

progress.txt (learnings)

prd.json (task status)

File Structure

ralph.sh

The loop:

Make executable:

Other agents:

Claude Code: `claude --dangerously-skip-permissions`

prompt.md

Instructions for each iteration:

prd.json

Your task list:

Key fields:

`branchName` — branch to use

`priority` — lower = first

`passes` — set true when done

progress.txt

Start with context:

Ralph appends after each story.

Patterns accumulate across iterations.

Running Ralph

Runs up to 25 iterations.

Ralph will:

Create the feature branch

Complete stories one by one

Commit after each

Stop when all pass

Critical Success Factors

1. Small Stories

Must fit in one context window.

2. Feedback Loops

Ralph needs fast feedback:

`npm run typecheck`

`npm test`

Without these, broken code compounds.

3. Explicit Criteria

4. Learnings Compound

By story 10, Ralph knows patterns from stories 1-9.

Two places for learnings:

progress.txt — session memory for Ralph iterations

AGENTS.md — permanent docs for humans and future agents

Before committing, Ralph updates AGENTS.md files in directories with edited files if it discovered reusable patterns (gotchas, conventions, dependencies).

5. AGENTS.md Updates

Ralph updates AGENTS.md when it learns something worth preserving:

6. Browser Testing

For UI changes, use the dev-browser skill by @sawyerhood. Load it with `Load the dev-browser skill`, then:

Not complete until verified with screenshot.

Common Gotchas

Idempotent migrations:

Interactive prompts:

Schema changes:

After editing schema, check:

Server actions

UI components

API routes

Fixing related files is OK:

If typecheck requires other changes, make them. Not scope creep.

Monitoring

Real Results

We built an evaluation system:

13 user stories

~15 iterations

2-5 min each

~1 hour total

Learnings compound. By story 10, Ralph knew our patterns.

When NOT to Use

Exploratory work

Major refactors without criteria

Security-critical code

Anything needing human review

For a great video walkthrough of how to use Ralph, checkout the video from @mattpocockuk ...