Installation

Prerequisites

Before installing Ralph Workflow, ensure your system meets the following requirements:

• Rust toolchain (for building from source) or a pre-built binary
• Git repository (Ralph integrates with git for version control)
• At least one AI coding agent installed (OpenCode, Claude Code, etc.)

Install via Cargo

The recommended way to install Ralph is via Cargo, the Rust package manager. This gives you access to the ralph command globally.

# Install Ralph Workflow
$ cargo install ralph-workflow --locked

# Verify the installation
$ ralph --version

Once installed, you can start using Ralph in any git repository. Navigate to your project and initialize with a work guide template:

$ cd my-project
$ ralph --init feature-spec

Created PROMPT.md from template
Ready to go! Edit PROMPT.md and run 'ralph' to start

Verify Installation

After installation, verify that Ralph can detect your AI agents and configuration:

$ ralph --diagnose

Ralph Workflow Diagnostics

 Ralph version: 0.1.0
 Git repository: detected
 Configuration: ~/.config/ralph-workflow.toml
 Available agents: opencode, ccs
 Developer fallback chain: configured
 Reviewer fallback chain: configured

All checks passed! Ralph is ready to use.

Initial Configuration

Ralph looks for configuration in two places: a global config at ~/.config/ralph-workflow.toml and a project-specific config at .ralph-workflow.toml in your project root.

# Example ~/.config/ralph-workflow.toml

# Maximum development iterations before stopping
max_dev_continuations = 5

# Maximum XSD validation retries
max_xsd_retries = 3

# Agent fallback chains
[developer]
fallback_chain = ["opencode", "ccs"]

[reviewer]
fallback_chain = ["ccs", "opencode"]

AI Agent Setup

Ralph supports multiple AI coding agents with automatic fallback between them. Configure your preferred agents in the fallback chain - Ralph will try each in order if one fails (due to rate limits, auth issues, etc.).

Next Steps

• Quick Start Guide - Run your first workflow in 5 minutes
• Core Concepts - Understand pipelines, checkpoints, and agents