Metadata-Version: 2.4
Name: ralph-workflow
Version: 0.8.5
Summary: Vendor-neutral AI coding workflow orchestration with unattended execution, recovery, and verification.
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
Author: Mistlight
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: agent,ai,multi-agent,orchestration,pipeline
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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: rich-click>=1.8
Requires-Dist: rich>=13.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: furo>=2024.8.6; 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'
Provides-Extra: web-visit
Requires-Dist: readability-lxml>=0.8.1; extra == 'web-visit'
Requires-Dist: selectolax>=0.3.21; extra == 'web-visit'
Description-Content-Type: text/markdown

# Ralph Workflow (Python)

> **Write the spec. Wake up to working software.**

Ralph Workflow is a Python 3.12+ CLI for spec-driven, unattended AI coding runs. You describe the task in `PROMPT.md`, point Ralph Workflow at the agent CLIs you already use, and let it run. When the workflow finishes, you come back to code changes, logs, artifacts, and review output you can inspect in your normal git workflow.

Ralph Workflow supports mixed-agent runs across planning, analysis, development, review, and commit phases. You might plan with Claude, route analysis through an OpenCode-backed GPT model, hand development to Codex or another OpenCode provider, and keep review on a different agent chain — all inside the same repo-native workflow.

For Claude-based runs, Ralph Workflow ships both a default `claude` transport and an explicit `claude-headless` transport. The headless path is the documented non-interactive option; deeper transport details for the default Claude path live in the reference docs rather than this onboarding README.

This package is a good fit when you want more than a demo. Ralph Workflow is designed for the kind of bounded engineering work that should leave you with a working feature, a verified refactor, a serious production-bound draft, or a reviewable implementation foundation.

## What you get

- **Spec-driven unattended runs** for real engineering work such as refactors, test generation, documentation sweeps, and migrations
- **Repo-native workflow files** instead of hidden product state
- **Agent-reviewed output** instead of a long interactive transcript
- **Flexible agent routing** across Claude Code, Codex CLI, OpenCode, and your own configured agents
- **Phase-by-phase model selection** so planning, analysis, development, review, and commit can each use the best-fit agent chain
- **Flexible Claude transport choices** including the explicit `claude-headless` path for documented non-interactive runs
- **A practical default workflow** you can use before inventing anything custom

## Install

### PyPI

```bash
pip install ralph-workflow
ralph --help
```

### pipx

```bash
python -m pip install pipx
python -m pipx ensurepath
pipx install ralph-workflow
ralph --help
```

### From source

```bash
git clone https://codeberg.org/RalphWorkflow/Ralph-Workflow.git
cd Ralph-Workflow/ralph-workflow
pip install -e .
ralph --version
```

Requires Python 3.12+.

## Before your first run

1. Install the agent CLIs you want Ralph Workflow to call.
2. Authenticate those CLIs normally.
3. Pick one small, concrete task for the first run.

Ralph Workflow does not manage provider authentication or store your agent credentials. You authenticate the agent CLIs yourself first, and Ralph Workflow then invokes those tools directly and supervises the workflow, even when different phases are routed through different agent families.

## Quick start

```bash
cd /path/to/your/project
ralph --init
ralph --diagnose
$EDITOR PROMPT.md
ralph
```

What happens in that flow:

- **`ralph --init`** creates the local `.agent/` support files.
- **`ralph --diagnose`** checks whether your configured agents and MCP setup are reachable.
- **`PROMPT.md`** becomes the task spec for the run.
- **`ralph`** directly invokes your configured agent CLIs and starts the unattended workflow.

After `ralph --init`, review the generated `.agent/` support files. If this repository needs a project-local main-config override, run `ralph --init-local-config` to create `.agent/ralph-workflow.toml`, then point the workflow at the agent CLIs you already use for planning, development, and review.

## What to expect from a run

Ralph Workflow is meant to get you to a strong implementation starting point while you are away, not to replace engineering judgment.

A good run should leave you with:

- code that compiles, tests, or clearly shows where work remains
- review artifacts and logs that explain what happened
- a result that is worth continuing from, not discarding and restarting

That may be a finished small task, or it may be a substantial first pass toward production on a larger one.

## Good first tasks

Start with work that is easy to verify:

- add tests to an existing module
- fix known lint failures
- refactor one narrow subsystem
- update documentation backed by existing code

## Depth presets

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

## When Ralph Workflow 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

## When it 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

## Where the name comes from

Ralph Workflow builds on the original Ralph idea: repeat a strong prompt until the model can make real progress. That loop was simple and powerful. In practice, Ralph Workflow is the Ralph loop on steroids: planning before implementation, verification after development, agent fallbacks, agent-agnostic execution, and customizable pipelines so unattended runs keep moving and teams can review the results with confidence.

## Development and verification

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

```bash
make verify
```

## Documentation

Use the website and docs for the deeper material this README intentionally leaves out:

- **Homepage:** <https://ralphworkflow.com>
- **Docs:** <https://ralphworkflow.com/docs>
- **Documentation map:** [`../docs/README.md`](../docs/README.md)
- **Maintained Sphinx docs:** [`docs/sphinx/`](docs/sphinx/)
- **Quickstart:** [`docs/sphinx/quickstart.md`](docs/sphinx/quickstart.md)
- **Developer reference:** [`docs/sphinx/developer-reference.md`](docs/sphinx/developer-reference.md)
- **Python API reference:** [`docs/sphinx/modules.rst`](docs/sphinx/modules.rst)
- **Source repository:** <https://codeberg.org/RalphWorkflow/Ralph-Workflow>
- **Issue tracker:** <https://codeberg.org/RalphWorkflow/Ralph-Workflow/issues/new>

## License

[AGPL-3.0-or-later](LICENSE).

The framework is copyleft. The code Ralph Workflow generates belongs to you — no license encumbrance on outputs. Use it commercially. Use it privately. Use it however you want.
