The Ralph Loop: Running Claude Code For Hours Autonomously

Last updated: May 24, 2026

Official Sources#

Claude Opus 4.5 just ran for 4 hours and 49 minutes straight - autonomously, without human intervention. This isn't a typo. It's a fundamental shift in what's possible with AI-assisted coding.

For context: GPT-4 managed 5 minutes. We've gone from a parlor trick to actual, practical work in less than two years.

The catch? You can't just run claude code and walk away. You need stop hooks.

The Autonomy Gap#

Claude Code is powerful, but it's not a self-driving car by default. You get permission prompts. You get questions. It asks for confirmation. This is good - you want guardrails when an AI can commit to git, delete files, and push code.

For the broader agentic coding map, read Claude Code Agent Teams, Subagents, and MCP: The 2026 Playbook and Why Skills Beat Prompts for Coding Agents in 2026; they connect this article to the surrounding tool and workflow decisions.

But for long-running tasks - refactors, test-driven development, processing todo lists - these interruptions kill productivity. You're back at your desk every few minutes, babysitting prompts.

Stop hooks solve this. They're deterministic checkpoints that fire when Claude finishes a thought, allowing you to inject logic, run tests, and loop back without stopping.

How Stop Hooks Work#

Hooks are shell commands that execute at specific points in Claude's workflow. Think git hooks, but for AI.

When Claude finishes a task and tries to exit, the stop hook intercepts it. Instead of returning a message to you, it:

1. Runs your hook script (tests, validation, whatever)
2. Captures the output
3. Feeds it back into Claude's context
4. Lets it continue autonomously

This creates a deterministic loop around Claude's non-deterministic agent behavior.

The power is in the timing. By running tests after edits are complete, Claude immediately sees what broke and can fix it iteratively. It's not guessing - it has real feedback.

Enter Ralph Wiggum#

"He's determined to get it done. So he'll just keep trying until it actually works."

That's the Ralph Loop philosophy, named after the Simpsons character who embodied persistence through repetition.

The Ralph Loop works like this:

You pass Claude a task plus a completion_promise - a condition that must be met. Claude executes. On stop, the hook checks the promise. If unmet, Claude loops back and tries again. This repeats until either:

• The completion promise is satisfied
• Max iterations is reached
• The work is done

Example: Give Claude a todo list. Tell it to mark each item complete as it goes. Add unit tests after each step. Claude runs through the list without stopping, fixing failures before moving on.

/ralph-loop \
  --prompt "Complete all tasks in tasks.md" \
  --completion-promise "All checkboxes marked" \
  --max-iterations 50

Real Numbers#

Boris Cherny, Claude Code's creator, published his usage stats:

• 259 PRs generated
• 457 commits
• 40,000 lines added
• 38,000 lines removed
• Every line written by Claude + Opus 4.5
• Using stop hooks throughout

This isn't theoretical anymore. This is production code at scale.

Practical Applications#

Test-driven development: Write tests first. Tell Claude to pass them. Hook runs tests after each attempt. Claude fixes failures iteratively.

Long refactors: List changes in a markdown file. Claude works through them step-by-step, validating with tests between each change. No babysitting.

Migrations: Database schema changes, dependency upgrades, API migrations. Chunk them into a todo list. Claude runs through it.

Batch tasks: Process hundreds of files, regenerate assets, scaffold scaffolding. One prompt, multiple iterations, deterministic validation at each step.

The common thread: You define success criteria, Claude pursues them relentlessly.

Setup#

The fastest way in is the official Ralph Wiggum plugin:

claude code --install-plugin ralph-wiggum

This gives you:

• /ralph-loop command
• Pre-configured stop hook
• State management
• Max iteration safeguards

Then define your todo list in markdown:

- [ ] Implement authentication
  - Unit tests: `npm test -- auth.test.js`
  - Integration test: `npm run test:integration`
- [ ] Add user dashboard
  - Tests: `npm test -- dashboard.test.js`
- [ ] Deploy to staging
  - Smoke tests: `npm run test:smoke`

Point Claude at it:

/ralph-loop \
  --prompt "Complete every todo in tasks.md, marking each done as you finish. Run all associated tests. Fix failures before moving on." \
  --completion-promise "All items marked complete and all tests passing" \
  --max-iterations 100

Then walk away.

The Critical Detail#

Always set max-iterations and completion-promise. Otherwise you get an infinite loop burning tokens forever. This is the guardrail that keeps the Ralph Loop from going rogue.

The hook can't know when to stop unless you tell it. Be explicit.

What Changes#

This pattern inverts the developer-AI dynamic. Instead of:

• You prompt Claude
• Claude thinks and stops
• You read output
• You prompt again

You get:

• You define the target
• Claude works autonomously
• You come back when it's done

The model's capability to stay on task for hours - especially with Opus 4.5's long context window - turns "AI assistants" into "AI workers."

4 hours and 49 minutes. That's a full workday's worth of focused engineering, no breaks, no context switching, deterministic validation at every step.

We're not there yet universally. 80% completion rate drops significantly, and 4:49 is a best-case benchmark. But the trajectory is undeniable. Each model generation gets better at staying focused, following chains of logic, and recovering from dead ends.

Stop hooks are the infrastructure that makes it practical.

Further Reading#

• Claude Code Hooks Documentation - Official hook configuration reference
• Claude Code Overview - Getting started with autonomous workflows

Frequently Asked Questions#

What is the Ralph Loop in Claude Code?#

The Ralph Loop is a pattern for running Claude Code autonomously for extended periods. Named after Ralph Wiggum from The Simpsons (who embodied persistence through repetition), it uses stop hooks to create a deterministic loop around Claude's agent behavior. You define a completion promise, Claude works until that condition is met or max iterations is reached, and the hook validates progress between each attempt.

How long can Claude Code run autonomously?#

With Opus 4.5 and stop hooks properly configured, Claude Code has run autonomously for 4 hours and 49 minutes on complex tasks. This is a significant improvement from earlier models. The actual runtime depends on task complexity, the completion promise you set, and the max iterations limit.

What are stop hooks?#

Stop hooks are shell commands that execute when Claude finishes a task and attempts to exit. Instead of returning control to you, the hook runs validation (tests, checks), captures output, feeds it back into Claude's context, and lets it continue working. This creates autonomous loops where Claude iterates on its own work until your success criteria are met.

How do I set up the Ralph Loop?#

Install the official Ralph Wiggum plugin with claude code --install-plugin ralph-wiggum. Then use the /ralph-loop command with three parameters: a prompt describing the work, a completion promise defining success criteria, and a max iterations limit as a safeguard. Point it at a markdown todo list and let Claude work through it autonomously.

What tasks work best with autonomous Claude Code?#

Test-driven development (write tests, let Claude pass them), long refactors (todo list of changes with validation), database migrations, batch file processing, and any repetitive task with clear success criteria. The common thread is: you define what "done" looks like, and Claude works toward it without interruption.

Is there a risk of runaway token usage?#

Yes, which is why you must always set max-iterations and completion-promise. Without these guardrails, the Ralph Loop can run indefinitely, burning tokens. Be explicit about when to stop. The hook cannot know completion criteria unless you define them.

What's the completion rate for autonomous sessions?#

Current benchmarks show around 80% completion rate on well-defined tasks, though this drops on ambiguous or complex requirements. The 4-hour-49-minute run is a best-case benchmark. Each model generation improves focus and recovery from dead ends, so these numbers continue to trend upward.

Watch the Video#

Continue Reading#

• Setting Up a Spare Mac for Claude Code: The Full Remote Control Guide