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
pipx install ralph-workflow
ralph --version
pipx keeps the install isolated from your other Python projects; the
post-condition is that ralph --version prints the installed package
version. pip install ralph-workflow also works.
First run
- Install Ralph Workflow (
pipxorpip, 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.
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
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.9.tar.gz.
File metadata
- Download URL: ralph_workflow-0.9.9.tar.gz
- Upload date:
- Size: 2.2 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7903d8de8daa039544b566d31023c8c1fb1ecc05c1729b2e0ffe3af7c03098e4
|
|
| MD5 |
5ba5cd548424da1adf2e3b7dd2dd4487
|
|
| BLAKE2b-256 |
2e6b4803bb8746b1fa07564c7ae213ada25d9a3782bf393aaf2a4f17be064af0
|
File details
Details for the file ralph_workflow-0.9.9-py3-none-any.whl.
File metadata
- Download URL: ralph_workflow-0.9.9-py3-none-any.whl
- Upload date:
- Size: 2.9 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
210e5e067289d94b320e209f6861d8d872c45853a1ba1527be1476e44df8f641
|
|
| MD5 |
ee89b8b0cd933aad69fec66b617a18cd
|
|
| BLAKE2b-256 |
e90b532f33c67843839080287b91cd54492d4b8622d97c1a03ee8fa8ea5b1f6b
|
