Home
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 pipes a prompt to an AI coding agent, validates the work with checks, and repeats — each iteration starts with a fresh context window.
Install¶
Two commands to start¶
ralph init creates a config file and a starter prompt. ralph run reads the prompt, pipes it to the agent, waits for it to finish, and does it again. Edit RALPH.md while the loop is running — changes take effect on the next iteration.
Or skip setup and pass a prompt directly:
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.
Why it works¶
-
One thing per loop
The agent picks a task, implements it, tests it, and commits. Then the next iteration starts fresh — no accumulated state, no context window bloat.
-
Fresh context every time
Each iteration re-reads
RALPH.mdand the codebase from scratch. The agent always works from the current state, not stale assumptions. -
Progress lives in git
Code and commits are the only state that persists. If something goes wrong,
git reset --hardand run more loops. No hidden state to debug. -
The prompt is a tuning knob
When the agent does something dumb, add a sign to the prompt. "SLIDE DOWN, DON'T JUMP." The next iteration follows the new rules.
Four primitives¶
Ralphify extends the basic loop with four building blocks that live in the .ralphify/ directory:
-
Checks
Run after each iteration to validate the agent's work — tests, linters, type checks. Failed check output feeds into the next iteration so the agent can fix its own mistakes.
-
Contexts
Inject dynamic data into the prompt before each iteration — recent git history, current test status, API responses. The agent always sees fresh information.
-
Instructions
Reusable rules and coding standards injected into the prompt. Toggle them on and off without editing
RALPH.md— useful for style guides, commit conventions, or safety constraints. -
Ralphs
Named, task-focused ralphs you can switch between without editing your root
RALPH.md. Keep adocsralph, arefactorralph, and abug-fixralph — select the one you need at run time withralph run docs.
The self-healing loop¶
Checks create a feedback loop that makes the agent self-correcting:
Iteration N Agent makes a change
Check runs → test fails
Iteration N+1 Agent sees failure output in prompt
Fixes the broken test → checks pass
Iteration N+2 No failures from previous iteration
Agent moves on to the next task
You define what "valid" means. Ralphify feeds failures back into the prompt automatically. The agent doesn't need to remember anything — check output tells it exactly what went wrong.
Requirements¶
- Python 3.11+
- Claude Code CLI (or any agent CLI that accepts piped input)
Next steps¶
-
Step-by-step tutorial from install to a running loop with checks and contexts.
-
Complete, copy-pasteable setups for Python, TypeScript, bug fixing, and docs.
-
Embed the loop in your own automation, listen to events, and manage multiple runs programmatically.