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.

Stops "done" too early

Ralph treats "done" as a checkpoint, not a finish line. It verifies completion multiple times across fresh rotations.

Keeps context clean

Every rotation starts with a clean slate, so failed attempts don't clutter the next pass.

Saves progress safely

Work carries forward through file-based handoffs, so nothing gets lost between rotations.

  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

Create PROMPT.md

Write your goal, constraints, and success criteria in PROMPT.md. Ralph uses this file as the source of truth for 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

Run one command in your project folder. Ralph starts the agent, supervises each rotation, and keeps progress saved in handoff files.

$ 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

Ralph handles the rest

Ralph automatically rotates context, runs verification cycles, and only stops after completion is detected with repeated clean checks.

[rotation 7/300] CONTINUE
[rotation 8/300] CONTINUE
[verification 1/3] PASS
[verification 2/3] PASS
[verification 3/3] PASS
[status] DONE - all success criteria met

Ralph doesn't just trust "done"

AI agents love to declare victory prematurely. Ralph's triple verification system catches issues they miss — no more cleaning up after false completions.

✓ Agent signals DONE

When the agent thinks it's finished, Ralph doesn't just take its word for it. This triggers the verification cycle.

✓✓ Must confirm 3 times

Ralph runs three consecutive verification passes. Each with fresh context. Each checking against your success criteria.

✓✓✓ Or counter resets

If any check fails or makes changes, back to zero. Only three clean passes in a row means truly complete.

This changes everything: No more premature "done" declarations. No more finding broken edge cases later. Ralph keeps verifying until the work actually meets your standards — not just when the agent thinks it does.

Get Started

Install with pipx
$ pipx install ralph-loop

Quick Start

  1. Install Ralph
  2. Create PROMPT.md with your task
  3. Run ralph run

For full documentation, examples, and advanced usage, use the GitHub link above, then run your first loop with ralph run.