Skip to content

Home

Ralphify CLI banner

Put your AI coding agent in a while True loop and let it ship.

Ralphify is a minimal CLI harness for autonomous AI coding loops, inspired by the Ralph Wiggum technique. It runs commands, assembles a prompt with the output, pipes it to an AI coding agent, and repeats — each iteration starts with a fresh context window.

Get Started View Cookbook

Install

uv tool install ralphify

pipx install ralphify

pip install ralphify

Create a ralph and run it

A ralph is just a directory with a RALPH.md file:

my-ralph/
└── RALPH.md

my-ralph/RALPH.md

---
agent: claude -p --dangerously-skip-permissions
commands:
  - name: tests
    run: uv run pytest -x
  - name: git-log
    run: git log --oneline -10
---

# Prompt

{{ commands.git-log }}

You are an autonomous coding agent running in a loop. Each iteration
starts with a fresh context. Your progress lives in the code and git.

Read TODO.md for the current task list. Pick the top uncompleted task,
implement it fully, then mark it done.

## Rules

- One task per iteration
- No placeholder code — full, working implementations only
- Run tests before committing
- Commit with a descriptive message like `feat: add X` or `fix: resolve Y`
- Mark the completed task in TODO.md

ralph run my-ralph         # Start the loop (Ctrl+C to stop)
ralph run my-ralph -n 3    # Run 3 iterations

What it looks like

$ ralph run my-ralph -n 3 --log-dir ralph_logs

── Iteration 1 ──
✓ Iteration 1 completed (52.3s) → ralph_logs/001_20250115-142301.log

── Iteration 2 ──
✗ Iteration 2 failed with exit code 1 (23.1s)

── Iteration 3 ──
✓ Iteration 3 completed (41.7s) → ralph_logs/003_20250115-143012.log

Done: 3 iteration(s) — 2 succeeded, 1 failed

Edit RALPH.md while the loop is running — changes take effect on the next iteration.

Why ralph loops?

A single agent conversation fills up its context window, slows down, and eventually loses the plot. Ralph loops solve this by resetting every iteration — the agent always starts fresh.

  • Fresh context, no decay

    Each iteration starts with a clean context window. No conversation bloat, no hallucinated memories, no degradation over time. The agent reads the current state of the codebase every loop.

  • Commands as feedback

    Commands run each iteration and their output feeds into the prompt. When tests fail, the agent sees the failure output and fixes it in the next iteration — a self-healing feedback loop.

  • Steer while it runs

    The prompt is re-read every iteration. Edit RALPH.md while the loop runs and the agent follows your new rules on the next cycle. When it does something dumb, add a sign.

  • Progress lives in git

    Every iteration commits to git. If something goes wrong, git log shows exactly what happened and git reset rolls it back. No opaque internal state to debug or lose.

Requirements

Next steps

  • Getting Started — from install to a running loop in 10 minutes
  • Writing Prompts — patterns for effective autonomous loop prompts
  • Cookbook — copy-pasteable setups for Python, TypeScript, Rust, and more
  • Python API — embed the loop in your own automation