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

  1. Install Ralph Workflow with the build that fits your workflow (above).
  2. 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).
  3. Confirm a supported agent CLI is on your PATH and authenticated (ralph --list-agents).
  4. Run ralph --diagnose and fix any reported problem until every line is green.
  5. Edit PROMPT.md with the outcome and checks you expect. Remove the <!-- ralph:starter-prompt ... --> 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.
  6. 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

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.9.27)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ken.ralphworkflow from gravatar.com ken.ralphworkflow

Credits

Author/Maintainer: Mistlight

License

GNU Affero General Public License v3 or later (AGPLv3+) (AGPL-3.0-or-later)

Requires

Python >=3.12

Provides Extra

bundle dev docs web-search

Tags

agent ai coding orchestration

Classifiers

Report project as malware

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.10.tar.gz (2.2 MB view details)

Uploaded Source

Built Distribution

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

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

Uploaded Python 3

File details

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

File metadata

  • Download URL: ralph_workflow-0.9.10.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

Hashes for ralph_workflow-0.9.10.tar.gz
Algorithm Hash digest
SHA256 9532c44b9bac53972f14cb5222674cd4c199c6eed66ce9f3ed912404a2486f94
MD5 85fc7605a4717c327e6b4f3402300438
BLAKE2b-256 3f53ec9afe9078297c19250d819c671625cd354d0a100fb16167b6d7b681577e

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ralph_workflow-0.9.10-py3-none-any.whl
Algorithm Hash digest
SHA256 d2b1fdc0ff8dfccfafd0c4d2049f61facbeef8e66562e1f77592a1c0da95ed12
MD5 f756861261664293b5274ec779cb3824
BLAKE2b-256 11b09c568bc08f65f445d257abb50e0a7df7c881a73343aea76bfc033f58cf44

See more details on using hashes here.

Release history Release notifications | RSS feed

0.9.27

2 files

0.9.26

2 files

0.9.25

2 files

0.9.24

2 files

0.9.23

2 files

0.9.21

2 files

0.9.20

2 files

0.9.19

2 files

0.9.18

2 files

0.9.17

2 files

0.9.16

2 files

0.9.15

2 files

0.9.14

2 files

0.9.13

2 files

0.9.12

2 files

0.9.11

2 files

This release

0.9.10 This release

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.1

2 files

0.9.0

2 files

0.8.27

2 files

0.8.25

2 files

0.8.24

2 files

0.8.23

2 files

0.8.22

2 files

0.8.21

2 files

0.8.20

2 files

0.8.19

2 files

0.8.18

2 files

0.8.17

2 files

0.8.16

2 files

0.8.15

2 files

0.8.14

2 files

0.8.13

2 files

0.8.12

2 files

0.8.11

2 files

0.8.10

2 files

0.8.9

2 files

0.8.8

2 files

0.8.7

2 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

Pre-release

0.8.4b0

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

Pre-release

0.8.0b8

2 files

Pre-release

0.8.0b7

2 files

Pre-release

0.8.0b6

2 files

Pre-release

0.8.0b5

2 files

Pre-release

0.8.0b4

2 files

Pre-release

0.8.0b3

2 files

Pre-release

0.8.0b1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page