From c32e264b0c781cb93cf16966e2bebb18b74600dd Mon Sep 17 00:00:00 2001 From: Kasper Junge Date: Mon, 8 Jun 2026 20:26:36 +0200 Subject: [PATCH] docs: simplify docs and landing so the structure leads instead of jargon MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the explicit 'five jobs' framing across docs, README, and the landing page — keep write/feed/run/steer/share as the underlying structure without naming it as a concept nobody recognizes yet. Remove the noisy info/callout boxes, fold the high-signal bits into prose, and cut the prerequisites and pip/pipx alternatives in favor of uv. Add a directory file tree and a clear args subsection in Getting Started. Recenter the landing page on Ralphify as the runtime for loop engineering that runs the open ralph loops standard, and remove dead cookbook/blog/agents links and the wrong 'ralph init' command. Co-Authored-By: Claude Opus 4.8 --- README.md | 20 +++++---- docs/404.md | 2 +- docs/cli.md | 19 +++++---- docs/getting-started.md | 89 +++++++++++++---------------------------- docs/index.md | 34 +++++----------- website/index.html | 68 ++++++++++++++++++++----------- 6 files changed, 102 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index 0c6f600..c527f91 100644 --- a/README.md +++ b/README.md @@ -49,20 +49,18 @@ That's loop engineering in three lines: a prompt, a command for live data, and t ## Install ```bash -uv tool install ralphify # recommended -pipx install ralphify # or pipx -pip install ralphify # or pip (use a virtualenv) +uv tool install ralphify ``` -Any of these gives you the `ralph` command. +This gives you the `ralph` command. --- -## The five jobs of loop engineering +## What you do with ralphify -Loop engineering with ralphify is one of these five jobs — write, feed, run, steer, share. That's the whole tool. +Working with ralphify comes down to a few things — write a ralph, feed it live data, run the loop, steer it while it runs, and share it. That's the whole tool. -### 1. Write a ralph +### Write a ralph A ralph is a *directory* containing a `RALPH.md` file — that file is the only requirement, and its shape is defined by the open [ralph loops format](https://ralphloops.io/). Scaffold one: @@ -102,7 +100,7 @@ Refactor the code under {{ args.focus }}. Keep tests green. ralph run my-ralph --focus src/auth # {{ args.focus }} → src/auth ``` -### 2. Feed it live data +### Feed it live data `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: @@ -123,7 +121,7 @@ If tests are failing, fix them before starting new work. When the agent breaks a test, the next iteration sees the failure and fixes it. That's the self-healing feedback loop. -### 3. Run the loop +### Run the loop ```bash ralph run my-ralph # loops until Ctrl+C @@ -132,7 +130,7 @@ ralph run my-ralph -n 5 # run 5 iterations then stop Each iteration: run commands → assemble the prompt → pipe it to the agent → repeat with fresh context. -### 4. Steer it while it runs +### Steer it while it runs 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: @@ -142,7 +140,7 @@ 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 a ralph +### Share a ralph This is what the standard format buys you. Because a ralph is just a directory in the open [ralph loops format](https://ralphloops.io/), it's portable — and anyone with ralphify can run it. Commit it to git, push it, and your loop engineering becomes someone else's starting point: diff --git a/docs/404.md b/docs/404.md index 2ef1445..c55180d 100644 --- a/docs/404.md +++ b/docs/404.md @@ -15,7 +15,7 @@ This page doesn't exist — it may have been moved or the URL might have a typo. **Try one of these instead:** -- [**Home**](index.md) — overview, install, and the five jobs +- [**Home**](index.md) — overview, install, and what ralphify does - [**Getting Started**](getting-started.md) — from install to a running loop - [**Reference**](cli.md) — the CLI, RALPH.md format, how the loop works, agents, and troubleshooting diff --git a/docs/cli.md b/docs/cli.md index 425e7b6..1dc2d76 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,10 +6,9 @@ keywords: loop engineering, ralph CLI reference, RALPH.md format, ralph run, ral # Reference -Everything beyond [the five jobs](index.md#the-five-jobs-of-loop-engineering) lives here: the CLI, the `RALPH.md` format, how a loop iteration works under the hood, how to wire up different agents, troubleshooting, and the Python API. +Everything beyond [the basics](index.md#what-you-do-with-ralphify) lives here: the CLI, the `RALPH.md` format, how a loop iteration works under the hood, how to wire up different agents, troubleshooting, and the Python API. -!!! tldr "TL;DR" - **`ralph run -n 5`** runs the loop. **`ralph scaffold `** creates a ralph from a template. Pass user args as `--name value` flags. Everything is configured in a single [`RALPH.md`](#ralphmd-format) file with YAML frontmatter. +`ralph run -n 5` runs the loop. `ralph scaffold ` creates a ralph from a template. Pass user args as `--name value` flags. Everything is configured in a single [`RALPH.md`](#ralphmd-format) file with YAML frontmatter. --- @@ -177,8 +176,7 @@ Your instructions here. Reference args with {{ args.dir }}. Commands run in order. Output (stdout + stderr) is captured regardless of exit code. -!!! warning "No shell features in commands" - Commands are parsed with `shlex.split()` and run directly, not through a shell — pipes (`|`), redirections (`>`), and chaining (`&&`) won't work in the `run` field. Point the `run` field at a script instead: `run: ./my-script.sh`. +Commands are parsed with `shlex.split()` and run directly, not through a shell — pipes (`|`), redirections (`>`), and chaining (`&&`) won't work in the `run` field. Point the `run` field at a script instead: `run: ./my-script.sh`. ### Placeholders @@ -309,11 +307,12 @@ The [`examples/`](https://github.com/computerlovetech/ralphify/tree/main/example ## Troubleshooting -!!! tldr "Quick checklist" - 1. Run `ralph run my-ralph -n 1` — it validates your setup and shows clear errors - 2. Test the agent outside ralphify: `echo "Say hello" | claude -p` - 3. Use `--log-dir ralph_logs` to capture output for debugging - 4. Commands don't support shell features (pipes, `&&`) — use a wrapper script instead +A quick checklist before digging in: + +1. Run `ralph run my-ralph -n 1` — it validates your setup and shows clear errors +2. Test the agent outside ralphify: `echo "Say hello" | claude -p` +3. Use `--log-dir ralph_logs` to capture output for debugging +4. Commands don't support shell features (pipes, `&&`) — use a wrapper script instead ### Setup diff --git a/docs/getting-started.md b/docs/getting-started.md index ddb7f92..bf2bbe8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,16 +6,7 @@ keywords: loop engineering, loop engineering tutorial, ralph loops tutorial, ins # 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 command output each iteration and fixes what it breaks. - -What you're about to do is loop engineering: you write a loop in the open [ralph loops format](https://ralphloops.io/), and ralphify — the runtime — runs it. This tutorial walks through the five jobs — **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 - -- **Python 3.11+** -- **An AI coding agent CLI** — this tutorial uses [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Install it with `npm install -g @anthropic-ai/claude-code`. Ralphify also works with [other agents](cli.md#using-different-agents). -- **A project with a test suite** (we'll use this for the feedback loop) +What you're about to do is loop engineering: you write a loop in the open [ralph loops format](https://ralphloops.io/), and ralphify — the runtime — runs it. This tutorial walks you through writing a ralph, feeding it live data, running the loop, steering it while it runs, and sharing it. By the end you'll have a self-healing loop that validates its own work. ## Step 1: Install ralphify @@ -23,21 +14,7 @@ What you're about to do is loop engineering: you write a loop in the open [ralph uv tool install ralphify ``` -??? note "Alternative install methods" - ```bash - pip install ralphify # pip works too - pipx install ralphify # or pipx - ``` - -Verify it's working: - -```bash -ralph --version -``` - -```text -ralphify 0.3.0 -``` +This gives you the `ralph` command. ## Step 2: Create a ralph @@ -56,17 +33,16 @@ This creates `my-ralph/RALPH.md` with a ready-to-customize template including an Or create the file manually as shown below. -!!! 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: +### Manual setup - ```bash - git clone https://github.com/owner/repo - ralph run my-ralph - ``` +A ralph is a *directory* — not a single file. It contains a `RALPH.md` (the loop definition) plus any scripts or files the loop needs. `RALPH.md` is the only requirement; its shape is defined by the open [ralph loops format](https://ralphloops.io/): -### Manual setup +```text +my-ralph/ +└── RALPH.md # the loop definition (required) +``` -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: +Create the directory and a `RALPH.md` with the `agent` field — this is the only required frontmatter: ```markdown --- @@ -88,27 +64,27 @@ implement it fully, then mark it done. - Mark the completed task in TODO.md ``` -!!! tip "Parameterize a ralph with `args`" - Declare `args` in the frontmatter to make one ralph reusable with different inputs. Each name becomes a `{{ args. }}` placeholder filled from the CLI: +### Parameterize with args + +To make one ralph reusable with different inputs, declare `args` in the frontmatter. Each name becomes a `{{ args. }}` placeholder in the prompt body, filled from the CLI at run time: - ```markdown - --- - agent: claude -p --dangerously-skip-permissions - args: - - focus - --- +```markdown +--- +agent: claude -p --dangerously-skip-permissions +args: + - focus +--- - Refactor the code under {{ args.focus }}. One module per iteration. - ``` +Refactor the code under {{ args.focus }}. One module per iteration. +``` - ```bash - ralph run my-ralph --focus src/auth - ``` +Pass the value with a matching flag: - See the [CLI reference](cli.md#user-arguments) for named vs. positional args. +```bash +ralph run my-ralph --focus src/auth # {{ args.focus }} → src/auth +``` -!!! info "What does `--dangerously-skip-permissions` do?" - Claude Code normally asks for your approval before running shell commands, editing files, or making git commits. The `--dangerously-skip-permissions` flag disables these interactive prompts so the agent can work autonomously without waiting for input. The `-p` flag enables non-interactive ("print") mode, which reads the prompt from stdin instead of opening a chat session. +The same ralph now runs against any path you give it. See the [CLI reference](cli.md#user-arguments) for named vs. positional args. ## Step 3: Do a test run @@ -132,17 +108,9 @@ ls ralph_logs/ cat ralph_logs/001_*.log ``` -!!! tip "Add `ralph_logs/` to `.gitignore`" - Log files are useful for debugging but shouldn't be committed: - - ```bash - echo "ralph_logs/" >> .gitignore - ``` - -If the agent produced useful work, you're ready to add test feedback. +Log files are useful for debugging but shouldn't be committed — add `echo "ralph_logs/" >> .gitignore`. -!!! info "Something not working?" - If the agent errored or didn't do anything useful, check [Troubleshooting](cli.md#troubleshooting) for common issues — agent hangs, missing commands, and frontmatter mistakes are all covered there. +If the agent produced useful work, you're ready to add test feedback. If it errored or didn't do anything useful, check [Troubleshooting](cli.md#troubleshooting). ## Step 4: Add a test command @@ -291,8 +259,7 @@ Read TODO.md and focus only on the API module. This is the most powerful part of ralph loops — you're steering a running agent with a text file. -!!! warning "Frontmatter changes need a restart" - Only the **prompt body** is re-read each iteration. Frontmatter fields (`agent`, `commands`, `args`) are parsed once at startup. If you add a new command or change the agent, stop the loop with `Ctrl+C` and restart it. +Note that only the **prompt body** is re-read each iteration. Frontmatter fields (`agent`, `commands`, `args`) are parsed once at startup, so if you add a command or change the agent, stop the loop with `Ctrl+C` and restart it. ## Next steps diff --git a/docs/index.md b/docs/index.md index 8d3182c..2b2e4f0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -69,33 +69,19 @@ Write the loop once in the standard format, and ralphify runs it for as long as ## Install -=== "uv (recommended)" - - ```bash - uv tool install ralphify - ``` - -=== "pipx" - - ```bash - pipx install ralphify - ``` - -=== "pip" - - ```bash - pip install ralphify - ``` +```bash +uv tool install ralphify +``` --- -## The five jobs of loop engineering +## What you do with ralphify -Loop engineering with ralphify is one of these five jobs — write, feed, run, steer, share. That's the whole tool. +Working with ralphify comes down to a few things — write a ralph, feed it live data, run the loop, steer it while it runs, and share it. That's the whole tool.
-- :material-file-document-edit-outline:{ .lg .middle } **1. Write a ralph** +- :material-file-document-edit-outline:{ .lg .middle } **Write a ralph** --- @@ -107,7 +93,7 @@ Loop engineering with ralphify is one of these five jobs — write, feed, run, s [Getting Started →](getting-started.md) -- :material-database-arrow-down-outline:{ .lg .middle } **2. Feed it live data** +- :material-database-arrow-down-outline:{ .lg .middle } **Feed it live data** --- @@ -115,7 +101,7 @@ Loop engineering with ralphify is one of these five jobs — write, feed, run, s [How it works →](cli.md#how-the-loop-works) -- :material-play-circle-outline:{ .lg .middle } **3. Run the loop** +- :material-play-circle-outline:{ .lg .middle } **Run the loop** --- @@ -127,7 +113,7 @@ Loop engineering with ralphify is one of these five jobs — write, feed, run, s [CLI reference →](cli.md) -- :material-pencil-outline:{ .lg .middle } **4. Steer it while it runs** +- :material-pencil-outline:{ .lg .middle } **Steer it while it runs** --- @@ -135,7 +121,7 @@ Loop engineering with ralphify is one of these five jobs — write, feed, run, s [Getting Started →](getting-started.md#step-7-steer-while-it-runs) -- :material-share-variant-outline:{ .lg .middle } **5. Share a ralph** +- :material-share-variant-outline:{ .lg .middle } **Share a ralph** --- diff --git a/website/index.html b/website/index.html index aec1869..cbc9e14 100644 --- a/website/index.html +++ b/website/index.html @@ -157,10 +157,10 @@ "@type": "HowToStep", "position": 2, "name": "Create a ralph", - "text": "Run ralph init my-ralph in your project directory to scaffold a RALPH.md prompt file.", + "text": "Run ralph scaffold my-ralph in your project directory to scaffold a RALPH.md prompt file.", "itemListElement": { "@type": "HowToDirection", - "text": "Run: ralph init my-ralph" + "text": "Run: ralph scaffold my-ralph" } }, { @@ -189,8 +189,7 @@
Docs - Cookbook - Blog + Ralph loops GitHub Get Started
@@ -212,26 +211,25 @@
- Loop engineering · Open-source · Agent-agnostic + Loop engineering · Open standard · Agent-agnostic

- Stop stressing over not having - an agent running. + Write the loop once. - Ralph is always running + Ralphify runs it.

- Ralphify is the runtime for loop engineering — write a loop, run your AI coding agent autonomously.
+ Ralphify is the runtime for loop engineering. Define an autonomous agent loop in the open ralph loops standard — a portable RALPH.md — and Ralphify runs it: fresh context and live data every iteration.
Write a prompt. Walk away. Wake up to commits.

Get Started - View Cookbook + The ralph loops standard
@@ -260,6 +258,31 @@

+ + + +
+
+

A standard, and a runtime for it

+

Loops are worth defining once.

+

+ Loop engineering splits into two pieces: an open way to define a loop, and a runtime that runs it. +

+
+
+
{ }
+

Ralph loops — the standard

+

The open ralph loops format defines a loop as a portable directory whose one required file is RALPH.md: a prompt, the commands that feed it live data, and the files it needs. Because it's a standard, a loop is shareable — write it once, commit the directory, and anyone can run it.

+
+
+
🏃
+

Ralphify — the runtime

+

The ralph CLI runs a ralph loop: run the commands, assemble the prompt, pipe it to your agent, and repeat with a fresh context window every iteration. Agent-agnostic, zero config, pure terminal.

+
+
+
+
+ @@ -479,22 +502,22 @@

Progress lives in git

Any agent that reads stdin.

Ralphify is a harness, not an agent. Pipe to whatever you want.

- + ✨ Claude Code Anthropic's CLI agent - + >_ Aider AI pair programming - + ▶ Codex CLI OpenAI's CLI agent - + 🏃 Any CLI agent If it reads stdin, it works @@ -525,8 +548,8 @@

Get Ralph running

2 Create a ralph
- ralph init my-ralph - + ralph scaffold my-ralph +
@@ -539,7 +562,7 @@

Get Ralph running

-

Also available via pip install ralphify or pipx install ralphify

+

Installs the ralph command. Requires Python 3.11+ and any agent CLI that reads stdin.

@@ -556,7 +579,7 @@

FAQ

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.

+

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.

What is a ralph loop? @@ -601,12 +624,12 @@

- uv tool install ralphify && ralph init my-ralph && ralph run my-ralph - + uv tool install ralphify && ralph scaffold my-ralph && ralph run my-ralph +
Read the guide - View Cookbook + The ralph loops standard
@@ -618,9 +641,8 @@

Documentation