# Ralphify

> The CLI 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.

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.

`RALPH.md` has YAML frontmatter (agent command, commands, args) and a prompt body with `{{ placeholders }}`. Each iteration: run commands, fill placeholders with output, pipe the assembled prompt to the agent, repeat. Fresh context every cycle.

## Quick install

```bash
uv tool install ralphify
```

Requires Python 3.11+ and an AI agent CLI (Claude Code recommended).

## The ralph format

A **ralph** is a directory containing a `RALPH.md` file. The frontmatter defines what to run; the body is the prompt.

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

{{ commands.tests }}

You are an autonomous coding agent running in a loop.
Fix failing tests before starting new work.
Read TODO.md and implement the next task.
```

Run it:

```bash
ralph run my-ralph         # loop until Ctrl+C
ralph run my-ralph -n 5    # run 5 iterations
```

Works with any agent CLI — swap `claude -p` for Codex, Aider, or your own.

## Why a format

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.

## Key features

- **Self-healing feedback loop**: Command output (test failures, lint errors) feeds into each iteration — the agent sees and fixes its own mistakes.
- **Live steering**: Edit `RALPH.md` while the loop runs. Changes take effect on the next iteration.
- **Fresh context every cycle**: No conversation bloat or hallucinated memories. The agent reads current codebase state each time.
- **Progress in git**: Every iteration commits to git. Roll back with `git reset` if needed.
- **Any agent**: Works with Claude Code, Aider, Codex CLI, or any CLI that reads stdin.
- **Shareable ralphs**: Ralphs are just directories — share via git repos, install with [agr](https://github.com/computerlovetech/agr).

## Placeholder types

- `{{ commands.<name> }}` — replaced with command output (stdout + stderr)
- `{{ args.<name> }}` — replaced with user argument values from CLI flags
- `{{ ralph.name }}` — ralph directory name
- `{{ ralph.iteration }}` — current iteration number (1-based)
- `{{ ralph.max_iterations }}` — total iterations if `-n` was set

## CLI commands

- `ralph run <path> [-n N] [--log-dir DIR] [--stop-on-error] [--timeout SEC] [--delay SEC]` — run the loop
- `ralph scaffold <name>` — scaffold a ralph from a template

## Python API

```python
from ralphify import run_loop, RunConfig, RunState
```

Embed the loop in automation pipelines. See the API docs for details.

## Documentation

- [Getting Started](https://ralphify.co/docs/getting-started/): Install to running loop in 10 minutes
- [How it Works](https://ralphify.co/docs/how-it-works/): Iteration lifecycle details
- [Using with Different Agents](https://ralphify.co/docs/agents/): Claude Code, Aider, Codex CLI setup
- [Cookbook](https://ralphify.co/docs/cookbook/): Copy-pasteable recipes for coding, docs, research
- [CLI Reference](https://ralphify.co/docs/cli/): All commands and options
- [Python API](https://ralphify.co/docs/api/): Programmatic usage
- [Quick Reference](https://ralphify.co/docs/quick-reference/): Cheat sheet
- [Troubleshooting](https://ralphify.co/docs/troubleshooting/): Common issues and fixes
- [Changelog](https://ralphify.co/docs/changelog/): Release history
- [Contributing](https://ralphify.co/docs/contributing/): How to contribute
- [Codebase Map](https://ralphify.co/docs/contributing/codebase-map/): Architecture and module guide

## Source

- PyPI: https://pypi.org/project/ralphify/
- GitHub: https://github.com/computerlovetech/ralphify
- Full docs for LLMs: https://ralphify.co/docs/llms-full.txt
