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 on Linux, macOS, or WSL, with uv 0.7.0 or newer, 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. They
install rdev only: an existing global ralph is reported and left untouched,
and rdev is used instead. Any rdev from an earlier dev build is replaced.
make stable owns the global ralph, so before it changes files you choose in
a terminal to continue, remove a pipx/uv-tool install, or abort; non-interactive
conflicts abort safely.
On native Windows, use the published package: pipx install ralph-workflow or
pip install ralph-workflow. The checkout installer is a POSIX/WSL workflow.
For its locked, serialized, rollback-capable refresh contract and failure modes,
see CONTRIBUTING.md.
First run
- Install Ralph Workflow with the build that fits your workflow (above).
- In your project:
ralph --init— creates user-global config and a starterPROMPT.md; it does not create.agent/. Advanced project-local overrides are explicit opt-in viaralph --init-local-config(alias:ralph --generate-local-config). - Confirm a supported agent CLI is on your
PATHand authenticated (ralph --list-agents). - Run
ralph --diagnoseand fix any reported problem until every line is green. - Edit
PROMPT.mdwith the outcome and checks you expect. Remove the<!-- ralph:starter-prompt ... -->sentinel at the top — Ralph Workflow refuses to run while it remains. Or, beforePROMPT.mdexists, seed a task-shaped starter withralph --init feature-spec,guardrail,refactor,test-coverage, ordocs. - 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.
Auto-integration ownership
Ralph Workflow refreshes the configured mainline before integration seams. The worktree
that owns that branch is infrastructure: with the default configuration Ralph Workflow
may snapshot and reset its uncommitted content to keep the mainline current.
Recover discarded contents with
git -C <target-owner-path> restore --source=<snapshot-ref> --staged --worktree ..
Snapshots remain under refs/ralph-reclaim/<target>/...; feature worktrees are never reclaimed. Set
auto_integrate_reclaim_target_worktree = false in ralph-workflow.toml to
keep the older refuse-and-retry behavior. See the
configuration reference for
all six settings.
Supported agents
Nine 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. |
| Kimi | Kimi Code CLI (kimi), headless -p <prompt> + --output-format stream-json; kimi/<model> aliases use full configured IDs. |
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
uv≥ 0.7.0 for checkout and stable Makefile installs- 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
1 maintainer
Metadata
1 maintainer
Release files for ralph-workflow 0.9.28
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ralph_workflow-0.9.28.tar.gz | 2.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ralph_workflow-0.9.28-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 6.5 MB
Release files / ralph_workflow-0.9.28.tar.gz
| Download URL | ralph_workflow-0.9.28.tar.gz |
|---|---|
| Size | 2.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a228cd7537c71b5dd8f291eb4e66cc8ffda836a8174db6b274e0eccab285d6b5
|
|
BLAKE2b-256 checksum How to use checksums |
25f8574181955fe5976df7b1da40addd7d5786a8583f5b7a5cd399b0dbf7d51a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / ralph_workflow-0.9.28-py3-none-any.whl
| Download URL | ralph_workflow-0.9.28-py3-none-any.whl |
|---|---|
| Size | 3.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b7fe326c706dd903256d53f83b5bdce0de8185498f046b79b04e6f4845e4fef2
|
|
BLAKE2b-256 checksum How to use checksums |
cbbb44897e2946e1a09bdedab5fc3dc8b9e223c6d2f9b0cf7f29a294e3a18904
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
