My first ralph loop: what actually happens

January 28, 2026 · 3 min read

Creator of ralph-starter

I keep saying "I type one command and get a PR" and people want to know what actually happens in between. So let me walk you through a real one.

Say you want to add a dark mode toggle to your settings page. Nothing crazy, but enough to touch a few files. You run:

ralph-starter run "add dark mode toggle to settings page" --loops 5 --test --lint --commit

First thing ralph-starter does is detect your coding agent. It prefers Claude Code but works with Cursor, Codex, OpenCode too. Then it reads your AGENTS.md to find your test/lint/build commands. No guessing -- it knows how your project validates code.

Loop 1 starts. The agent gets the task with full project context, reads your files, creates the components. First pass usually gets the structure right but something breaks -- which is fine, that is the whole point of loops.

Here is what the real terminal output looked like:

$ ralph-starter run "add dark mode toggle to settings page" --loops 5 --test --lint --commit

🔄 Loop 1/5
  → Planning implementation...
  → Writing code with Claude Code...
  → Running tests... 2 passed, 1 failed
  → Test failure: ThemeContext is not exported from './contexts'

🔄 Loop 2/5
  → Fixing: adding ThemeContext export...
  → Running tests... 3 passed ✓
  → Running lint... 2 issues found

🔄 Loop 3/5
  → Fixing lint issues (unused import, missing type)...
  → Running tests... 3 passed ✓
  → Running lint... clean ✓
  → Committing changes...

✅ Done in 1m 32s | Cost: $0.29 | Tokens: 45,218

Test failure goes back as context for loop 2. Agent sees the exact error -- ThemeContext is not exported -- and fixes it. Loop 2 passes tests but lint complains about an unused import. Loop 3 cleans that up.

Three loops, about 90 seconds total. The other 2 loops never ran because the task completed early -- ralph-starter stops as soon as everything passes so you are not wasting tokens.

You also get a cost summary at the end:

Cost Summary:
  Tokens: 45K (32K in / 13K out)
  Cost: $0.29 (3 iterations)
  Cache savings: $0.12

29 cents for a feature with tests that pass and clean lint. I used to spend 20 minutes doing this exact thing by hand.

There is a circuit breaker too -- if the agent fails the same way 3 consecutive times, it stops instead of burning tokens on something that is stuck. As Ralph Wiggum would say, "I bent my Wookiee" -- sometimes you just have to stop and try a different approach.

Want to try it yourself?

npm i -g ralph-starter
ralph-starter init
ralph-starter run "your first task" --loops 3 --test

Three commands and you are in the loop. If you want to understand why I built this in the first place, I wrote about that too.

References​

References