Metadata-Version: 2.4
Name: ralph-workflow
Version: 0.9.5
Summary: An autonomous coding-agent orchestrator: hand off a well-specified task and return to reviewable, tested work.
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,ai,coding,orchestration
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: packaging>=23.0
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.7
Requires-Dist: pygments>=2.18
Requires-Dist: questionary>=2.0
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: pathspec>=1.0.4; 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

# 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

```bash
pipx install ralph-workflow
ralph --version
```

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

## First run

The complete first-run path is six short steps and does not require
opening any other config file before your first run.

1. **Install Ralph Workflow.** Use `pipx install ralph-workflow` (or
   `pip install ralph-workflow`).
2. **Start in your project.** `cd /path/to/your/project` and run
   `ralph --init`. It creates your user-global config and a `PROMPT.md`;
   project-local config is optional later via `ralph --init-local-config`.
3. **Confirm a coding agent.** Ralph Workflow looks for supported agents
   already on your `PATH` and enables the ones it finds. Install and
   authenticate an agent first if none are found.
4. **Check the setup.** Run `ralph --diagnose` and fix any reported
   problem before starting work.
5. **Describe the task.** Edit `PROMPT.md` with the outcome and checks
   you expect. For a task-shaped starter, use `ralph --init feature-spec`,
   `guardrail`, `refactor`, `test-coverage`, or `docs` before a prompt
   file exists.
6. **Run Ralph Workflow.** Run `ralph`, then read the finish-receipt
   artifact: it names the change, checks run, and review focus before you
   decide what to do next.

The canonical first-run walkthrough — with screenshots of the bundled
config layout, the per-agent model-string cheat sheet, and what each
diagnostic flag actually checks — is in
[Getting started](docs/sphinx/getting-started.md). It is the single
home for the first-run sequence and does not require opening any other
config file before your first run.

## 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](docs/sphinx/index.rst) under
[agents](docs/sphinx/agents.md) and
[agent-compatibility](docs/sphinx/agent-compatibility.md).

## 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`](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`](CONTRIBUTING.md)
