Metadata-Version: 2.4
Name: ralph-workflow
Version: 0.8.20
Summary: Autopilot for coding agents — run Claude Code, Codex, OpenCode, Nanocoder, AGY & Pi unattended with verification, recovery, orchestration.
Project-URL: Homepage, https://ralphworkflow.com
Project-URL: Documentation, https://ralphworkflow.com/docs
Project-URL: Repository, https://codeberg.org/RalphWorkflow/Ralph-Workflow
Project-URL: Issues, https://codeberg.org/RalphWorkflow/Ralph-Workflow/issues/new
Project-URL: Community, https://codeberg.org/RalphWorkflow/Ralph-Workflow/issues
Project-URL: GitHub Mirror, https://github.com/Ralph-Workflow/Ralph-Workflow
Project-URL: Changelog, https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/CHANGELOG.md
Author: Mistlight
Maintainer: Mistlight
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: agent,agy,ai,ai-coding,autonomous-coding,claude-code,codeberg,codex,coding-agent,local-first,loop,loop-ecosystem,loop-engineering,multi-agent,nanocoder,ollama,opencode,orchestration,oss,overnight,pi,pipeline,quality-gate,ralph-loop,unattended,unattended-loop,vendor-neutral
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.12
Requires-Dist: ddgs>=9.14.0
Requires-Dist: gitpython>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: loguru>=0.7
Requires-Dist: mcp>=1.27.0
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.7
Requires-Dist: readability-lxml>=0.8.1
Requires-Dist: rich-click>=1.8
Requires-Dist: rich>=13.0
Requires-Dist: selectolax>=0.3.21
Requires-Dist: sentry-sdk>=2.0
Requires-Dist: tqdm>=4.66
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: bundle
Requires-Dist: pyinstaller>=6.0; extra == 'bundle'
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pydantic>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: readability-lxml>=0.8.1; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: selectolax>=0.3.21; extra == 'dev'
Requires-Dist: types-psutil>=5.9; extra == 'dev'
Requires-Dist: vulture>=2.16; extra == 'dev'
Provides-Extra: docs
Requires-Dist: linkify-it-py>=2; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-design>=0.5; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: web-search
Requires-Dist: brave-search-python-client>=0.4.27; extra == 'web-search'
Requires-Dist: exa-py>=2.12.0; extra == 'web-search'
Requires-Dist: tavily-python>=0.7.23; extra == 'web-search'
Description-Content-Type: text/markdown

<!--
  Review note (docs rubric §"Required review note for meaningful docs changes"):
  - What changed: this PyPI README now reads as a storefront, not a
    manual. The AGY section was collapsed to a one-sentence pointer
    (the smoke command with env var, parity-table excerpt, live
    regression test names/counts, and `tmp/agy-source-of-truth.txt`
    reference were all removed — they live in the Sphinx manual).
    The standalone "Idle watchdog" H2 was folded into Trust and
    safety as a one-line pointer. The "Install and run" and "Quick
    start" sections were collapsed into a single install-and-run
    block. The Documentation list was trimmed to four operator
    entries with contributor material under a sub-bullet. The
    rolling 30-day PyPI download clause was pruned (the date was
    2026-06-12 and refreshing it would require network-dependent
    level-2 verification); only the evergreen lifetime figure is
    retained. The Trust and safety block was widened with one-line
    pointers to the root README's full coverage (agent
    authentication, branch/worktree expectations, unattended
    approval implications, cost, human validation responsibility).
  - Why it belongs here: this file is the PyPI-facing README
    (`[project] readme = "README.md"` in pyproject.toml). PyPI
    readers want to know what the package is, whether it fits, and
    how to install it; deeper operator detail belongs in the
    Sphinx manual.
  - What was pruned, merged, or explicitly left alone: the AGY
    smoke command + parity table + live-regression test counts,
    the `tmp/agy-source-of-truth.txt` reference, the standalone
    "Idle watchdog" H2, the "Quick start" duplicate, the rolling
    30-day download clause, and several duplicate Documentation
    bullets were pruned. The supported-agents table is preserved
    because it is a single-page summary that PyPI readers want.
    The verbatim finish-receipt block is preserved here (PyPI
    readers may not click through to the manual).
  - How duplication was reduced or contained: root README is the
    single source for the full 6-step first-run block; this README
    repeats the trimmed 4-step version (install → init → write spec
    → run) for PyPI context and defers all deeper material via
    Sphinx links. The finish-receipt is preserved on PyPI but
    lives once on the root README in the maintained docs surfaces.
  - How the route is clearer now than before: what-it-is → who-it's-for →
    install-and-run → supported-agents → what-a-run-leaves-you →
    documentation → fit-or-not-fit → trust-and-safety → development →
    pro-support-pointer. Manual-depth technical detail is now reached
    only via Sphinx links, never duplicated on this page.
-->

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

[![PyPI](https://img.shields.io/pypi/v/ralph-workflow.svg)](https://pypi.org/project/ralph-workflow/)
[![PyPI downloads](https://img.shields.io/pypi/dm/ralph-workflow.svg)](https://pypi.org/project/ralph-workflow/)
[![Python](https://img.shields.io/pypi/pyversions/ralph-workflow.svg)](https://pypi.org/project/ralph-workflow/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

*Live lifetime PyPI downloads: [pepy.tech/projects/ralph-workflow](https://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:

```bash
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`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/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](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/diagnostics.md)
for what each check proves.

Depth presets:

```bash
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`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/agents.md)
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`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/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](https://ralphworkflow.com/blog/real-task-walkthrough-overnight-refactoring)
or browse the [first-run guide](https://ralphworkflow.com/start).

## Documentation

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

- **Quickstart:** [`docs/sphinx/quickstart.md`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/quickstart.md) —
  shorter repeat-use reference with commands and flags
- **Getting Started:** [`docs/sphinx/getting-started.md`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/getting-started.md) —
  fuller first-run walkthrough with task guidance
- **Configuration:** [`docs/sphinx/configuration.md`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/configuration.md) —
  config files and precedence
- **CLI Reference:** [`docs/sphinx/cli.md`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/cli.md) —
  all flags and sub-commands

Contributor material:

- **Modules Index:** [`docs/sphinx/modules.rst`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/modules.rst)
- **Developer Reference:** [`docs/sphinx/developer-reference.md`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/developer-reference.md)
- **Adding and managing agent support:** [`docs/agents/README.md`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/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:

  ```toml
  [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`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/README.md)
"Trust and safety" section.

## Development and verification

If you are changing Ralph Workflow itself, start with
[`CONTRIBUTING.md`](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/CONTRIBUTING.md)
and run the canonical verification command before you finish:

```bash
make verify
```

## Pro support (optional GUI layer)

[Ralph-Workflow-Pro](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/pro-support.md)
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](https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/docs/sphinx/pro-support.md)
page in the operator manual.
