Stop cleaning up after your AI coding agent

Ralph supervises your AI coding agent with context rotation, so every iteration starts clean and stays accountable. No more "it's done!" when it isn't. No more lost context. No more starting over.

$ pipx install ralph-loop
GitHub

Claude Code is powerful, but...

If you vibe-code with Claude Code, Cursor, or other AI coding agents, you've probably felt this. It's not you — the workflow breaks down over long threads, and you end up doing cleanup instead of building.

!

It loses context in long conversations

The more you iterate, the more confused it gets. Early decisions get forgotten. You end up repeating yourself.

!

Failed attempts pollute its memory

Every wrong turn stays in context. The agent starts mixing up what worked and what didn't.

!

It declares "done" when it isn't

You ask for a feature, it says it's complete, but half the edge cases are broken. Back to cleanup duty.

Context rotation fixes this

Instead of one long, polluted conversation, Ralph runs multiple short iterations. Each starts fresh but continues from where the last left off. Progress is saved in files, not in context.

  ROTATION 1              ROTATION 2              ROTATION 3
  +-----------+           +-----------+           +-----------+
  |  Fresh    |           |  Fresh    |           |  Fresh    |
  |  Context  |           |  Context  |           |  Context  |
  +-----------+           +-----------+           +-----------+
       |                       |                       |
       v                       v                       v
  +-----------+           +-----------+           +-----------+
  |   Work    |           |   Work    |           |   Work    |
  |  on task  |           |  on task  |           |  on task  |
  +-----------+           +-----------+           +-----------+
       |                       |                       |
       v                       v                       v
  +-----------+           +-----------+           +-----------+
  |  Save     |   ---->   |  Load     |   ---->   |  Load     |
  |  Progress |           |  Progress |           |  Progress |
  +-----------+           +-----------+           +-----------+
       |                       |                       |
       v                       v                       v
   CONTINUE                CONTINUE                 DONE

Each rotation gets a clean slate without the baggage of failed attempts, but picks up exactly where the previous rotation left off using file-based handoffs.

How It Works

1

Describe what you want

Create a PROMPT.md file with your goal and success criteria. Ralph injects this into every rotation.

# PROMPT.md

# Goal
Build a REST API for user authentication

# Success Criteria
- POST /register creates new users
- POST /login returns JWT tokens
- All endpoints have tests passing
2

Run Ralph

Ralph starts Claude Code and supervises it. The agent works, saves progress to files, and signals when to rotate or when it's done.

$ ralph run

# Ralph will:
# - Start Claude Code with your PROMPT.md
# - Monitor for completion signals
# - Rotate context when needed
# - Verify completion 3x before finishing
3

Get actually finished work

Ralph keeps rotating until the task is truly complete. No premature "done" declarations. No lost progress. No cleanup duty for you.

Ralph doesn't just trust "done"

When an agent signals completion, Ralph starts a verification cycle. The task must pass three consecutive checks before it's truly finished.

1 First verification

Fresh context reviews all work against the original success criteria. Any issues? Back to implementation.

2 Second verification

Another fresh context checks again. Different perspective might catch different issues.

3 Third verification

Final check confirms everything works. Three passes with no changes means it's actually done.

If any verification finds issues and makes changes, the counter resets. This ensures the agent can't just declare victory and move on.

Get Started

Install with pipx
pipx install ralph-loop

Quick Start

  1. Install Ralph
  2. Create a PROMPT.md with your goal and success criteria
  3. Run ralph run in your project directory

Full Documentation on GitHub