ralph-workflow

Ralph Workflow is a free, open-source AI agent orchestrator for coding work. You give it one well-specified task; it runs a Ralph loop (plan → build → verify → fix) with your chosen coding agent, then you come back to inspect the result. Adopt the default workflow as-is first; extend it later.

It fits developers and small teams with work that is too big to babysit and too risky to trust blindly. It is not for vague prompts or repos without tests or other guardrails.

Install

From a checkout, choose the build you need:

cd ralph-workflow
make install       # self-contained manual snapshot; rdev --version ends in -build
make dev           # self-contained development snapshot; rdev --version ends in -dev
make stable        # published release; ralph --version has no local suffix

make install and make dev copy the checkout and its bundled templates to their own snapshot, so rdev does not depend on the cloned repository. Before any install changes files, Ralph Workflow detects an existing global ralph: in a terminal, choose continue, remove a pipx/uv-tool install, or abort. Non-interactive conflicts abort safely.

Use pipx install ralph-workflow or pip install ralph-workflow only when the Makefile workflow is unavailable.

First run

Install Ralph Workflow with the build that fits your workflow (above).
In your project: ralph --init — creates user-global config and a starter PROMPT.md; it does not create .agent/. Advanced project-local overrides are explicit opt-in via ralph --init-local-config (alias: ralph --generate-local-config).
Confirm a supported agent CLI is on your PATH and authenticated (ralph --list-agents).
Run ralph --diagnose and fix any reported problem until every line is green.
Edit PROMPT.md with the outcome and checks you expect. Remove the  sentinel at the top — Ralph Workflow refuses to run while it remains. Or, before PROMPT.md exists, seed a task-shaped starter with ralph --init feature-spec, guardrail, refactor, test-coverage, or docs.
Run ralph. When it finishes, read the summary of what changed and which checks passed, then verify the feature yourself.

The canonical first-run walkthrough is Getting started. For agent-specific model-string formats, see Agent compatibility. For configuration after the first run, open the operator manual.

Supported agents

Eight built-in agents ship with Ralph Workflow:

Agent	Notes
Claude Code	Anthropic's CLI for Claude (interactive, PTY transport).
Claude Code (Headless)	Same `claude` binary in headless subprocess mode (`claude-headless`).
Codex	OpenAI's Codex CLI.
OpenCode	Open-source terminal coding agent.
Nanocoder	Local-only TUI coding agent.
Google Anti Gravity (AGY)	Google's Antigravity CLI (`agy`). Re-check after AGY updates.
Pi	Minimal coding agent. Headless mode is `pi --mode json <prompt>`.
Cursor	Cursor Agent CLI (`agent`), headless `--print` mode.

Pick one, authenticate it on your machine once, and Ralph Workflow uses it. Selection and trust-boundary details are in agents and agent-compatibility.

Requirements

Python ≥ 3.12
Local execution; no daemon, no cloud dependency
One supported agent CLI installed and authenticated

License

AGPL-3.0-or-later.

Documentation

The maintained operator manual is at docs/sphinx/index.rst — tutorial, configuration reference, MCP / artifact / pipeline configuration, concepts, troubleshooting, diagnostics, and developer internals.

Project home

Repository: https://github.com/Ralph-Workflow/Ralph-Workflow
PyPI: https://pypi.org/project/ralph-workflow/
Issue tracker: https://github.com/Ralph-Workflow/Ralph-Workflow/issues/new
Contribution route: CONTRIBUTING.md

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ralph_workflow-0.9.11.tar.gz (2.2 MB view details)

Uploaded Aug 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ralph_workflow-0.9.11-py3-none-any.whl (2.9 MB view details)

Uploaded Aug 3, 2026 Python 3

File details

Details for the file ralph_workflow-0.9.11.tar.gz.

File metadata

Download URL: ralph_workflow-0.9.11.tar.gz
Upload date: Aug 3, 2026
Size: 2.2 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.14.5

File hashes

Hashes for ralph_workflow-0.9.11.tar.gz
Algorithm	Hash digest
SHA256	`8fb2a6415cd31497f3b4cf44a02e4e41d9afe1c08e339e81d956fa19a4ec47b8`
MD5	`ec79ad9c3fe697437976024b2f586801`
BLAKE2b-256	`9da4172d7f3d55d488c55dbe5f3b6ba276dcb4ed53a049765c608d9c9ebfb59e`

See more details on using hashes here.

File details

Details for the file ralph_workflow-0.9.11-py3-none-any.whl.

File metadata

Download URL: ralph_workflow-0.9.11-py3-none-any.whl
Upload date: Aug 3, 2026
Size: 2.9 MB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.14.5

File hashes

Hashes for ralph_workflow-0.9.11-py3-none-any.whl
Algorithm	Hash digest
SHA256	`3d79e13c117bf144b5314ff39663af7357217bd16c8fe8fef72c1a24c169660f`
MD5	`18ffdbcc762fefeb6d0c5eff56cefa74`
BLAKE2b-256	`0d93ef0de173393112ee6b8740083b3253afaab2321fcf0eed124061fd15ec93`