ralph-workflow 0.8.23

An autonomous coding-agent orchestrator: hand off a well-specified task and return to reviewable, tested work.

ralph-workflow

Ralph Workflow is a free, open-source orchestrator for AI coding agents. Hand it a well-specified task, let agents plan, build, verify, and fix, and come back to reviewable, tested work.

Install

pipx install ralph-workflow
ralph --version
ralph --diagnose   # optional pre-flight check

pipx keeps the install isolated from your other Python projects; the post-condition is that ralph --version prints the installed package version.

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, v1.0.9+).
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. The selection and trust-boundary story is in the maintained Sphinx manual under 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://codeberg.org/RalphWorkflow/Ralph-Workflow
• PyPI: https://pypi.org/project/ralph-workflow/
• Issue tracker: https://codeberg.org/RalphWorkflow/Ralph-Workflow/issues/new
• Contribution route: CONTRIBUTING.md