Ralph Loop: Running Claude Code Autonomously for Hours

Most Claude Code sessions are interactive. You type a prompt, Claude works on it, you review the result, you prompt again. It's a conversation. A productive one, sure, but a conversation nonetheless. You're in the loop. Your attention is required at every step.

Ralph Loop flips this entirely.

You give Claude a task and a completion signal. It works. When it thinks it's done and tries to stop, a hook catches it, checks whether the work is actually complete, and if not, sends it back. No human in the loop. No review between iterations. Claude keeps working autonomously until the job is done or the safety limits kick in.

The name comes from the "Ralph Wiggum technique," a community-coined term for a bash loop that re-feeds prompts to Claude Code. The idea is simple enough that it sounds like a joke. The results are not a joke at all.

How It Works

At its core, Ralph Loop is a Stop hook. Claude Code supports lifecycle hooks that fire at specific points during a session. The Stop hook fires when Claude tries to exit, when it thinks the task is complete. Ralph Loop intercepts that exit and decides whether to let Claude stop or send it back to work.

Here is what the flow looks like in practice. You start a session with something like:

Copy/ralph-loop "implement the full authentication system" --max-iterations 10 --completion-promise "DONE"

Claude reads the prompt, reads your codebase, and starts working. It implements what it can in a single session. When it reaches a natural stopping point and tries to exit, the Stop hook intercepts.

The hook checks two things. First: did Claude output the completion marker, the "DONE" string you specified? Second: does the actual work look complete? This dual-condition gate is the key insight. You need both indicators to pass before Claude is allowed to stop.

Why two conditions? Because Claude is polite. It will say "DONE" even when the work isn't finished, because it thinks you want to review the progress. And conversely, sometimes the work is technically complete but Claude didn't output the marker because it got distracted by a tangential issue. The dual gate catches both failure modes.

If either condition fails, the hook re-feeds the original prompt to Claude with updated context. Crucially, this isn't a blank slate restart. Claude sees the modified files and git history from its previous iterations. It picks up where it left off. Each iteration builds on the last.

The mechanism is conceptually simple:

1. Claude receives the task and works on it
2. Claude tries to exit
3. The Stop hook intercepts and evaluates completion
4. If not complete, the prompt is re-fed with current codebase state
5. Claude sees its own previous changes and continues
6. Repeat until both completion conditions are met or limits are hit

That's it. There's no orchestration framework, no complex state machine, no multi-agent architecture. It's a loop. The power comes from the fact that Claude Code is already an autonomous agent with full tool access. You're just removing the human bottleneck between iterations.

The Safety Mechanisms

I can hear the alarm bells. "You're letting an AI run unsupervised on your codebase for hours?" Yes. But not without guardrails.

Rate limiting. Ralph Loop enforces a configurable API call limit per hour. The default is 100. This prevents runaway sessions that burn through your API credits at an alarming rate. If the limit is hit, the loop pauses and waits rather than terminating, so you don't lose progress.

Circuit breaker. The loop monitors Claude's output for error patterns. If Claude hits the same error three times in a row, or if it's making edits and then immediately reverting them, or if it's reading the same files over and over without making progress, the circuit breaker fires and halts the loop. This is the "going in circles" detector, and it's essential.

Max iterations. You set a hard cap on how many times the loop can cycle. Ten iterations is a reasonable default for most tasks. Some people push it to 50 for massive migrations. I've never needed more than 15.

The dual-condition gate. This isn't just a completion check. It's also an infinite loop prevention mechanism. If Claude keeps outputting "DONE" without the work being complete, the hook can detect the discrepancy and halt. If Claude keeps working without ever claiming completion, the max iterations cap catches it.

Git as a safety net. Every iteration's changes are visible in your git working tree. If something goes catastrophically wrong, you git checkout . and you're back to where you started. I always run Ralph Loop from a clean git state for exactly this reason.

These aren't theoretical safeguards. I've hit every single one of them. The circuit breaker is the one that's saved me the most money. Without it, a poorly specified task can loop for hours, burning tokens while making zero progress.

When It Works Well

Ralph Loop shines on tasks with three properties: a clear completion criteria, incremental progress, and each iteration naturally building on the last.

Implementing a full feature from a spec. This is the canonical use case. You have a design doc or a detailed spec. The feature touches multiple files, needs tests, needs integration. You feed the spec to Ralph Loop and let it work. Each iteration implements more of the spec. The completion condition is "all endpoints implemented, all tests passing, no TypeScript errors."

I used this to build an entire authentication system for a side project. OAuth flow, JWT handling, middleware, route protection, the works. The spec was detailed. I set max iterations to 12. Claude finished in 8 iterations over about 90 minutes. I reviewed the final result, made two small adjustments, and shipped it. That would have been a full day of interactive back-and-forth.

Migrating a codebase from one pattern to another. Moving from CSS modules to Tailwind across 40 components. Converting class components to functional ones. Migrating from REST to GraphQL. These tasks are repetitive, well-defined, and incremental. Perfect for Ralph Loop. Each iteration migrates a few more files. The completion condition is "no remaining files using the old pattern."

Writing comprehensive test coverage. "Write tests for every exported function in the /utils directory. Target 90% coverage. Don't stop until npm run test:coverage shows 90% or higher." Claude iterates, writing tests, running coverage, finding gaps, writing more tests. The coverage number is a clean, measurable completion condition.

Building out a series of similar components. If you have a component library and need 20 variations of a card component, or 15 form field types, or a set of data visualization widgets that follow the same pattern, Ralph Loop handles this well. The first iteration establishes the pattern. Subsequent iterations replicate it with variations.

The common thread: well-defined goal, measurable progress, each iteration builds on the last. If your task has these properties, Ralph Loop is probably the fastest way to get it done.

When It's a Terrible Idea

Ralph Loop amplifies both good and bad decisions. When it's working on a well-scoped task, each iteration compounds progress. When the task is poorly scoped, each iteration compounds mistakes. There's no human in the loop to catch the drift.

Architectural decisions. "Should we use Redux or Zustand?" is not a Ralph Loop task. It requires judgment, tradeoff analysis, understanding of the team's preferences, and context that Claude doesn't have. If you Ralph Loop a prompt like "refactor state management," Claude will pick an approach and commit to it. If that approach is wrong, you get 10 iterations of committed effort in the wrong direction.

Design work. Anything with subjective quality criteria is dangerous. "Make the landing page look better" will produce results, but whether those results are actually better requires a human eye. Claude will iterate confidently, making changes that it thinks are improvements. Without someone checking, it can drift into aesthetic territory that's technically different but not actually better. Or worse.

Debugging novel issues. This one surprised me. You'd think "find and fix this bug" is well-defined enough. But novel bugs require hypothesis generation and testing, and Claude can latch onto a wrong hypothesis and spend ten iterations trying to make it work. I've watched a Ralph Loop session spend 40 minutes trying to fix a race condition by adding increasingly complex locks, when the actual fix was a one-line change to the event ordering. Interactive debugging, where you can redirect Claude's attention, is almost always better.

Ambiguous requirements. If the task description contains "maybe," "something like," "figure out," or "whatever makes sense," don't Ralph Loop it. Claude will interpret the ambiguity in one direction and commit to it. You might not agree with that interpretation. By the time you review the output, you've got ten iterations of work built on an assumption you never validated.

The heuristic I use: if I'd want to review the output after every step in interactive mode, Ralph Loop is wrong for this task. If I'd rubber-stamp the intermediate steps and just want to see the final result, Ralph Loop is right.

Real Examples

The most famous Ralph Loop story is Geoffrey Huntley's. He ran a loop for roughly three months that built an entire programming language. Not a toy language. A real one with a compiler, standard library, and documentation. The loop ran autonomously, committing code, running tests, fixing failures, and iterating. The total token cost was significant, but the output was a project that would have taken a small team months.

That's the extreme end. More practically relevant are the YC hackathon teams that used Ralph Loop to ship products overnight. Multiple teams at a YC batch hackathon ran autonomous loops on separate repos simultaneously. They'd define the specs in the evening, start the loops, go to sleep, and wake up to working applications. One team shipped six repos overnight for about $297 in API costs. That's not a typo. Six working repositories, built autonomously, for less than the cost of a nice dinner in San Francisco.

But I should be honest about the failures too, because they're instructive.

I once Ralph Looped a prompt to "refactor the data layer to be more modular." That's too vague. Claude spent 8 iterations reorganizing files, creating abstractions, removing those abstractions, creating different abstractions. The circuit breaker eventually fired after detecting the back-and-forth pattern. I'd burned about $50 in API costs and the codebase was worse than when I started. git checkout . was my best friend that day.

Another time, I used Ralph Loop for a database migration that involved schema changes. Claude handled the migration files fine but didn't account for the seed data that depended on the old schema. Each iteration ran the migrations, saw the seed failures, tried to fix the seeds, which broke something else, which it tried to fix, and so on. The task was well-defined in my head but the prompt didn't mention the seed data dependency. Claude couldn't know what I hadn't told it.

The lesson from both failures: the quality of the output is directly proportional to the precision of the input. Ralph Loop doesn't make Claude smarter. It makes Claude more persistent. If the direction is wrong, persistence is a liability.

The Trust Spectrum

Every interaction with Claude Code sits on a spectrum of human involvement. On one end, you're dictating every keystroke, using Claude as a fancy autocomplete. On the other end, you've handed over the keys entirely and Claude is running autonomously for hours.

Here's how I think about it:

Autocomplete mode (Copilot-style): you're driving, AI suggests. Maximum human control, minimum AI leverage. Fine for small edits.

Interactive mode (standard Claude Code): you prompt, Claude works, you review, you prompt again. This is where most work belongs. The human feedback loop catches mistakes early. Each prompt can redirect based on what Claude did in the previous step.

Plan mode: Claude explores and proposes before acting. Slightly more trust. You're letting Claude think independently but reviewing before execution. I covered this in detail in the plan mode post. It's the sweet spot for complex tasks.

Ralph Loop: Claude works autonomously with no human review between iterations. Maximum AI leverage, minimum human control. Only appropriate when the task is precisely defined and the completion criteria are measurable.

Most developers I talk to are stuck between autocomplete and interactive. They're leaving enormous leverage on the table by not using plan mode. And they're right to be cautious about Ralph Loop, because most tasks genuinely don't belong there.

My split is roughly 60% interactive, 25% plan mode, 10% Ralph Loop, and 5% things that are too small to even categorize. Your split will be different. The point isn't the numbers. The point is that knowing which mode fits which task is one of the most important skills in working with Claude Code.

Don't use Ralph Loop because it's cool. Use it because the task demands it.

Practical Tips If You Try It

A few things I've learned from running Ralph Loop on real projects.

Always start from a clean git state. Commit or stash everything before starting a loop. You want a clean rollback point. This isn't optional.

Write the prompt like a spec, not a conversation. Ralph Loop prompts should read like technical specifications. What exactly needs to be built. What the completion criteria are. What files are in scope. What's out of scope. The more precise the prompt, the better the output.

Set conservative iteration limits first. Start with 5 iterations, not 50. Run it, review the output, understand the pattern. Then increase if the trajectory is good. I've seen people set max iterations to 100 on their first try and wonder why they burned $200 on nonsense.

Monitor the first two iterations. Don't walk away immediately. Watch Claude's first two cycles. Are they making progress? Is the approach sensible? Is Claude interpreting the task the way you intended? If the first two iterations look good, the rest probably will too. If the first iteration is heading in the wrong direction, kill it immediately.

Use specific completion conditions. "DONE" is fine as a marker, but pair it with something measurable. "All tests pass," "no TypeScript errors," "coverage above 80%," "all 15 components created." Something Claude can actually verify programmatically. Vague completion criteria lead to loops that either stop too early or never stop.

Keep a cost eye on it. Check your Anthropic dashboard after your first few Ralph Loop sessions. Understand the cost profile. A well-scoped 10-iteration loop on a mid-sized task typically costs $5-15 for me. A poorly scoped one can cost ten times that. Know what you're spending.

The Bigger Picture

Ralph Loop is the most powerful and most dangerous tool in the Claude Code toolkit. It's the difference between having an agent that works when you're watching and an agent that works while you sleep.

That sentence should both excite you and make you nervous. It excites me because the leverage is real. Waking up to a working feature that didn't exist the night before is a genuinely new experience in software development. Nothing in my career has felt quite like it. Not GitHub Copilot, not ChatGPT, not Cursor. Those tools make me faster when I'm working. Ralph Loop makes progress when I'm not working. That's a category difference.

It makes me nervous because the failure modes are expensive and silent. A bad interactive session wastes your time but you see it happening. A bad Ralph Loop session wastes your money and you find out after the fact. The guardrails help, but they're not perfect.

My honest recommendation: don't use Ralph Loop until you're comfortable with interactive Claude Code. Until plan mode is second nature. Until you've built the CLAUDE.md and context infrastructure that makes Claude reliable. Until you have a strong intuition for what Claude handles well and what it struggles with. Ralph Loop rewards precision and punishes ambiguity, and building that intuition takes time.

But once you have it, once you can reliably scope a task that Claude will execute well autonomously, Ralph Loop is transformative. I use it two or three times a week now, almost always for implementation tasks where the spec is locked and the completion criteria are clear.

It's not for everyday use. Most work belongs in interactive mode with plan mode for the complex stuff. But for the right task, letting Claude run for two hours while you go for a walk is the best possible use of both your time and Claude's capabilities.

The future of development tools isn't about making autocomplete faster. It's about making agents trustworthy enough to run unsupervised. Ralph Loop is the clearest glimpse of that future I've found so far. The permissions and security model that governs what Claude can do unsupervised is what makes this possible without being reckless.