Skip to content

Home

Ralphify CLI banner

A ralph is a directory that defines an autonomous agent loop. Ralphify runs it.

A ralph is a directory with a RALPH.md file — a skill-like format that bundles a prompt, the commands to run between iterations, and any files the agent needs. Ralphify is the CLI runtime that executes them.

See The Ralph Format for the full spec.

grow-coverage/
├── RALPH.md               # the loop definition (required)
├── check-coverage.sh      # command that runs each iteration
└── testing-conventions.md # context for the agent

---
agent: claude -p --dangerously-skip-permissions
commands:
  - name: coverage
    run: ./check-coverage.sh
---

You are an autonomous coding agent working in a loop.
Each iteration, write tests for one untested module, then stop.

Follow the conventions in testing-conventions.md.

## Current coverage

{{ commands.coverage }}

ralph run grow-coverage     # loops until Ctrl+C

One directory. One command. Each iteration starts with fresh context and current data — ralphify runs the commands, fills in {{ placeholders }}, pipes the prompt to your agent, and loops.

Works with any agent CLI. Swap claude -p for Codex, Aider, or your own — just change the agent field.

Get Started Read the Format Spec

Install

uv tool install ralphify

pipx install ralphify

pip install ralphify

Scaffold a ralph and run it

ralph scaffold my-ralph

This creates a directory with a RALPH.md template. Edit it, then run:

ralph run my-ralph         # loop until Ctrl+C
ralph run my-ralph -n 3    # run 3 iterations

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

Or install one with agr

Ralphs are just directories, so you can share them via any git repo. Install a pre-built ralph from GitHub with agr:

agr add owner/repo/my-ralph     # install a ralph from GitHub
ralph run my-ralph              # run it by name

agr installs ralphs to .agents/ralphs/ so they're automatically discovered by ralph run.

Why a format

Everyone writing ralph loops ends up with the same scaffolding: a markdown prompt, a few shell commands that surface state between iterations, a while-loop that ties them together. Turning that into a format makes ralphs shareable, versionable, and installable — the same way skills made inner-loop workflows shareable.

Ralphs are to the outer loop what skills are to the inner loop. A skill guides an agent inside a session. A ralph defines what runs between sessions.

  • 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