Quick Reference¶

Everything you need at a glance. Bookmark this page.

CLI commands¶

ralph run my-ralph                 # Run loop forever (Ctrl+C to stop)
ralph run my-ralph -n 5            # Run 5 iterations
ralph run my-ralph -n 1 --log-dir logs  # Single iteration with output capture
ralph run my-ralph --stop-on-error # Stop if agent exits non-zero
ralph run my-ralph --delay 10      # Wait 10s between iterations
ralph run my-ralph --timeout 300   # Kill agent after 5 min per iteration
ralph run my-ralph -- --dir ./src  # Pass user args to the ralph

ralph new                          # AI-guided ralph creation
ralph new docs                     # AI-guided creation with name pre-filled

ralph --version                    # Show version

Directory structure¶

my-ralph/
└── RALPH.md              # Prompt + configuration (required)

That's it. A ralph is a directory with a RALPH.md file.

RALPH.md format¶

---
agent: claude -p --dangerously-skip-permissions    # Required: agent command
commands:                                           # Optional: run each iteration
  - name: tests
    run: uv run pytest -x
  - name: lint
    run: uv run ruff check .
  - name: git-log
    run: git log --oneline -10
args: [dir, focus]                                  # Optional: declared user arguments
---

# Prompt body

{{ commands.git-log }}

{{ commands.tests }}

{{ commands.lint }}

Your instructions here. Use {{ args.dir }} for user arguments.

Frontmatter fields¶

Field	Type	Required	Description
`agent`	string	yes	Full agent command (piped via stdin)
`commands`	list	no	Commands to run each iteration
`args`	list	no	User argument names

Command fields¶

Field	Type	Description
`name`	string	Identifier for `{{ commands.<name> }}`
`run`	string	Shell command to execute

Placeholders¶

Command placeholders¶

{{ commands.tests }}              # Replaced with test command output
{{ commands.git-log }}            # Replaced with git-log command output

Output includes stdout + stderr regardless of exit code
Unmatched placeholders resolve to empty string
Must be commands (plural)

User argument placeholders¶

{{ args.dir }}                   # Replaced with --dir value from CLI
{{ args.focus }}                 # Replaced with --focus value from CLI

Pass via ralph run my-ralph -- --dir ./src --focus "perf" (named flags)
Or positionally: ralph run my-ralph -- ./src "perf" (requires args: in frontmatter)
Missing args resolve to empty string

The loop¶

Each iteration:

Re-read RALPH.md from disk
Run all commands in order, capture output
Resolve {{ commands.* }} and {{ args.* }} placeholders
Pipe assembled prompt to agent via stdin
Wait for agent to exit
Repeat

Live editing¶

Everything is re-read from disk every iteration — edit files while the loop runs

Common patterns¶

Minimal ralph¶

---
agent: claude -p --dangerously-skip-permissions
---

Read TODO.md and implement the next task. Commit when done.

Self-healing with test feedback¶

---
agent: claude -p --dangerously-skip-permissions
commands:
  - name: tests
    run: uv run pytest -x
---

{{ commands.tests }}

Fix failing tests before starting new work.
Read TODO.md and implement the next task.

Parameterized ralph¶

---
agent: claude -p --dangerously-skip-permissions
args: [dir, focus]
---

Research the codebase at {{ args.dir }}.
Focus area: {{ args.focus }}.

ralph run research -- --dir ./api --focus "error handling"

Debug a single iteration¶

ralph run my-ralph -n 1 --log-dir ralph_logs
cat ralph_logs/001_*.log

Run on a branch¶

git checkout -b feature && ralph run my-ralph