From 62f12cfd3994b2c2eca722667542d3ee8ad6bdfd Mon Sep 17 00:00:00 2001 From: Kasper Junge Date: Mon, 8 Jun 2026 19:50:04 +0200 Subject: [PATCH] docs: position ralphify as the loop engineering runtime so it ranks on the new trend Weave "loop engineering" through the README, docs, and landing page so ralphify is discoverable as the runtime for the emerging loop-engineering paradigm (Steinberger/Cherny). Consistently frame it as: the ralph loops format is how you write a loop, ralphify is how you run it. - README + docs/index: bridge line under the tagline; "Why loop engineering works" - landing page: new title/meta/OG/Twitter, hero badge + subhead, "What is loop engineering?" FAQ, "Why loop engineering wins" heading - SEO keywords: add "loop engineering" to index, getting-started, how-it-works, agents, cookbook; retitle How it Works - remove outdated agr install references, reframe sharing around plain git Co-Authored-By: Claude Opus 4.8 --- README.md | 14 ++++++++------ docs/agents.md | 2 +- docs/cookbook.md | 2 +- docs/getting-started.md | 13 ++++++------- docs/how-it-works.md | 8 ++++---- docs/index.md | 13 ++++++++----- mkdocs.yml | 2 +- website/index.html | 24 ++++++++++++++---------- 8 files changed, 43 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 5a6b6850..eaa890bb 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ **Ralphify runs ralph loops.** +Designing autonomous agent loops — *loop engineering* — is becoming how people get real work out of coding agents. The [ralph loops format](https://ralphloops.io/) is how you write one. Ralphify is how you run it. + 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. ``` @@ -138,20 +140,20 @@ The prompt body is re-read from disk every iteration. Edit `RALPH.md` while the - Do NOT delete failing tests — fix the underlying code instead. ``` -### 5. Share and install ralphs +### 5. Share a ralph -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: +A ralph is just a directory in the [ralph loops format](https://ralphloops.io/), so it's portable. Commit it to git, push it, and anyone can clone the repo and run it by name: ```bash -agr add owner/repo/grow-coverage # install a ralph -ralph run grow-coverage # run it by name +git clone https://github.com/owner/repo # grab a shared ralph +ralph run grow-coverage # run it by name ``` --- -## Why loops +## Why loop engineering works -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. +Instead of prompting an agent turn by turn, you write the loop once and let it drive the agent for you. 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. diff --git a/docs/agents.md b/docs/agents.md index a14d9a04..29abd311 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -1,7 +1,7 @@ --- title: How to Run Claude Code, Aider, or Codex in an Autonomous Loop description: Set up Claude Code, Aider, Codex CLI, or any AI coding agent to run autonomously in a loop with ralphify. Copy-pasteable configs, wrapper scripts, and a comparison table. -keywords: run claude code in loop, aider autonomous mode, codex cli automation, AI coding agent loop, autonomous claude code, aider loop setup, run AI agent automatically, pipe prompt to coding agent, claude code non-interactive, aider no-interactive mode, codex exec stdin, automate AI coding agent +keywords: loop engineering, run claude code in loop, aider autonomous mode, codex cli automation, AI coding agent loop, autonomous claude code, aider loop setup, run AI agent automatically, pipe prompt to coding agent, claude code non-interactive, aider no-interactive mode, codex exec stdin, automate AI coding agent --- # Using with Different Agents diff --git a/docs/cookbook.md b/docs/cookbook.md index 573b3044..df13e9cb 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -1,7 +1,7 @@ --- title: Ralph Loop Recipes description: Copy-pasteable ralph loop setups for autonomous ML research, test coverage, code migration, security scanning, deep research, documentation, bug fixing, and codebase improvement. -keywords: ralphify cookbook, autonomous coding recipes, RALPH.md examples, documentation loop, bug fixing loop, codebase improvement, deep research agent, code migration loop, security scanning agent, test coverage automation, autoresearch, autonomous ML research +keywords: loop engineering examples, ralphify cookbook, autonomous coding recipes, RALPH.md examples, documentation loop, bug fixing loop, codebase improvement, deep research agent, code migration loop, security scanning agent, test coverage automation, autoresearch, autonomous ML research --- # Cookbook diff --git a/docs/getting-started.md b/docs/getting-started.md index 16e84c58..56d56e3b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,7 +1,7 @@ --- 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 +keywords: loop engineering, loop engineering tutorial, ralph loops tutorial, install ralphify, write a ralph, ralphloops.io, self-healing loop, run agent loop, ralph loop setup, RALPH.md --- # Getting Started @@ -9,7 +9,7 @@ keywords: ralph loops tutorial, install ralphify, write a ralph, ralphloops.io, !!! 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 command output each iteration and fixes what it breaks. -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/). +What you're about to build is a loop: you write it in the [ralph loops format](https://ralphloops.io/), and ralphify runs it. 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. ## Prerequisites @@ -56,15 +56,14 @@ This creates `my-ralph/RALPH.md` with a ready-to-customize template including an Or create the file manually as shown below. -!!! tip "Installing an existing ralph?" - Use [agr](https://github.com/computerlovetech/agr) to install shared ralphs from GitHub: +!!! tip "Running a shared ralph?" + A ralph is just a directory, so a shared one lives in a git repo. Clone it and run it by name: ```bash - agr add owner/repo + git clone https://github.com/owner/repo + ralph run my-ralph ``` - This installs to `.agents/ralphs/` so you can run it by name with `ralph run `. - ### Manual setup A ralph is a *directory* containing a `RALPH.md` file — the file's shape is defined by the open [ralph loops format](https://ralphloops.io/). Create the directory and a `RALPH.md` with the agent field — this is the only required frontmatter: diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 74d39e9d..9beb68f6 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -1,7 +1,7 @@ --- -title: How Autonomous AI Coding Loops Work — The Ralph Loop Lifecycle -description: Step-by-step breakdown of what happens inside each ralph loop iteration — command execution, prompt assembly, agent piping, and the self-healing feedback cycle that auto-fixes broken code. -keywords: autonomous coding loop lifecycle, how AI coding agents work, self-healing code loop, AI agent feedback cycle, prompt assembly pipeline, ralph loop architecture, agentic coding workflow +title: How Loop Engineering Works — The Ralph Loop Lifecycle +description: Step-by-step breakdown of loop engineering — what happens inside each ralph loop iteration — command execution, prompt assembly, agent piping, and the self-healing feedback cycle that auto-fixes broken code. +keywords: loop engineering, how loop engineering works, autonomous coding loop lifecycle, how AI coding agents work, self-healing code loop, AI agent feedback cycle, prompt assembly pipeline, ralph loop architecture, agentic coding workflow --- # How the ralph loop works @@ -9,7 +9,7 @@ keywords: autonomous coding loop lifecycle, how AI coding agents work, self-heal !!! tldr "TL;DR" Each iteration: re-read `RALPH.md` from disk → run commands → replace `{{ placeholders }}` with output → pipe the assembled prompt to the agent → agent works and exits → repeat. The prompt body is re-read every iteration (so you can edit it live), but frontmatter is parsed once at startup. Failed commands still capture output — that's what makes the loop self-healing. -What happens inside each iteration of an autonomous coding loop? This page breaks down the lifecycle — from command execution to prompt assembly to agent piping — so you can write better prompts, debug unexpected behavior, and understand the self-healing feedback cycle. +Writing a loop is becoming a discipline of its own — *loop engineering*. This page shows what one iteration of a ralph loop actually does: the format you write, and the runtime that runs it. It breaks down the lifecycle — from command execution to prompt assembly to agent piping — so you can write better prompts, debug unexpected behavior, and understand the self-healing feedback cycle. ## The six steps of each iteration diff --git a/docs/index.md b/docs/index.md index f6c3d442..3d1095f4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ --- 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 +description: Ralphify runs ralph loops — the open format for loop engineering and autonomous agent loops (ralphloops.io). The ralph loops format is how you write a loop; ralphify is the runtime that runs it. +keywords: ralphify, loop engineering, ralph loops, ralph loops format, RALPH.md, ralphloops.io, agent loop runtime, autonomous agent loop hide: - toc --- @@ -14,6 +14,8 @@ hide: Ralphify runs ralph loops.

+Designing autonomous agent loops — *loop engineering* — is becoming how people get real work out of coding agents. The [ralph loops format](https://ralphloops.io/) is how you write one. Ralphify is how you run it. + 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/)): a directory whose one required file is `RALPH.md`. **Ralphify** is the CLI that runs it. ``` @@ -118,14 +120,15 @@ Everything in ralphify is one of these five jobs. That's the whole tool. [Getting Started →](getting-started.md#step-7-steer-while-it-runs) -- :material-share-variant-outline:{ .lg .middle } **5. Share and install ralphs** +- :material-share-variant-outline:{ .lg .middle } **5. Share a ralph** --- - 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). + A ralph is a portable directory in the [ralph loops format](https://ralphloops.io/). Commit it to git and push — anyone can clone the repo and run it by name. ```bash - agr add owner/repo/my-ralph + git clone https://github.com/owner/repo + ralph run my-ralph ``` diff --git a/mkdocs.yml b/mkdocs.yml index d0b4f9a2..9f4365ab 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: Ralphify -site_description: A minimal CLI harness for autonomous AI coding loops — run commands, assemble a prompt, pipe it to an agent, and repeat with fresh context each iteration. +site_description: The runtime for loop engineering — write a loop in the ralph loops format, and ralphify runs it. Run commands, assemble a prompt, pipe it to an agent, and repeat with fresh context each iteration. site_url: https://ralphify.co/docs/ repo_url: https://github.com/computerlovetech/ralphify repo_name: computerlovetech/ralphify diff --git a/website/index.html b/website/index.html index 5c0c717b..aec1869f 100644 --- a/website/index.html +++ b/website/index.html @@ -3,16 +3,16 @@ - Ralphify — Stop stressing. Ralph is always running. - - + Ralphify — The Loop Engineering Runtime for AI Coding Agents + + - - + + @@ -23,8 +23,8 @@ - - + + @@ -212,7 +212,7 @@
- Open-source · Agent-agnostic · CLI-native + Loop engineering · Open-source · Agent-agnostic

@@ -225,7 +225,7 @@

- Put your AI coding agent in a while True loop.
+ Ralphify is the runtime for loop engineering — write a loop, run your AI coding agent autonomously.
Write a prompt. Walk away. Wake up to commits.

@@ -443,7 +443,7 @@

A ralph is just
a Markdow

Why loops beat single runs

-

Single runs decay.
Loops compound.

+

Why loop engineering wins:
single runs decay, loops compound.

A single agent conversation fills up, slows down, and loses the plot. Loops don't.

@@ -550,6 +550,10 @@

Get Ralph running

FAQ

+
+ What is loop engineering? +

Loop engineering is the practice of designing autonomous loops that prompt your AI coding agent for you, instead of prompting it by hand turn by turn. You write the loop once — the task, the feedback commands, the stopping rules — and it drives the agent through iteration after iteration. Ralphify is the runtime for loop engineering: you write the loop in the open ralph loops format, and Ralphify runs it.

+
What AI coding agents work with Ralphify?

Any agent that accepts prompts via stdin or CLI arguments — Claude Code, Aider, Codex CLI, and others. Ralphify is agent-agnostic by design. See supported agents.