-**A ralph is a directory that defines an autonomous agent loop.** It bundles a prompt, commands, and any files your agent needs. Ralphify is the CLI runtime that executes them.
+**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](https://ralphloops.io/)): one required file, `RALPH.md`. Ralphify is the CLI that runs it.
```
grow-coverage/
-├── RALPH.md # the prompt (only required file)
-├── check-coverage.sh # command that runs each iteration
-└── testing-conventions.md # context for the agent
+├── RALPH.md # the loop definition (required)
+└── check-coverage.sh # a command that runs each iteration
```
```markdown
@@ -26,11 +27,8 @@ commands:
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 }}
@@ -40,147 +38,110 @@ Follow the conventions in testing-conventions.md.
ralph run grow-coverage # loops until Ctrl+C
```
-That's it. One directory. One command. The agent loops — running commands, building a fresh prompt with the latest output, and piping it to your agent. Every iteration starts with clean context and current data.
+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. Walk away, come back to a pile of commits.
*Works with any agent CLI. Swap `claude -p` for Codex, Aider, or your own — just change the `agent` field.*
-## Why loops
-
-A single agent run can fix a bug or write a function. But the real leverage is **sustained, autonomous work** — campaigns that run for hours, chipping away at a goal one commit at a time while you do something else.
-
-Ralph loops give you:
-
-- **Incremental progress in small chunks.** Each iteration does one thing, tests it, and commits. Small changes are easier to review and safer to ship.
-- **Fresh context every iteration.** No context window bloat. The agent starts clean each loop and sees the current state of the codebase — including everything it changed last iteration.
-- **Continuous work toward a goal.** The loop keeps running until you hit Ctrl+C or it reaches the iteration limit. Walk away, come back to a pile of commits.
-- **No micromanagement.** Define the goal once in the prompt, tune with commands that feed live data back in. The agent figures out what to do next.
-- **The prompt is a tuning knob.** When the agent does something dumb, add a rule. Like putting up a sign: "SLIDE DOWN, DON'T JUMP."
-
-### What people build ralphs for
-
-| Ralph | What it does |
-|---|---|
-| **grow-coverage** | Write tests for untested modules, one per iteration, until coverage hits the target |
-| **security-audit** | Hunt for vulnerabilities — scan, find, fix, verify, repeat |
-| **clear-backlog** | Work through a TODO list or issue tracker, one task per loop |
-| **write-docs** | Generate documentation for undocumented modules, one at a time |
-| **improve-codebase** | Find and fix code smells, refactor patterns, modernize APIs |
-| **migrate** | Incrementally migrate files from one framework or pattern to another |
-| **research** | Deep-dive into a topic — gather sources, synthesize, and build a knowledge base |
-| **bug-hunter** | Run the test suite, find edge cases, write regression tests |
-| **perf-sweep** | Profile, find bottlenecks, optimize, benchmark, repeat |
-
-The ralph format is intentionally simple — if you've written a skill file or a GitHub Action, you already know how it works. YAML frontmatter for config, markdown body for the prompt, `{{ commands.name }}` placeholders for live data.
-
## Install
```bash
uv tool install ralphify # recommended
-```
-
-Or if you don't have `uv`:
-
-```bash
-pipx install ralphify # isolated install via pipx
-pip install ralphify # plain pip (use a virtualenv or --user)
+pipx install ralphify # or pipx
+pip install ralphify # or pip (use a virtualenv)
```
Any of these gives you the `ralph` command.
-## Quickstart
+---
-Scaffold a ralph and start experimenting:
+## The five things you do with ralphify
-```bash
-ralph scaffold my-ralph
-```
+Everything in ralphify is one of these five jobs. That's the whole tool.
-Edit `my-ralph/RALPH.md`, then run it:
+### 1. Write a ralph
+
+A ralph is a directory with a `RALPH.md` file. Scaffold one:
```bash
-ralph run my-ralph # loops until Ctrl+C
-ralph run my-ralph -n 5 # run 5 iterations then stop
+ralph scaffold my-ralph
```
-### What `ralph run` does
-
-Each iteration:
-1. **Runs commands** — executes all commands in the ralph, captures output
-2. **Builds prompt** — reads the RALPH.md body, replaces `{{ commands.-A ralph is a directory that defines an autonomous agent loop. Ralphify runs it. +Ralphify runs ralph loops.
-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 [How it Works](how-it-works.md) for a full breakdown of the loop lifecycle. +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](https://ralphloops.io/)): one required file, `RALPH.md`. **Ralphify** is the CLI that runs it. ``` grow-coverage/ ├── RALPH.md # the loop definition (required) -├── check-coverage.sh # command that runs each iteration -└── testing-conventions.md # context for the agent +└── check-coverage.sh # a command that runs each iteration ``` ```markdown @@ -33,11 +30,8 @@ commands: 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 }} @@ -47,12 +41,12 @@ Follow the conventions in testing-conventions.md. 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. +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](getting-started.md){ .md-button .md-button--primary } -[How it Works](how-it-works.md){ .md-button } +[The ralph loops format](https://ralphloops.io/){ .md-button } --- @@ -76,70 +70,79 @@ One directory. One command. Each iteration starts with fresh context and current pip install ralphify ``` -## Scaffold a ralph and run it - -```bash -ralph scaffold my-ralph -``` +--- -This creates a directory with a `RALPH.md` template. Edit it, then run: +## The five things you do with ralphify -```bash -ralph run my-ralph # loop until Ctrl+C -ralph run my-ralph -n 3 # run 3 iterations -``` +Everything in ralphify is one of these five jobs. That's the whole tool. -Edit `RALPH.md` while the loop is running — changes take effect on the next iteration. +