From ac466bd8983054f440886240999ae1b0ef8ff042 Mon Sep 17 00:00:00 2001 From: Kasper Junge Date: Mon, 8 Jun 2026 18:52:30 +0200 Subject: [PATCH] docs: center README and docs on the five jobs and the ralph loops format Reposition ralphify as the runtime for the ralph loops format (ralphloops.io) rather than a generic AI tool, and lead both the README and docs landing with the five things you do with it: write a ralph, feed it live data, run the loop, steer it while it runs, and share it. Co-Authored-By: Claude Opus 4.8 --- README.md | 165 +++++++----------- docs/cookbook.md | 2 +- .../2026-06-08-simplify-docs-five-jobs.md | 76 ++++++++ docs/getting-started.md | 10 +- docs/index.md | 102 +++++------ 5 files changed, 197 insertions(+), 158 deletions(-) create mode 100644 docs/diary/2026-06-08-simplify-docs-five-jobs.md diff --git a/README.md b/README.md index e633cffd..c9923e61 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,14 @@ Documentation

-**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. }}` placeholders with fresh output -3. **Pipes to agent** — runs the agent command with the assembled prompt on stdin -4. **Repeats** — goes back to step 1 with updated data +`RALPH.md` is YAML frontmatter + a markdown prompt. The only required field is `agent`: -### What it looks like +```markdown +--- +agent: claude -p --dangerously-skip-permissions +--- +Read TODO.md, pick the top unfinished task, implement it fully, commit, then stop. +One task per iteration. No placeholder code. ``` -$ ralph run grow-coverage -n 3 -▶ Running: grow-coverage - 1 command · max 3 iterations +### 2. Feed it live data -── Iteration 1 ── - Commands: 1 ran -✓ Iteration 1 completed (52.3s) +`commands` run before each iteration. Their output replaces `{{ commands. }}` in the prompt, so the agent always sees the current state — test results, coverage, git log, lint output: + +```markdown +--- +agent: claude -p --dangerously-skip-permissions +commands: + - name: tests + run: uv run pytest -x +--- -── Iteration 2 ── - Commands: 1 ran -✗ Iteration 2 failed with exit code 1 (23.1s) +## Test results -── Iteration 3 ── - Commands: 1 ran -✓ Iteration 3 completed (41.7s) +{{ commands.tests }} -────────────────────── -Done: 3 iterations — 2 succeeded, 1 failed +If tests are failing, fix them before starting new work. ``` -## The ralph format +When the agent breaks a test, the next iteration sees the failure and fixes it. That's the self-healing feedback loop. -A **ralph** is a directory containing a `RALPH.md` file. Everything the ralph needs lives in that directory — scripts, reference docs, test data, whatever the agent might need. +### 3. Run the loop +```bash +ralph run my-ralph # loops until Ctrl+C +ralph run my-ralph -n 5 # run 5 iterations then stop ``` -my-ralph/ -├── RALPH.md # the prompt (required) -├── check-coverage.sh # script (optional) -├── style-guide.md # reference doc (optional) -└── test-data.json # any supporting file (optional) -``` - -**RALPH.md** has YAML frontmatter for configuration and a markdown body that becomes the prompt: - -| Frontmatter field | Required | Description | -|---|---|---| -| `agent` | Yes | The agent command to run | -| `commands` | No | List of commands (name + run) whose output fills `{{ commands. }}` placeholders | -| `args` | No | Declared argument names for `{{ args. }}` placeholders | -| `credit` | No | Append co-author trailer instruction to prompt (default: `true`) | -**Commands** run before each iteration. Their output replaces `{{ commands. }}` placeholders in the prompt. Use them for test results, coverage reports, git history, lint output — anything that changes between iterations. +Each iteration: run commands → assemble the prompt → pipe it to the agent → repeat with fresh context. -## The technique +### 4. Steer it while it runs -The Ralph Wiggum technique works because: +The prompt body is re-read from disk 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: -- **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. +```markdown +## Rules -Read the full writeup: [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/) +- Do NOT delete failing tests — fix the underlying code instead. +``` -## Share ralphs +### 5. Share and install ralphs -Use [agr](https://github.com/computerlovetech/agr) to install shared ralphs from GitHub: +A ralph is just a directory in the [ralph loops format](https://ralphloops.io/), so it's portable — version it in git, share it, install it. Use [agr](https://github.com/computerlovetech/agr) to install one from GitHub: ```bash -agr add owner/repo/grow-coverage # install a ralph from GitHub +agr add owner/repo/grow-coverage # install a ralph ralph run grow-coverage # run it by name ``` -Ralphs installed by agr go to `.agents/ralphs/` and are automatically discovered by `ralph run`. +--- + +## Why loops + +A single agent run can fix a bug or write 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 every iteration.** No context-window bloat. The agent starts clean and reads the current state of the codebase. +- **Commands as feedback.** Live data feeds back into the prompt each loop, so the agent self-corrects. +- **Steer with a text file.** Edit the prompt mid-run to redirect a running agent. +- **Progress lives in git.** Every iteration commits. `git log` shows what happened; `git reset` rolls it back. + +Read the original writeup: [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/). ## Documentation -Full documentation at **[ralphify.co/docs](https://ralphify.co/docs/)** — getting started tutorial, format spec, cookbook, CLI reference, and troubleshooting. +Full docs at **[ralphify.co/docs](https://ralphify.co/docs/)** — getting started, the loop lifecycle, CLI reference, and cookbook. The format spec lives at **[ralphloops.io](https://ralphloops.io/)**. ## Requirements diff --git a/docs/cookbook.md b/docs/cookbook.md index e6455725..573b3044 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -9,7 +9,7 @@ keywords: ralphify cookbook, autonomous coding recipes, RALPH.md examples, docum !!! tldr "TL;DR" 8 copy-pasteable ralph loops: [autoresearch](#autoresearch), [codebase improvement](#codebase-improvement), [documentation](#documentation-loop), [bug hunting](#bug-hunter), [deep research](#deep-research), [code migration](#code-migration), [security scanning](#security-scan), and [test coverage](#test-coverage). Each is a real, runnable example from the `examples/` directory. -Copy-pasteable setups for common autonomous workflows. Each recipe is a real, runnable ralph from the [`examples/`](https://github.com/computerlovetech/ralphify/tree/main/examples) directory. +Once you know [the five things you do with ralphify](index.md#the-five-things-you-do-with-ralphify), these are starting points to copy. Each recipe is a real, runnable ralph loop from the [`examples/`](https://github.com/computerlovetech/ralphify/tree/main/examples) directory. All recipes use **Claude Code** as the agent. To use a different agent, swap the `agent` field — see [Using with Different Agents](agents.md). diff --git a/docs/diary/2026-06-08-simplify-docs-five-jobs.md b/docs/diary/2026-06-08-simplify-docs-five-jobs.md new file mode 100644 index 00000000..42757b12 --- /dev/null +++ b/docs/diary/2026-06-08-simplify-docs-five-jobs.md @@ -0,0 +1,76 @@ +# Diary: Simplify docs around the five jobs and the ralph loops format + +Drastically simplify the README and MkDocs documentation so newcomers can understand ralphify fast. Two positioning shifts: (1) ralphify is the **runtime for the ralph loops format** (the open spec at [ralphloops.io](https://ralphloops.io/)), not "an AI tool"; (2) center everything on the five things you actually *do* with ralphify, rather than a sprawl of example use cases. + +## Step 1: Reframe README and docs landing around the five jobs + +**Author:** main + +### Prompt Context + +**Verbatim prompt:** "Okay so we need to drastically simplify the documentation, the mkdocs documentation and the readme file. We need to center around the five most valuable jobs to be done that Ralph can do. We also need to make it clear to people that it is using ralphloops.io not AI. Ralph loops that I owe in the standard format. Please identify the five jobs to be done that Ralph can help with and make them very clear and upfront in the documentation because there's way too much now. Simplify it so people can understand it and it will be easy to understand and get started with. Please go do" + +**Interpretation:** Cut the documentation down and make it center on five clearly-stated jobs-to-be-done, presented upfront. Stop marketing ralphify as a generic "AI tool" and make clear it runs ralph loops — a standardized, portable format. + +**Inferred intent:** Lower the comprehension barrier for new users. The docs had grown heavy with "autonomous AI coding agent" SEO phrasing and eight cookbook recipes, which buried the simple core: ralphify runs ralph loops, and there are only a handful of things you do with it. + +### What I did + +Started by surveying the existing docs surface: `mkdocs.yml` nav, `/README.md`, `/docs/index.md`, `/docs/getting-started.md`, `/docs/how-it-works.md`, and `/docs/cookbook.md`. + +I initially assumed the "five jobs" were five example *use cases* (grow coverage, fix bugs, migrate, etc.) and asked the user to confirm a set via `AskUserQuestion`. The user corrected two things that changed the whole approach: + +1. The five jobs are **not** example use cases — they're the five things you do to *create and run ralph loops* (the mechanics of using the tool). +2. The format is the one defined at **https://ralphloops.io/** — a standard format the user owns. Ralphify *uses* that format. + +I fetched ralphloops.io via `WebFetch` to ground the framing: the ralph loops format is "a lightweight specification for packaging autonomous agent workflows as portable directories," centered on a single required `RALPH.md` file with agent definition, commands, arguments, and instructions. + +With that, I defined the five jobs as the spine of the docs: + +1. **Write a ralph** — scaffold a `RALPH.md` +2. **Feed it live data** — `commands` → `{{ commands. }}` placeholders (self-healing feedback) +3. **Run the loop** — `ralph run` +4. **Steer it while it runs** — edit the prompt mid-run +5. **Share and install ralphs** — portable directories / `agr` + +Then I rewrote: +- `/README.md` — rewrote around "Ralphify runs ralph loops" + the five jobs, with a link to ralphloops.io as the format spec. Stripped "autonomous AI coding agent" SEO phrasing. +- `/docs/index.md` — rewrote the landing page; the five jobs are now a card grid, each linking to the relevant page. Title/description/keywords reframed around "ralph loops" and ralphloops.io. +- `/docs/getting-started.md` — retitled and reframed the intro around the five jobs; dropped AI-heavy SEO from frontmatter. +- `/docs/cookbook.md` — reframed the intro so recipes are clearly *secondary* starting points you reach for after learning the five jobs. + +Verified with `uv run mkdocs build --strict` — exit 0. + +### Why + +The user's two corrections are positioning decisions: ralphify is a *runtime for an open format*, and the docs should teach the *mechanics* of that format rather than parade use cases. Leading both the README and the docs home with the same five-job structure gives a single, repeated mental model. Linking ralphloops.io in both places makes the "it's a format, not just a tool" point concrete. + +### What worked + +The card-grid layout in `index.md` (reusing the existing `grid cards` Material extension already used on the page) maps cleanly to five jobs with one icon + one CTA each. The strict build passed first try after the rewrites, so no broken internal links or snippet references. + +### What didn't work + +My first `AskUserQuestion` call failed validation: + +``` +InputValidationError: Too big: expected array to have <=4 items (path: questions[0].options) +``` + +I had put 8 options on the "which five jobs" question; the tool caps options at 4. I reworked it into preset bundles. More importantly, the *premise* of that question was wrong — the user rejected the "example use cases" framing entirely, which is the real lesson, not the validation error. + +### What I learned + +The "five jobs to be done" are a product-narrative device, not a feature list: they're the verbs of using ralphify (write / feed / run / steer / share). The user thinks of ralphify as an implementation of the ralphloops.io format — that ownership of the format is central to how it should be marketed. + +### What was tricky + +The original prompt was voice-transcribed and garbled: "it is using ralphloops.io not AI. Ralph loops that I owe in the standard format." Decoding that into "ralphify uses the ralph loops format (ralphloops.io), a standard format the user owns — don't market it as a generic AI tool" required a clarifying round. Worth the round-trip; guessing wrong would have meant rewriting the rewrite. + +### What warrants review + +Look at `/README.md` and `/docs/index.md` first — they carry the new positioning and the five-job structure; check the framing reads the way the user wants. Confirm the five chosen jobs are the right five (write / feed / run / steer / share). The deeper reference pages (`how-it-works.md`, `cli.md`, `api.md`, `quick-reference.md`, `troubleshooting.md`) were left intact and are now secondary — verify nothing in them contradicts the new lead narrative. The nav in `mkdocs.yml` was not pruned. + +### Future work + +Potential follow-ups that fell out of the work but were not done: pruning/restructuring the `mkdocs.yml` nav to match the five-job spine; possibly folding `how-it-works.md` into getting-started; trimming the cookbook to fewer recipes. The `ralphs/example/` untracked directory present in the working tree is unrelated to this change and was left alone. diff --git a/docs/getting-started.md b/docs/getting-started.md index 306954ad..fce2bde8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,15 +1,15 @@ --- -title: How to Set Up an Autonomous AI Coding Agent Loop — Ralphify Tutorial -description: Install ralphify, create your first ralph, add test commands for self-healing feedback, and run an autonomous AI coding loop — step-by-step in 10 minutes. -keywords: set up autonomous AI coding agent, install ralphify, AI coding loop tutorial, self-healing coding agent, run AI agent in loop, automate coding agent prompts, ralph loop setup, claude code autonomous +title: Getting Started with Ralph Loops — Ralphify Tutorial +description: Install ralphify, write your first ralph loop, feed it live data with commands, run it, and steer it while it runs — step-by-step in 10 minutes. +keywords: ralph loops tutorial, install ralphify, write a ralph, ralphloops.io, self-healing loop, run agent loop, ralph loop setup, RALPH.md --- # Getting Started !!! tldr "TL;DR" - `uv tool install ralphify` → `ralph scaffold my-ralph` → edit the RALPH.md → `ralph run my-ralph -n 1 --log-dir ralph_logs` to test → add a `commands` entry for your test suite → `ralph run my-ralph` to loop. The agent sees fresh test output each iteration and fixes what it breaks. + `uv tool install ralphify` → `ralph scaffold my-ralph` → edit the RALPH.md → `ralph run my-ralph -n 1 --log-dir ralph_logs` to test → add a `commands` entry for your test suite → `ralph run my-ralph` to loop. The agent sees fresh command output each iteration and fixes what it breaks. -This tutorial walks through setting up ralphify, creating a ralph with commands, and running a productive autonomous loop. By the end, you'll have a self-healing coding loop that validates its own work. +This tutorial walks through the five things you do with ralphify — **write** a ralph, **feed** it live data, **run** the loop, **steer** it while it runs, and **share** it. By the end you'll have a self-healing loop that validates its own work. Ralphify implements the open [ralph loops format](https://ralphloops.io/). ## Prerequisites diff --git a/docs/index.md b/docs/index.md index 03da5c94..74883b2c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ --- -title: Ralphify — a runtime for the ralph format -description: Ralphify is the runtime for the ralph format — a skill-like spec for autonomous agent loops. A ralph is a directory with a RALPH.md file. Ralphify runs it. -keywords: ralphify, ralph format, RALPH.md, autonomous agent loop, agent runtime, harness engineering, skill-like format, ralph spec +title: Ralphify — the runtime for ralph loops +description: Ralphify runs ralph loops — an open format for autonomous agent loops (ralphloops.io). A ralph loop is a directory with a RALPH.md file. Ralphify runs it. +keywords: ralphify, ralph loops, ralph loops format, RALPH.md, ralphloops.io, agent loop runtime, autonomous agent loop hide: - toc --- @@ -11,18 +11,15 @@ hide:

-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. +
-## Or install one with agr +- :material-file-document-edit-outline:{ .lg .middle } **1. Write a ralph** -Ralphs are just directories, so you can share them via any git repo. Install a pre-built ralph from GitHub with [agr](https://github.com/computerlovetech/agr): + --- -```bash -agr add owner/repo/my-ralph # install a ralph from GitHub -ralph run my-ralph # run it by name -``` + Scaffold a directory with a `RALPH.md` — YAML frontmatter for config, a markdown body for the prompt. The only required field is `agent`. -agr installs ralphs to `.agents/ralphs/` so they're automatically discovered by `ralph run`. + ```bash + ralph scaffold my-ralph + ``` ---- + [Getting Started →](getting-started.md) -## Why a format +- :material-database-arrow-down-outline:{ .lg .middle } **2. Feed it live data** -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](https://agentskills.io/) are to the inner loop. A skill guides an agent inside a session. A ralph defines what runs *between* sessions. + `commands` run each iteration; their output fills `{{ commands. }}` in the prompt. The agent always sees current test results, coverage, and git log — a self-healing feedback loop. -
+ [How it works →](how-it-works.md) -- :material-refresh:{ .lg .middle } **Fresh context, no decay** +- :material-play-circle-outline:{ .lg .middle } **3. Run the loop** --- - 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. + `ralph run` assembles the prompt, pipes it to your agent, and repeats with fresh context. Loop until `Ctrl+C` or cap it with `-n`. -- :material-shield-check-outline:{ .lg .middle } **Commands as feedback** - - --- + ```bash + ralph run my-ralph -n 5 + ``` - 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. + [CLI reference →](cli.md) -- :material-pencil-outline:{ .lg .middle } **Steer while it runs** +- :material-pencil-outline:{ .lg .middle } **4. Steer it 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. + 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. -- :material-git:{ .lg .middle } **Progress lives in git** + [Getting Started →](getting-started.md#step-7-steer-while-it-runs) + +- :material-share-variant-outline:{ .lg .middle } **5. Share and install ralphs** --- - 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. + A ralph is a portable directory in the [ralph loops format](https://ralphloops.io/). Version it in git, share it, install it from GitHub with [agr](https://github.com/computerlovetech/agr). + + ```bash + 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 - Python 3.11+ @@ -149,8 +152,7 @@ Ralphs are to the outer loop what [skills](https://agentskills.io/) are to the i ## Next steps -- **[How it Works](how-it-works.md)** — the full loop lifecycle - **[Getting Started](getting-started.md)** — from install to a running loop in 10 minutes - **[How it Works](how-it-works.md)** — what happens inside each iteration -- **[Cookbook](cookbook.md)** — copy-pasteable ralphs for coding, docs, research, and more -- **[Python API](api.md)** — embed the loop in your own automation +- **[Cookbook](cookbook.md)** — copy-pasteable ralph loops to start from +- **[The ralph loops format](https://ralphloops.io/)** — the open spec ralphify implements