ralph-loop 0.3.0

Autonomous development loop with context rotation

Ralph

Stop cleaning up after your AI coding agent.

Ralph supervises Claude Code (and other agents soon) to actually finish what they start. When Claude loses track, declares "done" prematurely, or forgets earlier decisions -- Ralph catches it.

Who This Is For

• You use Claude Code or similar AI coding tools
• You're building real projects, not just experimenting
• You've been frustrated by half-finished AI output
• You want better results, even if it costs more tokens

Quick Start

1. Install and initialize

   pipx install ralph-loop
   ralph init
   

2. Describe what you want built (in PROMPT.md)

   # Goal
   Add a contact form that emails submissions to me.
   
   # Success Criteria
   - [ ] Form has name, email, message fields
   - [ ] Validates email format before sending
   - [ ] Shows success message after submission
   - [ ] Emails go to [e-mail]
   

3. Let Ralph supervise the build

   ralph run
   

   Ralph keeps Claude working until all criteria are actually met. Verified 3 times to make sure nothing was missed.

How It Works

Claude Code is powerful, but on bigger tasks it can:

• Lose context as the conversation grows
• Forget decisions made earlier in the session
• Declare "done" when things clearly aren't

Ralph solves this by breaking big tasks into fresh-context chunks.

After each chunk, Ralph:

1. Saves what Claude learned and accomplished (so nothing is lost)
2. Starts a fresh session (so context stays clean)
3. Hands off the state (so Claude picks up where it left off)

When Claude says "done", Ralph doesn't just trust it. It verifies 3 times with fresh eyes. If anything was missed, work continues.

Result: Tasks that used to fail halfway through now complete reliably.

The Tradeoff

Ralph uses more tokens than running Claude directly. Each rotation is a fresh API call, and verification adds more.

But: You'll spend less time debugging, less time re-prompting, and less time cleaning up half-finished work. For many tasks, the extra tokens are worth it.

Commands

Command	Description
ralph init	Initialize Ralph in the current directory
ralph run	Supervise Claude until the goal is complete
ralph inspect	Inspect a running Ralph session
ralph status	Show current progress
ralph reset	Start fresh
ralph history	View logs from previous sessions
ralph --about	Show comprehensive explanation (useful for AI agents)

Configuration

The .ralph/ directory contains local state and should not be committed:

# .gitignore
.ralph/

Documentation

• Getting Started - Full setup guide
• Writing Effective Prompts - Get better results
• Troubleshooting - When things go wrong
• Full Documentation - Everything else

Built By

Ralph was created by Ilja Weber to solve my own frustrations with AI coding agents declaring "done" too early.

Follow for updates:

• LinkedIn
• Twitter/X

License

MIT