### Setup Development Environment

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/contributing.md

Commands to set up the development environment, including cloning the repository, creating a virtual environment, installing dependencies, and setting up pre-commit hooks.

```bash
# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/ralph-orchestrator.git
cd ralph-orchestrator

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e .
pip install pytest pytest-cov black ruff

# Install pre-commit hooks (optional)
pip install pre-commit
pre-commit install
```

--------------------------------

### Include Input/Output Examples

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/prompts.md

Provide concrete examples of expected input and output to guide the orchestrator's behavior and ensure accurate results.

```json
{
  "user_id": 123,
  "action": "purchase",
  "items": ["SKU-001", "SKU-002"]
}
```

```json
{
  "order_id": "ORD-789",
  "status": "confirmed",
  "total": 99.99,
  "estimated_delivery": "2024-01-15"
}
```

--------------------------------

### Generated README for QuickSort Plus Package

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/examples/documentation.md

This is an example of a generated README.md file. It includes a title, features, installation instructions, quick start examples, performance comparison, and license information.

```markdown
# QuickSort Plus

An optimized implementation of the quicksort algorithm with modern enhancements.

## Features

- **Hybrid Sorting**: Automatically switches to insertion sort for small arrays (< 10 elements)
- **Three-Way Partitioning**: Efficiently handles arrays with many duplicate elements
- **Parallel Processing**: Leverages multiple cores for large datasets
- **Type Support**: Works with any comparable Python objects

## Installation

```bash
pip install quicksort-plus
```

## Quick Start

```python
from quicksort_plus import quicksort

# Basic usage
data = [3, 1, 4, 1, 5, 9, 2, 6]
sorted_data = quicksort(data)

# With parallel processing
large_data = list(range(1000000, 0, -1))
sorted_data = quicksort(large_data, parallel=True)
```

## Performance

| Array Size | Standard QuickSort | QuickSort Plus | Improvement |
|------------|-------------------|----------------|-------------|
| 100        | 0.012ms          | 0.008ms        | 33%         |
| 10,000     | 1.8ms            | 1.2ms          | 33%         |
| 1,000,000  | 248ms            | 142ms          | 43%         |

## License

MIT License - See LICENSE file for details

```

--------------------------------

### Install and Configure Gemini CLI Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install the Gemini CLI using npm and set the `GEMINI_API_KEY` environment variable for authentication. Verify the installation with `gemini --version`.

```bash
# Install
npm install -g @google/gemini-cli

# Configure API key
export GEMINI_API_KEY=your-key

# Verify
gemini --version
```

--------------------------------

### Verify Development Setup

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/contributing/setup.md

Commands to verify the development setup by running tests, checking formatting, and running clippy.

```bash
cargo test

cargo test -p ralph-core smoke_runner

cargo fmt --check

cargo clippy --all-targets --all-features
```

--------------------------------

### Example Debug Session Workflow

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/advanced/diagnostics.md

A step-by-step example of enabling diagnostics, running a command, and identifying the session directory.

```bash
# 1. Run with diagnostics
RALPH_DIAGNOSTICS=1 ralph run -p "implement feature X"

# 2. Find the session
ls -la .ralph/diagnostics/
# 2024-01-21T08-45-30/
```

--------------------------------

### Prompt Example: Constraints

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/first-task.md

Illustrates how to specify constraints in a prompt, guiding Ralph on technology choices, versioning, and limitations.

```markdown
## Constraints
- Use Axum (not Actix)
- Rust 1.75+
- No external API calls
```

--------------------------------

### Setup Pre-commit Hooks

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/advanced/testing.md

Install the project's pre-commit hooks. These hooks run CI-parity checks before each commit to ensure code quality and consistency.

```bash
./scripts/setup-hooks.sh
```

--------------------------------

### Run Ralph in a Virtual Machine with Snapshots

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/advanced/security.md

This example demonstrates how to use Vagrant to manage a virtual machine for running Ralph, including starting, executing commands, and restoring to a clean snapshot.

```bash
# Run in VM with snapshot
vagrant up
vagrant ssh -c "cd /project && ./ralph run"
vagrant snapshot restore clean
```

--------------------------------

### Install ACP Agent (Gemini Example)

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/quick-start.md

Install an ACP-compliant agent, such as the Gemini CLI, and configure it to run with Ralph in ACP mode.

```bash
# Any ACP-compliant agent can be used
# Example: Gemini CLI with ACP mode
npm install -g @google/gemini-cli
# Run with: ralph run -a acp --acp-agent gemini
```

--------------------------------

### Feature Development Workflow

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/examples/index.md

A comprehensive example demonstrating the setup for feature development. It initializes Ralph, creates a detailed prompt for a new feature, and then runs the task using a code-assist hat.

```bash
# Initialize core config
ralph init --backend claude

# Create detailed prompt
cat > PROMPT.md << 'EOF'
# Feature: User Dashboard

Add a user dashboard with:
- Profile summary widget
- Recent activity feed
- Quick action buttons

Use React components.
Follow existing UI patterns.
EOF

# Run Ralph with the default implementation hats
ralph run -c ralph.yml -H builtin:code-assist
```

--------------------------------

### Execute Backend Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/api/ralph-adapters.md

An example demonstrating how to execute a backend (Claude) using `PtyExecutor` and `ConsoleStreamHandler`, then printing the results.

```rust
use ralph_adapters::{backends, PtyExecutor, ConsoleStreamHandler};

#[tokio::main]
async fn main() -> Result<()> {
    // Get Claude backend
    let backend = backends::claude();

    // Create executor
    let executor = PtyExecutor::new();

    // Execute with prompt
    let result = executor.execute(
        &backend,
        "Write a hello world function",
        Box::new(ConsoleStreamHandler::new()),
    ).await?;

    println!("Exit code: {}", result.exit_code);
    println!("Output: {}", result.output);

    Ok(())
}
```

--------------------------------

### Install Ralph CLI with npm

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/index.md

Use npm to install the Ralph CLI globally. This is the recommended installation method.

```bash
npm install -g @ralph-orchestrator/ralph-cli
```

--------------------------------

### Install Amp Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install the Amp CLI by visiting its GitHub repository. Authentication is handled through the `amp` CLI itself, and no specific environment variables are checked by `ralph doctor`.

```bash
# Install
# Visit https://github.com/sourcegraph/amp

# Verify
amp --version
```

--------------------------------

### Install Kiro Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install the Kiro CLI by visiting the official Kiro website. Authentication is handled via Kiro CLI's own authentication process.

```bash
# Install
# Visit https://kiro.dev/

# Verify
kiro-cli --version
```

--------------------------------

### Install Ralph CLI with GitHub Releases Installer

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/index.md

Download and run the official installer script from GitHub releases to install the Ralph CLI.

```bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh
```

--------------------------------

### Install and Authenticate Copilot CLI Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install the Copilot CLI using npm and authenticate using `copilot auth login` or `gh auth login`. Verify the installation with `copilot --version`.

```bash
# Install
npm install -g @github/copilot

# Authenticate
copilot auth login

# Verify
copilot --version
```

--------------------------------

### Setup Development Environment with Direnv

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/DEVELOPMENT.md

Clone the repository and allow direnv to activate the development environment for automatic tool setup.

```bash
cd ralph-orchestrator
direnv allow
```

--------------------------------

### Install AI Agents with npm

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/reference/faq.md

Install the necessary AI agent CLIs using npm. Ensure you have Node.js and npm installed.

```bash
# Claude
npm install -g @anthropic-ai/claude-code

# Gemini
npm install -g @google/gemini-cli

# Q Chat
# Follow instructions at https://github.com/qchat/qchat
```

--------------------------------

### Execute Backend Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/api/ralph-adapters.md

A complete example demonstrating how to execute a backend, process its output using a stream handler, and retrieve results.

```APIDOC
## Example: Execute Backend

```rust
use ralph_adapters::{backends, PtyExecutor, ConsoleStreamHandler};

#[tokio::main]
async fn main() -> Result<()> {
    // Get Claude backend
    let backend = backends::claude();

    // Create executor
    let executor = PtyExecutor::new();

    // Execute with prompt
    let result = executor.execute(
        &backend,
        "Write a hello world function",
        Box::new(ConsoleStreamHandler::new()),
    ).await?;

    println!("Exit code: {}", result.exit_code);
    println!("Output: {}", result.output);

    Ok(())
}
```
```

--------------------------------

### Install and Authenticate Forge Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install Forge using the provided curl command and authenticate providers via `forge provider login`. Verify with `forge --version`.

```bash
# Install
curl -fsSL https://forgecode.dev/cli | sh

# Authenticate
forge provider login

# Verify
forge --version
```

--------------------------------

### Install Ralph v2 (Rust)

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/reference/migration-v1.md

Installation methods for the new Rust-based Ralph v2 CLI, including npm, a GitHub Releases installer script, and Cargo.

```bash
# Via npm (recommended)
npm install -g @ralph-orchestrator/ralph-cli
```

```bash
# Via GitHub Releases installer
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh
```

```bash
# Via Cargo
cargo install ralph-cli
```

--------------------------------

### Install and Verify OpenCode CLI

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install the OpenCode CLI using curl and verify the installation by checking the version. Ensure an API key environment variable is set for authentication.

```bash
# Install
curl -fsSL https://opencode.ai/install | bash

# Verify
opencode --version
```

--------------------------------

### Install Skills from Local Repository

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/skills/README.md

During local development, use this command to install skills directly from the checked-out repository. The --list flag shows available skills.

```bash
npx skills add . --list
```

--------------------------------

### Install Q CLI and Ralph Orchestrator

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/deployment/qchat-production.md

Installs the Q Chat CLI and the Ralph Orchestrator with Q adapter support using pip.

```bash
# Install Q CLI
pip install q-cli

# Verify installation
qchat --version

# Install Ralph Orchestrator with Q adapter support
pip install ralph-orchestrator
```

--------------------------------

### Install and Configure Codex Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install Codex from its GitHub repository and configure authentication using either `OPENAI_API_KEY` or `CODEX_API_KEY` environment variables. Verify with `codex --version`.

```bash
# Install
# Visit https://github.com/openai/codex

# Configure
export OPENAI_API_KEY=your-key

# Verify
codex --version
```

--------------------------------

### Custom Event Loop Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/api/ralph-core.md

Provides an example of setting up and running a custom event loop with an optional event listener.

```APIDOC
## Example: Custom Event Loop

### Description
Demonstrates how to create a custom event loop, load configuration, and optionally attach an event listener.

### Usage
```rust
use ralph_core::{Config, EventLoop};
use ralph_proto::{EventBus, Event};

#[tokio::main]
async fn main() -> Result<()> {
    // Load config
    let config = Config::load("ralph.yml")?;

    // Create event loop
    let mut event_loop = EventLoop::new(config);

    // Optional: Add custom event listener
    event_loop.on_event(|event| {
        println!("Event: {:?}", event.topic);
    });

    // Run
    let result = event_loop.run().await?;

    println!("Completed in {} iterations", result.iterations);
    Ok(())
}
```
```

--------------------------------

### Start Ralph Loop with Preset Config

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/crates/ralph-cli/sops/addendums/pdd-ralph.md

Use this command to start the Ralph loop with a predefined configuration file. Replace '<task>' with the actual task description.

```bash
ralph run --config presets/pdd-to-code-assist.yml --prompt "<task>"
```

--------------------------------

### Install Node.js with NVM

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/README.md

Install the correct Node.js version using NVM (Node Version Manager) by reading the `.nvmrc` file. This is the recommended method for setting up Node.js.

```bash
# Option 1: nvm (recommended)
nvm install    # reads .nvmrc
```

--------------------------------

### Install Frontend and Legacy Backend Dependencies

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/README.md

Install dependencies for the frontend and the legacy Node.js backend. This is typically done before development or running the web dashboard.

```bash
npm install              # install frontend + legacy backend deps
```

--------------------------------

### Clone, Build, Test, and Install Hooks

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/contributing/index.md

Quick commands to clone the Ralph repository, build the project, run tests, and install git hooks for development.

```bash
git clone https://github.com/mikeyobrien/ralph-orchestrator.git
cd ralph-orchestrator

cargo build

cargo test

./scripts/setup-hooks.sh
```

--------------------------------

### Install Coverage Tools and Generate Report

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/CONTRIBUTING.md

Manual installation steps for coverage tools and commands to generate coverage reports and badge payloads if not using the devenv shell.

```bash
rustup component add llvm-tools-preview
cargo install cargo-llvm-cov

just coverage
just coverage-badge-json
```

--------------------------------

### Install Q Chat CLI

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/agents.md

Install the Q Chat CLI for a cost-effective AI assistant. This is required for using Q Chat with Ralph Orchestrator.

```bash
pip install q-cli
```

--------------------------------

### Setup Development Environment with Nix

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/DEVELOPMENT.md

Clone the repository and enter the development shell using 'nix develop' to access all necessary tools.

```bash
cd ralph-orchestrator
nix develop
```

--------------------------------

### Building Documentation Locally with MkDocs

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/contributing.md

Commands to install MkDocs, serve the documentation locally for development, and build the static site.

```bash
# Install MkDocs
pip install mkdocs mkdocs-material

# Serve locally
mkdocs serve

# Build static site
mkdocs build
```

--------------------------------

### Install Claude AI Agent

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/quick-start.md

Install the Claude AI agent using npm. Alternatively, visit the provided URL for setup instructions.

```bash
npm install -g @anthropic-ai/claude-code
# Or visit https://claude.ai/code for setup instructions
```

--------------------------------

### Onboard RObot with Telegram

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/README.md

Commands to onboard and verify the RObot human-in-the-loop functionality using Telegram. Requires guided setup for token and chat ID.

```bash
ralph bot onboard --telegram
```

```bash
ralph bot status
```

```bash
ralph bot test
```

```bash
ralph run -c ralph.bot.yml -p "Help the human"
```

--------------------------------

### Documentation Prompt Pattern

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/prompts.md

An example prompt for creating user documentation, detailing the objective, required sections, structure, style guide, and success criteria.

```markdown
# Create User Documentation

## Objective
Write comprehensive user documentation for the application.

## Requirements
1. Installation guide
2. Configuration reference
3. Usage examples
4. Troubleshooting section
5. FAQ

## Structure
```
docs/
├── getting-started.md
├── installation.md
├── configuration.md
├── usage/
│   ├── basic.md
│   └── advanced.md
├── troubleshooting.md
└── faq.md
```

## Style Guide
- Use clear, concise language
- Include code examples
- Add screenshots where helpful
- Follow Markdown best practices

## Success Criteria
- [ ] All sections complete
- [ ] Examples tested and working
- [ ] Reviewed for clarity
- [ ] No broken links

The orchestrator will continue iterations until limits are reached.
```

--------------------------------

### Description Mode Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/crates/ralph-cli/sops/code-task-generator.md

Illustrates the input for description mode and the expected output file path for a task.

```text
Description mode input: "I need a function that validates email addresses and returns detailed error messages"

Description mode output: .ralph/tasks/email-validator.code-task.md — task with acceptance criteria for valid/invalid email handling, error messages, and unit tests.
```

--------------------------------

### Generate README for Python Package with Claude

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/examples/documentation.md

Use this prompt to generate a README.md file for a Python package. Include package name, features, installation instructions, and usage examples.

```python
prompt = """
Create a README.md for a Python package called 'quicksort-plus' that implements 
an optimized quicksort algorithm with the following features:
- Hybrid approach with insertion sort for small arrays
- Three-way partitioning for duplicate elements
- Parallel processing support
"""

response = orchestrator.execute(prompt, agent="claude")
```

--------------------------------

### Pi Backend Configuration Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/specs/pi-agent-support/research/04-backend-patterns.md

Configure Pi backend with specific providers and models using YAML. This allows for different Pi configurations per 'hat' in Ralph.

```yaml
hats:
  planner:
    backend:
      type: pi
      args: ["--provider", "anthropic", "--model", "claude-sonnet-4"]
  builder:
    backend:
      type: pi
      args: ["--provider", "openai-codex", "--model", "gpt-5.2-codex"]
```

--------------------------------

### Run Ralph Interactive Tutorial

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/cli-reference.md

Launches an interactive walkthrough to guide users through Ralph's features.

```bash
ralph tutorial [OPTIONS]
```

--------------------------------

### Custom Helm values.yaml Configuration

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/deployment/kubernetes.md

Example `values.yaml` file for customizing Helm chart installations. Configure replica count, image details, API keys, agent settings, resources, persistence, autoscaling, monitoring, and ingress.

```yaml
# values.yaml
replicaCount: 1

image:
  repository: ghcr.io/mikeyobrien/ralph-orchestrator
  tag: v1.0.0
  pullPolicy: IfNotPresent

apiKeys:
  claude: ""
  gemini: ""
  q: ""

config:
  agent: "auto"
  maxIterations: 100
  maxRuntime: 14400
  checkpointInterval: 5
  verbose: true
  enableMetrics: true

resources:
  requests:
    memory: "2Gi"
    cpu: "1"
  limits:
    memory: "4Gi"
    cpu: "2"

persistence:
  enabled: true
  storageClass: "standard"
  workspace:
    size: 10Gi
  cache:
    size: 5Gi

autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s

ingress:
  enabled: false
  className: "nginx"
  annotations: {}
  hosts:
    - host: ralph.example.com
      paths:
        - path: "/"
          pathType: "Prefix"

```

--------------------------------

### Ralph Hooks Configuration Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/specs/add-hooks-to-ralph-orchestrator-lifecycle/design.md

Configure hook execution, including defaults for timeouts and output limits, and define specific hooks for lifecycle events like loop start and loop completion. Hooks can be named, specify commands, and define error handling behavior.

```yaml
hooks:
  enabled: true
  defaults:
    timeout_seconds: 30
    max_output_bytes: 8192
    suspend_mode: wait_for_resume
  events:
    pre.loop.start:
      - name: env-guard
        command: ["./scripts/hooks/env-guard.sh"]
        on_error: block
    post.loop.complete:
      - name: notify
        command: ["./scripts/hooks/notify.sh"]
        on_error: warn
```

--------------------------------

### Initialize Ralph Project

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/quick-start.md

Create a new directory for your Ralph project, navigate into it, initialize Git, and create a default configuration file using `ralph init`.

```bash
mkdir my-ralph-project
cd my-ralph-project
git init  # Ralph works best with git

# Create a default config
ralph init --backend claude
```

--------------------------------

### Verify Ralph CLI Installation

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/installation.md

Run this command after installation to confirm that the Ralph CLI is installed and accessible.

```bash
ralph --version
```

--------------------------------

### PDD Mode Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/crates/ralph-cli/sops/code-task-generator.md

Shows the input for PDD mode and the expected output directory structure with multiple task files.

```text
PDD mode input: ".ralph/specs/data-pipeline/plan.md"

PDD mode output: .ralph/tasks/data-pipeline/step02/ containing task-01-create-data-models.code-task.md, task-02-implement-validation.code-task.md, task-03-add-serialization.code-task.md — each with design.md reference, acceptance criteria, and demo requirements.
```

--------------------------------

### Install Ralph CLI with Prebuilt Binary

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/installation.md

Download, extract, and place the prebuilt Ralph CLI binary on your system's PATH. Replace the placeholder URL with the correct archive for your platform.

```bash
# Example (replace with the correct archive for your platform)
mkdir -p ~/bin
curl -L -o ralph.tar.xz "<release-archive-url>"
tar -xJf ralph.tar.xz
mv ralph ~/bin/
export PATH="$HOME/bin:$PATH"
```

--------------------------------

### Orchestrator Usage Examples

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/api/orchestrator.md

Demonstrates how to initialize and run the orchestrator using either a configuration object or individual parameters.

```python
from ralph_orchestrator import RalphOrchestrator, RalphConfig

# Using config object
config = RalphConfig(agent=AgentType.CLAUDE)
orchestrator = RalphOrchestrator(config)
orchestrator.run()

# Using individual parameters
orchestrator = RalphOrchestrator(
    prompt_file_or_config="PROMPT.md",
    primary_tool="claude",
    max_iterations=50
)
orchestrator.run()

```

--------------------------------

### Install Single Skill for Codex Agents

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/skills/README.md

Installs the 'ralph-loop' skill from the ralph-orchestrator repository for Codex-style agents. The -y flag confirms installation.

```bash
npx skills add mikeyobrien/ralph-orchestrator \
  --skill ralph-loop \
  -a codex \
  -y
```

--------------------------------

### Setup Logging and Configuration

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/examples/data-analysis.md

Initializes logging for the application and defines a function to load configuration from a YAML file. Ensure 'config.yaml' exists and is properly formatted.

```python
import logging
import yaml

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

def load_config(config_path='config.yaml'):
    """Load configuration from YAML file"""
    with open(config_path, 'r') as f:
        return yaml.safe_load(f)
```

--------------------------------

### Install All Skills for Claude Code

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/skills/README.md

Installs all skills from the ralph-orchestrator repository, specifically configured for Claude Code. The -y flag confirms installation.

```bash
npx skills add mikeyobrien/ralph-orchestrator \
  --skill ralph-hats \
  --skill ralph-loop \
  --skill ralph-docs \
  -a claude-code \
  -y
```

--------------------------------

### Python CLI Tool Setup with setuptools

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/examples/cli-tool.md

Configure your Python package for distribution and command-line entry points. Ensure necessary dependencies like rich, tqdm, and click are included.

```python
from setuptools import setup, find_packages

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

setup(
    name="fman",
    version="1.0.0",
    author="Your Name",
    author_email="your.email@example.com",
    description="A powerful file manager CLI tool",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/fman",
    packages=find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
        "Environment :: Console",
        "Topic :: System :: Filesystems",
    ],
    python_requires=">=3.7",
    install_requires=[
        "rich>=10.0.0",
        "tqdm>=4.60.0",
        "click>=8.0.0",
    ],
    entry_points={
        "console_scripts": [
            "fman=fman.cli:main",
        ],
    },
    include_package_data=True,
)
```

--------------------------------

### Install Ralph CLI with Cargo

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/index.md

Install the Ralph CLI using Cargo, Rust's package manager. Ensure you have Rust and Cargo installed.

```bash
cargo install ralph-cli
```

--------------------------------

### Example Ralph CLI Commands for Preset Usage

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/specs/hat-imports/research/embedded-preset-interaction.md

Demonstrates how to use Ralph CLI commands with self-contained embedded presets, file-based presets with imports, and hat files with imports.

```bash
# Self-contained embedded preset (no imports)
ralph run -H builtin:feature -p "Add OAuth"
```

```bash
# File-based preset with imports
ralph run -H ./my-workflow.yml -p "Add OAuth"
# my-workflow.yml can contain: import: ./shared-hats/builder.yml
```

```bash
# Hat file with imports
ralph run -c ralph.yml -H ./hats/custom.yml -p "Add OAuth"
```

--------------------------------

### Initialize and Run a Ralph Project

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/README.md

Use these commands to initialize a new project with a specified backend, plan a task, and run the orchestration.

```bash
ralph init --backend claude
ralph plan "Add user authentication with JWT"
ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
```

--------------------------------

### Initialize Ralph and Auto-Detect Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Run `ralph init` to automatically detect and set up the first available AI backend based on a predefined order.

```bash
ralph init
# Auto-detects available backend
```

--------------------------------

### Install rapidfuzz Package

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/advanced/loop-detection.md

Loop detection requires the `rapidfuzz` package. Install it using pip, ensuring a version between 3.0.0 and 4.0.0 is used. If not installed, loop detection is skipped.

```bash
pip install "rapidfuzz>=3.0.0,<4.0.0"
```

--------------------------------

### Initialize Ralph and List Presets

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/crates/ralph-cli/presets/README.md

Use these commands to initialize Ralph with a specific backend and to list all available presets.

```bash
ralph init --backend claude
```

```bash
ralph init --list-presets
```

--------------------------------

### Install Missing Agents

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/reference/troubleshooting.md

Install Claude and Gemini agents using npm if they are not found.

```bash
# Claude
npm install -g @anthropic-ai/claude-code

# Gemini
npm install -g @google/gemini-cli
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/contributing.md

Examples of commit messages following the Conventional Commits specification.

```bash
feat: add Gemini agent support
fix: resolve token overflow in long prompts
docs: update installation guide for Windows
test: add integration tests for checkpointing
refactor: extract prompt validation logic
```

--------------------------------

### v1.x Solo Mode Configuration

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/migration/v2-hatless-ralph.md

Example of a v1.x configuration for solo mode with a specified backend.

```yaml
cli:
  backend: claude
```

--------------------------------

### Install Claude Code CLI

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/quick-start.md

Install the Claude Code CLI, a recommended AI backend for Ralph. Ensure it's added to your system's PATH. Verify installation with `claude --version`.

```bash
# Claude Code
npm install -g @anthropic-ai/claude-code
```

```bash
# Verify the CLI is available
claude --version
```

--------------------------------

### Initialize Ralph Project

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/examples/web-api.md

Use 'ralph init' to start a new project. Copy the prompt to PROMPT.md for task definition. Run the project with 'ralph run' specifying an agent and max iterations.

```bash
ralph init

cp web-api-prompt.md PROMPT.md

ralph run --agent claude --max-iterations 50
```

--------------------------------

### Install and Verify Pi Coding Assistant

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/backends.md

Install the Pi coding assistant globally using npm and verify the installation by checking its version. Authentication can be handled via environment variables or explicit API key arguments.

```bash
# Install
npm install -g @earendil-works/pi-coding-agent

# Verify
pi --version
```

--------------------------------

### Verify Agent Installation

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/reference/troubleshooting.md

Check if the necessary agents (claude, gemini, q) are installed and accessible in your PATH.

```bash
which claude
which gemini
which q
```

--------------------------------

### Install Copilot CLI

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/installation.md

Install the Copilot CLI AI tool via npm. This is a prerequisite for Ralph.

```bash
npm install -g @github/copilot
```

--------------------------------

### GCP Production Infrastructure Setup

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/deployment/production.md

Commands to set up essential GCP resources for a production deployment, including GKE cluster, Cloud SQL instance, and Memorystore Redis.

```bash
# Create GKE cluster
gcloud container clusters create ralph-production \
  --zone us-central1-a \
  --machine-type n2-standard-4 \
  --num-nodes 3 \
  --enable-autoscaling \
  --min-nodes 2 \
  --max-nodes 10 \
  --enable-autorepair \
  --enable-autoupgrade
```

```bash
# Create Cloud SQL instance
gcloud sql instances create ralph-prod-db \
  --database-version=POSTGRES_15 \
  --cpu=4 \
  --memory=16GB \
  --region=us-central1 \
  --availability-type=REGIONAL \
  --backup \
  --backup-start-time=03:00
```

```bash
# Create Memorystore Redis
gcloud redis instances create ralph-prod-cache \
  --size=5 \
  --region=us-central1 \
  --redis-version=redis_6_x \
  --tier=STANDARD_HA
```

--------------------------------

### Install Gemini CLI

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/installation.md

Install the Gemini CLI AI tool via npm. This is a prerequisite for Ralph.

```bash
npm install -g @google/gemini-cli
```

--------------------------------

### Initialize Ralph with Supported Backends

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/reference/troubleshooting.md

Initialize Ralph with supported backends like claude, gemini, or codex.

```bash
ralph init --backend claude
ralph init --backend gemini
ralph init --backend codex
```

--------------------------------

### Verify Ralph Installation

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/getting-started/index.md

Check if the Ralph CLI is installed correctly by running the version and help commands.

```bash
ralph --version
ralph --help
```

--------------------------------

### Cost-Aware Prompt Example

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/guide/cost-management.md

An example of markdown content for a prompt that includes budget constraints and optimization priorities.

```markdown
## Budget Constraints
- Maximum budget: $10
- Optimize for efficiency
- Skip non-essential features if approaching limit
- Prioritize core functionality
```

--------------------------------

### Initialize Ralph with Custom Backend

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/reference/troubleshooting.md

Generate a template configuration for a custom backend in Ralph.

```bash
ralph init --backend custom
```

--------------------------------

### Install Git Hooks

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/contributing/setup.md

Installs pre-commit hooks to ensure code quality and consistency by mirroring CI checks.

```bash
./scripts/setup-hooks.sh
```

--------------------------------

### Hat Backends Configuration in YAML

Source: https://github.com/mikeyobrien/ralph-orchestrator/blob/main/docs/api/config.md

Example YAML structure for configuring different Hat backends, including builder, reviewer, and custom backends. Demonstrates specifying backend type, agent, arguments, and command.

```yaml
hats:
  builder:
    name: "Builder"
    triggers: ["plan.done"]
    publishes: ["build.done"]
    backend:
      type: "kiro"
      agent: "builder"
      args: ["--verbose"]

  reviewer:
    name: "Reviewer"
    triggers: ["build.done"]
    publishes: ["review.done"]
    backend:
      type: "claude"
      args: ["--model", "claude-sonnet-4"]

  custom:
    name: "Custom"
    triggers: ["review.done"]
    backend:
      command: "/usr/local/bin/my-llm"
      args: ["--safe"]
```