ralph-workflow 0.8.0b1

Ralph Workflow is an unattended multi-agent AI development workflows with extensive customization options based on the original Ralph concept.

Ralph Workflow (Python)

Ralph Workflow is a Python 3.12+ CLI for unattended multi-agent development loops. The installable package lives in this directory and exposes two entry points:

• ralph — the main CLI
• ralph-mcp — the standalone MCP server runtime

Install

PyPI

pip install ralph-workflow
ralph --help

pipx

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

Development install

make dev
ralph --version

Refresh the runnable executable from this checkout

make install
ralph --version

make install updates the current Python environment and, when pipx is available, force-refreshes the pipx-managed ralph executable so it points at the current checkout instead of a stale deleted worktree.

Quick start

cd /path/to/your/project
ralph --init feature-spec
# edit PROMPT.md
ralph

Verification

make verify

That runs:

• ruff check ralph/ tests/
• mypy ralph/
• pytest tests/ -v --cov=ralph --cov-report=term-missing --cov-report=html

For the dead-code policy tooling, run the separate Vulture audit:

make dead-code

It is intentionally separate from make verify while the current dead-code backlog still exists; today the command proves the scanner wiring by failing on the code that still needs cleanup.

Package map

• ralph/cli/ — Typer CLI entry points and command plumbing
• ralph/config/ — layered config loading and Pydantic models
• ralph/pipeline/ — state, events, reducer, orchestrator, effects
• ralph/phases/ — phase handlers and dispatch
• ralph/agents/ — agent registry, chains, and invocation
• ralph/mcp/ — MCP bridge, artifact handling, standalone server runtime
• ralph/git/ — GitPython-backed repository helpers and rebase support
• ralph/workspace/ — production and in-memory filesystem abstractions

Pydoc-first API reference

The public package docstrings are intended to stand on their own. Useful entry points:

python -m pydoc ralph
python -m pydoc ralph.cli
python -m pydoc ralph.pipeline
python -m pydoc ralph.mcp
python -m pydoc ralph.git
python -m pydoc ralph.workspace

Use package/module docstrings for API understanding and this README for workflow-level guidance.

Phase-output hardening

Ralph now treats several agent-driven phases as producing explicit evidence, not just a zero exit code.

• development must leave behind a fresh .agent/artifacts/development_result.json.
• review must leave behind a fresh .agent/artifacts/issues.json.
• fix must leave behind a fresh .agent/artifacts/fix_result.json.
• The runner removes those per-phase artifacts before each invocation so a later interrupted run cannot silently reuse stale output from an earlier pass.

This hardening is intentionally strict. It adds complexity, but it closes a real unattended-mode failure class where a provider could exit successfully, emit no meaningful work, and still let the pipeline advance because an old artifact was still present on disk.

Claude/CCS MCP safety note

Claude-compatible transports such as claude and ccs run through a stricter MCP path. Ralph still uses --mcp-config plus --strict-mcp-config, but it only emits --tools "" / --allowedTools ... when live MCP tool discovery succeeds with a non-empty allowlist. That avoids a brittle edge case in non-interactive Claude/CCS runs where empty-tool configurations and MCP bootstrapping can produce misleadingly successful no-op executions.

Parallel mode

When your planning phase produces two or more work units, Ralph fans development out across multiple git worktrees simultaneously. Configure it in your pipeline policy:

[pipeline.parallel_execution]
max_parallel_workers = 4
max_work_units = 50

See docs/agents/parallelization.md for the full guide.