Ralph Loops

A minimal, open format for packaging autonomous agent loops as portable directories.

Define the task, feedback commands, and constraints in a RALPH.md file. Bundle scripts and docs alongside it. Any compatible runtime can execute it.

Read the spec GitHub

my-loop/
├── RALPH.md
├── scripts/
│   └── run-tests.sh
└── docs/
    └── conventions.md

What is a Ralph Loop?

A Ralph Loop is a self-contained directory package that describes an autonomous agent loop. Every package has one required entrypoint file — RALPH.md — and may bundle any supporting scripts, prompts, templates, fixtures, or reference docs beside it.

Compatible runtimes discover RALPH.md, run the specified agent, execute commands, and inject args into the loop instructions.

The format is deliberately small. It does not mandate a runtime, an execution engine, or a single metadata schema beyond a tiny required core.

---
agent: claude -p --dangerously-skip-permissions
commands:
  - name: tests
    run: uv run pytest -x
  - name: types
    run: uv run ty check
  - name: lint
    run: uv run ruff check .
args:
  - focus
---

# Bug Hunter

Find and fix a real bug in this codebase.
{{ args.focus }}

## Test results
{{ commands.tests }}

## Type checking
{{ commands.types }}

## Lint
{{ commands.lint }}

Each iteration:
1. Read code — look for edge cases,
   missing validation, or logic errors.
2. Write a failing test to prove the bug.
3. Fix the bug with a minimal change.
4. Verify all existing tests still pass.