Why AI Coding Assistants Quit Early and How Ralph Loop Keeps Them Working

Problem

Developers using AI coding assistants face four common problems: the model stops early because it thinks the job is “good enough”, single‑prompt tasks break on complex problems, re‑prompting requires manual effort, and context is lost after a session restart. These stem from the LLM’s unreliable self‑assessment.

Ralph Loop

Ralph Loop (also called Ralph Wiggum Loop) is a minimal persistent‑agent pattern that repeatedly feeds the same prompt to the model while external state (files, test results, Git history) records progress. A Stop Hook intercepts any attempt by the model to exit before a machine‑verifiable completion promise is emitted and re‑injects the original prompt.

Key components

Explicit task and completion criteria – define a testable goal (e.g., all tests pass, coverage > 80 %).

Stop Hook – a script (e.g., hooks/stop-hook.sh) that scans the model output for a token such as <promise>COMPLETE</promise> and forces another iteration if it is missing.

Safety valve – a maximum‑iteration limit to avoid infinite loops.

Typical project layout

scripts/ralph/
├── ralph.sh
├── prompt.md
├── prd.json
└── progress.txt

prd.json

holds a structured backlog of user stories (id, title, acceptanceCriteria, priority, passes). progress.txt is an append‑only log of each iteration’s actions and learned patterns, enabling the agent to resume from a known state.

Running Ralph

# Install the Claude Code plugin
/plugin install ralph-wiggum@claude-plugins-official

# Execute the loop (example: 25 iterations)
ralph-loop "Add unit tests" \
  --completion-promise "<promise>COMPLETE</promise>" \
  --max-iterations 25

During each cycle Ralph reads progress.txt and prd.json, selects the highest‑priority unfinished story, implements it, runs type‑checking, linting and tests, then commits the change. When the completion promise is detected the loop exits gracefully.

Why it works better than traditional agent loops

Conventional agents follow an Observe → Reason → Act (ReAct) or a static plan‑and‑execute sequence, both of which rely on the model’s internal judgment to stop. Ralph externalizes the stop condition, so the loop continues until an objective, machine‑verifiable condition is satisfied, eliminating premature termination and context rot.

Comparison

Standard loops are flexible but can quit early when the model mis‑evaluates.

Ralph Loop is a “refine‑until‑done” pattern that guarantees progress as long as external verification succeeds.

Best‑practice checklist

Define clear, machine‑verifiable completion criteria (tests passing, coverage thresholds, specific output tokens).

Set a reasonable --max-iterations limit to bound cost.

Keep progress.txt organized: reusable code‑base patterns at the top, then per‑iteration logs.

Process one story per iteration and commit immediately to maintain a clean Git history.

Prioritize high‑risk tasks (architectural decisions, integration points) before low‑risk polish.

Run the loop inside a Docker sandbox (e.g., docker sandbox run claude) for AFK execution.

Monitor token usage and set iteration caps; typical costs with Claude 3.5 Sonnet are $5‑15 for small tasks, $50‑150 for larger ones.

Typical use cases

Test‑driven development where the loop stops only when all tests pass.

Greenfield projects with well‑defined acceptance criteria.

Automated migration (e.g., Jest → Vitest) where success can be verified by linting and test results.

Code‑base refactoring, duplicate‑code removal, or entropy‑reduction loops.

Limitations

Ralph is unsuitable for tasks that require subjective judgment or lack an objective success metric. It also requires careful definition of completion promises to avoid infinite loops.

Conclusion

Ralph Loop provides a repeatable paradigm for AI‑assisted development by forcing the model to iterate until an explicit, verifiable goal is reached. By externalizing the stop condition with a Stop Hook and persisting state in the file system and Git history, it overcomes the “half‑way” failures of traditional AI coding assistants and enables reliable unattended automation for well‑scoped development tasks.

Relevant resources:

https://github.com/langchain-ai/deepagents/tree/master/examples/ralph

https://github.com/vercel-labs/ralph-loop-agent

https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md