ralph-workflow 0.8.19

Autopilot for coding agents — run Claude Code, Codex, OpenCode, Nanocoder, AGY & Pi unattended with verification, recovery, orchestration.

Ralph Workflow — the autopilot for coding agents

Codeberg is primary. Star, watch, fork, and report issues there first: https://codeberg.org/RalphWorkflow/Ralph-Workflow (verify: repo-exists) GitHub is a read-only mirror: https://github.com/Ralph-Workflow/Ralph-Workflow (verify: repo-exists)

Ralph Workflow is the autopilot for coding agents — a free and open-source operating system for autonomous coding, an AI agent orchestrator built around a simple Ralph-loop core that becomes powerful through composition.

Hand it a well-specified coding task, let the agents plan, build, verify, and fix, and come back to reviewable, tested work.

The default workflow is strong enough to adopt as-is, before you customize anything.

Live lifetime PyPI downloads: pepy.tech/projects/ralph-workflow (audited 2026-06-30; no hardcoded number — refresh the page for the current count).

What it is

Ralph Workflow is an operating system for autonomous coding: the agents handle the long middle of engineering work while you handle the judgment that only a human can make. Hand it a well-specified coding task, let the agents plan, build, verify, and fix, and come back to reviewable, tested work.

The simple Ralph-loop idea — plan, build, verify — becomes a composable loop framework under the hood: each phase can loop independently and hand off to the next, so a single ralph command spawns planning, development iteration, review, and fix cycles across multiple agents and then produces finished git commits you can review when you come back.

Who it's for

Ralph Workflow is for developers and small teams with engineering work that is too big to babysit and too risky to trust blindly — the kind of ambitious, well-specified work that you would trust a capable colleague to do unattended. It runs the agents you already use — Claude Code, Codex, OpenCode, Nanocoder, Google Anti Gravity, and Pi — on your own machine, with your keys to yourself.

It is not for one-line fixes, vague prompts, or repos without tests. A repo without guardrails will produce results that reflect that.

Install and run

The fastest PyPI install:

pipx install ralph-workflow

The full first-run path (install → init → write PROMPT.md → run → review) is the single source of truth in the root README.md — see the "Start your first run" section. PyPI readers should follow the root README for the 6-step walkthrough; this README intentionally leaves out the deeper operator material to avoid drift between the two surfaces.

ralph --init also auto-symlinks the bundled skill bundle into the supported agent roots and seeds a batteries-included .gitignore covering Python, Node, Rust, Go, Ruby, PHP, Java/Kotlin, .NET, Dart/Flutter, Elixir, Scala, Terraform, and common IDE/OS patterns. Run those commands from a human-operated shell outside any Ralph-managed agent session.

Before your first run: install the agent CLIs you want Ralph Workflow to call, authenticate them normally, and pick one small concrete task. ralph --diagnose is the optional pre-flight check — it verifies your agent CLIs, MCP servers, and capability bundles are healthy before you spend a real run on them. See the diagnostics page for what each check proves.

Depth presets:

ralph -Q     # quick: small fixes, single iteration
ralph        # standard: most features and tasks
ralph -T     # thorough: complex refactors, ten iterations

Supported agents

Ralph Workflow ships with first-class support for six user-facing agent CLIs: Claude Code, Codex, OpenCode, Nanocoder, Google Anti Gravity, and Pi. Each agent has a documented end-to-end verification path in the Sphinx manual; see the agents page for the canonical details.

Agent	Description
Claude Code	Anthropic's CLI for Claude. The canonical reference agent.
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>.

What a run leaves you

The finish-receipt handoff is documented as the single source of truth in the root README.md "What a run leaves you" section — the verbatim receipt, the bundled-example reference, and the sample unedited terminal captures all live on the root README so PyPI readers and forge readers see the same proof.

Want to follow a full first run? Read the real-task walkthrough or browse the first-run guide.

Documentation

This README intentionally leaves out deeper implementation details and defers to the Sphinx operator manual for those.

• Quickstart: docs/sphinx/quickstart.md — shorter repeat-use reference with commands and flags
• Getting Started: docs/sphinx/getting-started.md — fuller first-run walkthrough with task guidance
• Configuration: docs/sphinx/configuration.md — config files and precedence
• CLI Reference: docs/sphinx/cli.md — all flags and sub-commands

Contributor material:

• Modules Index: docs/sphinx/modules.rst
• Developer Reference: docs/sphinx/developer-reference.md
• Adding and managing agent support: docs/agents/README.md

When Ralph Workflow fits (and when it doesn't)

Fits:

• Multi-step tasks that outgrow one prompt
• Work you want to review after the fact instead of steering live
• Teams that want AI execution to stay in the repo
• Runs where you want to mix stronger and cheaper models by phase

Does not fit:

• One-shot interactive prompts
• Pair-programming sessions with constant human steering
• Tiny tasks where setup overhead is not worth it
• Workflows that need unpredictable mid-run human input

Privacy & Error Reporting

Ralph Workflow sends anonymous, metalevel crash reports and performance metrics to help fix bugs and improve reliability. No personal data is collected, and nothing about the project you are working on ever leaves your machine.

Each installation generates a random 32-character identifier stored in $XDG_CONFIG_HOME/ralph-workflow-user.ini when XDG_CONFIG_HOME is set, falling back to ~/.config/ralph-workflow-user.ini otherwise. This identifier is not tied to your name, email address, IP address, or any other personal data — it is a random string used only to distinguish different installations in crash reports. A fresh random session identifier is generated on every run.

What we collect (anonymous metadata only):

• Operating system, architecture, and environment markers (CI, container, WSL, Codespaces, SSH session, package manager).
• Python and Ralph Workflow versions (e.g. Python 3.12.5, Ralph Workflow 0.8.18).
• Whether you are running inside a virtualenv (boolean only — the virtualenv path is never sent).
• Session timing (start, duration) and a coarse exit outcome (success / failure / interrupted / unknown for utility invocations).

What we never collect:

• Your prompts, inline arguments, or any other user input.
• The current working directory, argv, config path, or any other filesystem location tied to your codebase.
• Stack-frame absolute paths — these are stripped to basenames before being sent, so the codebase you are working on is never identified.
• Hostnames, usernames, environment-variable values, or any other personally identifying detail.

How to opt out (set the environment variable before invocation):

• Set RALPH_DISABLE_TELEMETRY=1 (any of 1, true, yes, on, case-insensitive). When this variable is set, the CLI skips every sentry call — initialization, the atexit finalize, the session outcome setter, and the user-id lookup — so no telemetry data leaves the process. This is the only supported opt-out.

Note: the identity file at $XDG_CONFIG_HOME/ralph-workflow-user.ini (or ~/.config/ralph-workflow-user.ini) only holds a random, anonymous installation identifier used to distinguish sessions. It is not itself an opt-out — if the file is missing, Ralph Workflow will create a new random ID on the next run only when telemetry is enabled. To disable telemetry permanently, set RALPH_DISABLE_TELEMETRY in your shell profile or CI environment.

Community

Already installed? Run ralph star from your terminal to open the primary repo, or visit https://codeberg.org/RalphWorkflow/Ralph-Workflow. Codeberg is primary — star, watch, fork, and open issues there first; GitHub is a read-only mirror. Stars are the only signal we get that Ralph Workflow is working for you, and they set what we build next.

Trust and safety

Ralph Workflow runs locally on your own machine and does not upload your code or data to a cloud service. For the full coverage of trust and safety boundaries (agent authentication, branch/worktree expectations, unattended approval implications, cost, and human validation responsibility), see the root README.md "Trust and safety" section.

Development and verification

If you are changing Ralph Workflow itself, start with CONTRIBUTING.md and run the canonical verification command before you finish:

make verify

Pro support (optional GUI layer)

Ralph-Workflow-Pro is an optional GUI layer that runs the engine as a subprocess. For the engine-side contract and the default-factory wiring, see the Pro support page in the operator manual.