You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|[Aider](#aider)| Via bash wrapper | No | Yes (`bash -c`) |
22
+
|[Codex CLI](#codex-cli)| Native (`exec`) | No | No |
23
+
|[Custom](#custom-wrapper-script)| You implement it | No | Yes (script) |
24
24
25
25
If you're not sure which to pick: **start with Claude Code.** It has the deepest integration, the best autonomous coding capabilities, and is the default.
Copy file name to clipboardExpand all lines: docs/blog/posts/the-ralph-standard.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -150,14 +150,14 @@ ralph run ./ralphs/bug-hunter
150
150
151
151
Declare `args: [focus]` and you get `--focus` on the CLI. The value fills `{{ args.focus }}` in the prompt. One ralph, many use cases.
152
152
153
-
Because ralphs are just directories in a git repo, anyone can share them. If a repo contains a directory with a `RALPH.md`, you can install it with `ralph add`:
153
+
Because ralphs are just directories in a git repo, anyone can share them. If a repo contains a directory with a `RALPH.md`, you can install it with [agr](https://github.com/computerlovetech/agr):
154
154
155
155
```bash
156
156
# install a specific ralph from any GitHub repo
157
-
ralph add owner/repo/ralph-name
157
+
agr add owner/repo/ralph-name
158
158
159
159
# install all ralphs in a repo
160
-
ralph add owner/repo
160
+
agr add owner/repo
161
161
```
162
162
163
163
The [ralphify examples](https://github.com/computerlovetech/ralphify/tree/main/examples) are a good place to start — and the [cookbook](https://ralphify.co/docs/cookbook/) has more.
Copy file name to clipboardExpand all lines: docs/cli.md
+8-54Lines changed: 8 additions & 54 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,13 @@
1
1
---
2
2
title: "CLI Reference: Run AI Coding Agents in Autonomous Loops"
3
-
description: "Complete CLI reference for the ralph command — run autonomous AI coding loops, scaffold new agent prompts, install shared ralphs from GitHub, and configure RALPH.md frontmatter options."
4
-
keywords: run AI agent in loop CLI, autonomous coding agent command line, ralph run command, ralph init, ralph add GitHub, RALPH.md frontmatter format, AI coding loop options, agent timeout iterations, user arguments CLI, ralphify CLI reference
3
+
description: "Complete CLI reference for the ralph command — run autonomous AI coding loops, scaffold new agent prompts, and configure RALPH.md frontmatter options."
4
+
keywords: run AI agent in loop CLI, autonomous coding agent command line, ralph run command, ralph scaffold, RALPH.md frontmatter format, AI coding loop options, agent timeout iterations, user arguments CLI, ralphify CLI reference
5
5
---
6
6
7
7
# CLI Reference
8
8
9
9
!!! tldr "TL;DR"
10
-
**`ralph run <path> -n 5`** runs the loop. **`ralph init <name>`**scaffolds a ralph from a template. **`ralph new`** creates one with AI guidance. **`ralph add owner/repo`** installs from GitHub. Pass user args as `--name value` flags. Everything is configured in a single [`RALPH.md`](#ralphmd-format) file with YAML frontmatter.
10
+
**`ralph run <path> -n 5`** runs the loop. **`ralph scaffold <name>`**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.
11
11
12
12
## `ralph`
13
13
@@ -52,7 +52,7 @@ ralph run my-ralph --dir ./src # Pass user args to the ralph
|`PATH`|| (required) | Path to a ralph directory containing `RALPH.md`, a direct path to a `RALPH.md` file, or the name of an installed ralph (from `ralph add`)|
55
+
|`PATH`|| (required) | Path to a ralph directory containing `RALPH.md`, a direct path to a `RALPH.md` file, or the name of an installed ralph in `.agents/ralphs/`|
56
56
|`-n`|| unlimited | Max number of iterations |
57
57
|`--stop-on-error`|`-s`| off | Stop loop if agent exits non-zero or times out |
58
58
|`--delay`|`-d`|`0`| Seconds to wait between iterations |
@@ -116,13 +116,13 @@ The loop also stops automatically when:
116
116
117
117
---
118
118
119
-
## `ralph init`
119
+
## `ralph scaffold`
120
120
121
-
Scaffold a new ralph with a ready-to-customize template. No AI agent required. For a guided setup, see [`ralph new`](#ralph-new) instead.
121
+
Scaffold a new ralph with a ready-to-customize template.
122
122
123
123
```bash
124
-
ralph init my-task # Creates my-task/RALPH.md with a generic template
125
-
ralph init# Creates RALPH.md in the current directory
124
+
ralph scaffold my-task # Creates my-task/RALPH.md with a generic template
125
+
ralph scaffold# Creates RALPH.md in the current directory
126
126
```
127
127
128
128
| Argument | Default | Description |
@@ -135,52 +135,6 @@ Errors if `RALPH.md` already exists at the target location.
135
135
136
136
---
137
137
138
-
## `ralph new`
139
-
140
-
Create a new ralph with AI-guided setup. Launches an interactive session where the agent guides you through creating a complete ralph via conversation.
141
-
142
-
```bash
143
-
ralph new # Agent helps you choose a name and build everything
144
-
ralph new my-task # Start with a name already chosen
145
-
```
146
-
147
-
| Argument | Default | Description |
148
-
|---|---|---|
149
-
|`[NAME]`| none | Name for the new ralph. If omitted, the agent will help you choose |
150
-
151
-
The command detects your [agent](agents.md) and installs a skill to guide the creation process.
152
-
153
-
---
154
-
155
-
## `ralph add`
156
-
157
-
Add a ralph from a GitHub repository. Installs it to `.ralphify/ralphs/<name>/` so you can run it by name.
158
-
159
-
```bash
160
-
ralph add owner/repo # Install all ralphs in the repo
161
-
ralph add owner/repo/ralph-name # Specific ralph by name
162
-
ralph add https://github.com/owner/repo # Full GitHub URL
163
-
ralph add https://github.com/owner/repo/tree/main/my-ralph # URL copied from GitHub browser
164
-
```
165
-
166
-
| Argument | Default | Description |
167
-
|---|---|---|
168
-
|`SOURCE`| required | GitHub source — shorthand (`owner/repo`), subpath (`owner/repo/path`), or full GitHub URL |
169
-
170
-
**How it resolves:**
171
-
172
-
-`owner/repo` — if the repo root contains `RALPH.md`, installs it as a single ralph named after the repo. Otherwise, finds and installs all ralphs in the repo.
173
-
-`owner/repo/ralph-name` — searches the repo for a directory named `ralph-name` containing `RALPH.md`. If multiple matches are found, prints the paths and asks you to use the full subpath to disambiguate.
174
-
-`https://github.com/owner/repo/tree/branch/path` — extracts the path from the URL. This is the format you get when you copy a URL from the GitHub web UI while browsing a directory. The branch name is used only to locate the path — `ralph add` always clones the default branch.
175
-
176
-
After adding, run the ralph by name:
177
-
178
-
```bash
179
-
ralph run ralph-name
180
-
```
181
-
182
-
---
183
-
184
138
## RALPH.md format
185
139
186
140
The `RALPH.md` file is the single configuration and prompt file for a ralph. It uses YAML frontmatter for settings and the body for the prompt text. See [Writing Prompts](writing-prompts.md) for detailed guidance on crafting effective prompts.
└── new-ralph/ # AI-guided ralph creation skill for `ralph new`
33
+
└── _brand.py # Brand color constants shared across CLI and console rendering
38
34
39
35
tests/ # Pytest tests — one test file per module
40
36
docs/ # MkDocs site (Material theme) — user-facing documentation
@@ -118,8 +114,6 @@ The CLI uses a `ConsoleEmitter` (defined in `_console_emitter.py`) that renders
118
114
3.**`cli.py`** — All CLI commands. Validates frontmatter fields via extracted helpers (`_validate_agent`, `_validate_commands`, `_validate_credit`, `_validate_run_options`, `_validate_declared_args`), builds a `RunConfig`, and delegates to `engine.run_loop()` for the actual loop. Terminal event rendering lives in `_console_emitter.py`.
119
115
4.**`_frontmatter.py`** — YAML frontmatter parsing. Extracts `agent`, `commands`, `args` from the RALPH.md file.
120
116
5.**`_resolver.py`** — Template placeholder logic. Small file but critical.
121
-
6.**`_skills.py`** + **`skills/`** — The skill system behind `ralph new`. `_skills.py` handles agent detection, reads bundled skill definitions from `skills/`, installs them into the agent's skill directory, and builds the command to launch the agent.
Copy file name to clipboardExpand all lines: docs/getting-started.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ keywords: set up autonomous AI coding agent, install ralphify, AI coding loop tu
7
7
# Getting Started
8
8
9
9
!!! tldr "TL;DR"
10
-
`uv tool install ralphify` → `ralph init 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.
10
+
`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.
11
11
12
12
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.
13
13
@@ -41,10 +41,10 @@ ralphify 0.3.0
41
41
42
42
## Step 2: Create a ralph
43
43
44
-
The fastest way to scaffold a ralph is `ralph init`:
44
+
The fastest way to scaffold a ralph is `ralph scaffold`:
45
45
46
46
```bash
47
-
ralph init my-ralph
47
+
ralph scaffold my-ralph
48
48
```
49
49
50
50
```text
@@ -54,16 +54,16 @@ Edit the file, then run: ralph run my-ralph
54
54
55
55
This creates `my-ralph/RALPH.md` with a ready-to-customize template including an example command, arg, and prompt. Edit the task section, [test it](#step-3-do-a-test-run), then follow [Step 4](#step-4-add-a-test-command) to add a test command — test feedback is what makes the loop self-healing.
56
56
57
-
Alternatively, use `ralph new` for AI-guided setup, or create the file manually as shown below.
57
+
Or create the file manually as shown below.
58
58
59
59
!!! tip "Installing an existing ralph?"
60
-
If someone has shared a ralph on GitHub, skip the manual setup and install it directly:
60
+
Use [agr](https://github.com/computerlovetech/agr) to install shared ralphs from GitHub:
61
61
62
62
```bash
63
-
ralph add owner/repo
63
+
agr add owner/repo
64
64
```
65
65
66
-
This installs to `.ralphify/ralphs/` so you can run it by name with `ralph run <name>`. See the [CLI reference](cli.md#ralph-add) for all source formats.
66
+
This installs to `.agents/ralphs/` so you can run it by name with `ralph run <name>`.
Edit `RALPH.md` while the loop is running — changes take effect on the next iteration.
129
129
130
-
## Or grab one from GitHub
130
+
## Or install one with agr
131
131
132
-
Install a pre-built ralph from any GitHub repo and run it immediately:
132
+
Install a pre-built ralph from any GitHub repo using [agr](https://github.com/computerlovetech/agr)and run it immediately:
133
133
134
134
```bash
135
-
ralph add owner/repo/my-ralph # Install a ralph from GitHub
135
+
agr add owner/repo/my-ralph# Install a ralph from GitHub
136
136
ralph run my-ralph # Run it
137
137
```
138
138
139
-
`ralph add` fetches the ralph and installs it locally. You can install a single ralph by name, or all ralphs in a repo at once with `ralph add owner/repo`. See the [CLI reference](cli.md#ralph-add) for details.
139
+
agr installs ralphs to `.agents/ralphs/` so you can run them by name.
0 commit comments