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.
my-loop/
├── RALPH.md
├── scripts/
│ └── run-tests.sh
└── docs/
└── conventions.mdWhat 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.Why Ralph Loops?
Portable across tools
A directory plus one file. Any compatible runtime can load it.
Bundled context
Scripts, prompts, fixtures, and reference docs travel with the loop.
Git-native
Version, diff, and review loops like any other code artifact.
Reusable
Share loops across projects, teams, and tools without rewriting them.
Inspectable
Plain markdown and plain files. Humans can read every byte.
Beyond chat
Stop pasting giant prompts into chat windows that forget them.
How it works
-
1
Author a loop directory
Create a folder with a
RALPH.mdfile and any supporting scripts or docs the loop needs. -
2
Runtime discovers RALPH.md
A compatible runtime locates the package, parses its metadata, and reads the loop instructions.
-
3
Runtime executes the loop
The agent loops over the instructions with bundled resources resolved relative to the package root.
For creators
Authoring a Ralph Loop means deciding what the agent should do, then packaging everything it needs beside the instructions.
- Instructions in
RALPH.md - Validation and test commands
- Templates and checklists
- Reference docs and examples
- Scripts the agent can invoke
- Fixtures and sample inputs
For runtime authors
The specification defines everything a runtime needs to load and execute loops.
- Locate
RALPH.md - Parse optional YAML frontmatter
- Read the markdown body as instructions
- Expand
{{ commands.* }}and{{ args.* }}templates - Resolve bundled files relative to the package root
Examples
Six reference loop packages shipped with the specification repo.
improve-codebase
Continuously find and fix code quality issues.
bug-hunter
Reproduce, localize, and patch reported bugs.
raise-coverage
Add focused tests to lift coverage on under-tested modules.
refactor-module
Refactor a single module against a set of invariants.
write-docs
Generate and revise documentation for existing code.
dependency-updater
Upgrade dependencies one at a time with tests green.
Inspiration
Ralph Loops draws from Geoffrey Huntley’s Ralph loop methodology (the concept of autonomous loops with deterministic feedback) and Agent Skills (the directory-based packaging philosophy). It applies both to a different problem: iterative autonomous loops with feedback commands, not one-shot agent skills.
The format evolves through public discussion in the ralphloops/ralphloops repository.