ralphify 0.1.11

Harness toolkit for autonomous AI coding loops

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

Ralphify is a minimal harness for running autonomous AI coding loops, inspired by the Ralph Wiggum technique. The idea is simple: pipe a prompt to an AI coding agent, let it do one thing, commit, and repeat. Forever. Until you hit Ctrl+C.

while :; do cat RALPH.md | claude -p ; done

Ralphify wraps this pattern into a proper tool with config, iteration tracking, and clean shutdown.

Install

uv tool install ralphify    # recommended

Or if you don't have uv:

pipx install ralphify       # isolated install via pipx
pip install ralphify         # plain pip (use a virtualenv or --user)

Any of these gives you the ralph command.

Quickstart

# In your project directory
ralph init      # Creates ralph.toml + RALPH.md
ralph run       # Starts the loop (Ctrl+C to stop)

That's it. Two commands.

What ralph init creates

ralph.toml — tells ralphify what command to run:

[agent]
command = "claude"
args = ["-p", "--dangerously-skip-permissions"]
ralph = "RALPH.md"

RALPH.md — a starter prompt template. This file IS the prompt. It gets piped directly to your agent each iteration. Edit it to fit your project.

What ralph run does

Reads the prompt, pipes it to the agent, waits for it to finish, then does it again. Each iteration gets a fresh context window. Progress lives in the code and in git.

ralph run          # Run forever
ralph run -n 10    # Run 10 iterations then stop
ralph run docs     # Use a named ralph from .ralphify/ralphs/

What it looks like

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

── Iteration 1 ──
✓ Iteration 1 completed (52.3s) → ralph_logs/001_20250115-142301.log
  Checks: 2 passed
    ✓ lint
    ✓ tests

── Iteration 2 ──
✗ Iteration 2 failed with exit code 1 (23.1s)
  Checks: 1 passed, 1 failed
    ✓ lint
    ✗ tests (exit 1)

── Iteration 3 ──
✓ Iteration 3 completed (41.7s) → ralph_logs/003_20250115-143012.log
  Checks: 2 passed
    ✓ lint
    ✓ tests

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

Iteration 2 broke a test. Iteration 3 automatically received the failure output and fixed it — that's the self-healing loop in action.

The technique

The Ralph Wiggum technique works because:

• One thing per loop. The agent picks the most important task, implements it, tests it, and commits. Then the next iteration starts fresh.
• Fresh context every time. No context window bloat. Each loop starts clean and reads the current state of the codebase.
• Progress lives in git. Code, commits, and a plan file are the only state that persists between iterations. If something goes wrong, git reset --hard and run more loops.
• The prompt is a tuning knob. When the agent does something dumb, you add a sign. Like telling Ralph not to jump off the slide — you add "SLIDE DOWN, DON'T JUMP" to the prompt.

Read the full writeup: Ralph Wiggum as a "software engineer"

Beyond the basic loop

The simple loop works, but ralphify's real power comes from three primitives that live in the .ralphify/ directory.

Checks — the self-healing loop

Checks validate the agent's work after each iteration. When one fails, its output automatically feeds into the next iteration so the agent can fix its own mistakes.

mkdir -p .ralphify/checks/tests

Create .ralphify/checks/tests/CHECK.md:

---
command: uv run pytest -x
timeout: 120
---
Fix all failing tests. Do not skip or delete tests.

Now the loop self-corrects:

Iteration 1 → Agent adds feature → tests pass ✓ → moves on
Iteration 2 → Agent adds feature → tests fail ✗
Iteration 3 → Agent sees failure output → fixes tests → pass ✓

You define what "valid" means. Ralphify feeds failures back automatically.

Contexts — dynamic data injection

Contexts inject fresh data into the prompt each iteration — git history, test status, anything a shell command can produce.

mkdir -p .ralphify/contexts/git-log

Create .ralphify/contexts/git-log/CONTEXT.md:

---
command: git log --oneline -10
---
## Recent commits

The command runs before each iteration. Use {{ contexts.git-log }} in your RALPH.md to control where the output appears.

Ralphs — named task switcher

Keep multiple ralphs for different jobs and switch between them at run time:

ralph new docs
ralph new refactor

Edit .ralphify/ralphs/docs/RALPH.md with your documentation-focused prompt, then:

ralph run docs           # Use the "docs" ralph
ralph run refactor -n 5  # Use "refactor" for 5 iterations

Customizing your ralph

The generated RALPH.md is a starting point. A good prompt for autonomous loops typically includes:

• What to work on (specs, plan file, TODO list)
• Constraints — what NOT to do (no placeholders, no skipping tests)
• Process — how to validate and commit

The agent reads this ralph fresh every iteration, so you can edit it while the loop is running. When the agent does something dumb, add a sign to the prompt — the next iteration follows the new rules.

Documentation

Full documentation at computerlovetech.github.io/ralphify/docs — getting started tutorial, prompt writing guide, cookbook, and troubleshooting.

Requirements

• Python 3.11+
• Claude Code CLI (or any agent CLI that accepts piped input)

License

MIT