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. 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.
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 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
- 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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ralph_workflow-0.9.23.tar.gz.
File metadata
- Download URL: ralph_workflow-0.9.23.tar.gz
- Upload date:
- Size: 2.7 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
308e079ae26e30765f7e8aed34cdc8a9061f4f9a7e231f3c4c7f4961ece9f615
|
|
| MD5 |
380f6f55b07fcdd5706521b38c7d2a56
|
|
| BLAKE2b-256 |
20d59abc7e4af5cf34b48fd715bc3163483d8960595b55c7ac252dc92a6484a5
|
File details
Details for the file ralph_workflow-0.9.23-py3-none-any.whl.
File metadata
- Download URL: ralph_workflow-0.9.23-py3-none-any.whl
- Upload date:
- Size: 3.4 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
92b7ff35bd909f856f55bf69f3079ffd39f4106e4188fcb46d1177d165bda6e2
|
|
| MD5 |
353c0e9b7280916c91f590d272126d3f
|
|
| BLAKE2b-256 |
e6174e49f4d547570d989777bdb081d2156e468e5834a200c115c895e9467b28
|
