Skip to content

Home

Ralphify CLI banner

Ralphify runs ralph loops.

A ralph loop is a portable directory that defines an autonomous agent loop — a prompt, the commands to run between iterations, and any files the agent needs. It's an open format (ralphloops.io): a directory whose one required file is RALPH.md. Ralphify is the CLI that runs it.

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

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

Each iteration, write tests for one untested module, then stop.

## Current coverage

{{ commands.coverage }}

ralph run grow-coverage     # loops until Ctrl+C

Each iteration starts with a fresh context window and current data — ralphify runs the commands, fills in the {{ 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 The ralph loops format

Install

uv tool install ralphify

pipx install ralphify

pip install ralphify

The five things you do with ralphify

Everything in ralphify is one of these five jobs. That's the whole tool.

  • 1. Write a ralph

    Scaffold a directory with a RALPH.md — YAML frontmatter for config, a markdown body for the prompt. The only required field is agent; add args to parameterize the loop with {{ args.<name> }}.

    ralph scaffold my-ralph

    Getting Started →

  • 2. Feed it live data

    commands run each iteration; their output fills {{ commands.<name> }} in the prompt. The agent always sees current test results, coverage, and git log — a self-healing feedback loop.

    How it works →

  • 3. Run the loop

    ralph run assembles the prompt, pipes it to your agent, and repeats with fresh context. Loop until Ctrl+C or cap it with -n.

    ralph run my-ralph -n 5

    CLI reference →

  • 4. Steer it while it runs

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

    Getting Started →

  • 5. Share and install ralphs

    A ralph is a portable directory in the ralph loops format. Version it in git, share it, install it from GitHub with agr.

    agr add owner/repo/my-ralph

Why loops

A single agent run fixes a bug or writes a function. The leverage of a ralph loop is sustained, autonomous work — running for hours, one commit at a time, while you do something else.

  • Fresh context, no decay. Each iteration starts with a clean context window. The agent reads the current state of the codebase every loop — no conversation bloat, no degradation.
  • Commands as feedback. Command output feeds into the prompt each iteration. When tests fail, the agent sees the failure and fixes it next cycle.
  • Steer with a text file. Edit RALPH.md while the loop runs to redirect a running agent.
  • Progress lives in git. Every iteration commits. git log shows what happened; git reset rolls it back.

Requirements

Next steps