ralph-workflow 0.8.20

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 session-health data, performance metrics, coarse failure outcomes, and usage metadata to help fix bugs, improve product quality, and understand which features operators actually use. The data is used only to operate and improve Ralph Workflow, including prioritizing fixes and informing users about useful product capabilities. It is never sold. It is not rented or shared for advertising. 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 aggregate session-health and usage analytics. A fresh random session identifier is generated on every run.

What we collect (anonymous metadata only):

• Anonymous installation and session identity: a random 32-character installation ID and a fresh random session ID for each run. This supports aggregate active-user and session-health analysis without names, emails, IP addresses, or account identifiers.
• Operating system, architecture, and environment markers (CI, container, WSL, Codespaces, SSH session, package manager). ci and container are also emitted as dedicated boolean tags for aggregate filtering — the values are always bool, never env-var strings.
• 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).
• Which CLI command or subcommand was invoked (closed vocabulary: the registered subcommand name or the literal "pipeline" for the default run path — never free-text user input).
• Pipeline phase telemetry: which phase role ran (closed 8-value set: execution / analysis / review / commit / verification / terminal / fanout_join / commit_cleanup), how long it took (whole-second int), and a coarse outcome (success / failure / skipped / crashed). Aggregated per run and flushed once at session end.
• Coarse UTC time-of-day buckets (hour of day 0-23, day of week 0-6, weekday/weekend bool) for aggregate usage analytics — no full timestamp and no local timezone string is forwarded.
• Sentry release-health, tracing, breadcrumbs, and custom metrics derived only from the metadata above. For example, Ralph Workflow emits session counts, session duration, phase counts, and phase duration with closed-vocabulary attributes such as success, failure, and phase role. Sentry automatic integrations are disabled, so tracing is limited to the manual ralph.session transaction and these metadata-only events.

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.
• Raw phase names (only the closed-vocabulary role is recorded).
• Full timestamps or timezone names (only coarse UTC buckets).
• Application logs, replay recordings, user-feedback text, feature-flag payloads, profiling stack samples, or arbitrary user-authored strings. Ralph Workflow does not enable Sentry log capture or profiling by default because logs and stack samples can contain prompts, paths, model output, or codebase details outside the metadata-only contract.
• The codebase identity — phase telemetry is keyed on the closed-vocabulary role, never the user-customizable phase name from pipeline.toml.

How to opt out:

• 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.

• Or set this in ~/.config/ralph-workflow.toml (or $XDG_CONFIG_HOME/ralph-workflow.toml) for a user-wide opt-out, or in .agent/ralph-workflow.toml for a project-local opt-out:

  [general]
  telemetry_enabled = false
  

  The config-file setting is read before Sentry initialization and before anonymous user-id lookup.

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 telemetry_enabled = false in your user-global or project-local ralph-workflow.toml, or 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.