Ralph

Documentation

Three-Phase Workflow

┌────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ARCHITECT │───▶│ PLANNER │───▶│ EXECUTE │ │
│ │ │ │ │ │ │ │
│ │ • Explore │ │ • Generate │ │ • Run tasks │ │
│ │ codebase │ │ PRD with │ │ • Verify via │ │
│ │ • Gather │ │ user │ │ tests │ │
│ │ context │ │ stories │ │ • Retry on │ │
│ │ • Build │ │ • Define │ │ failure │ │
│ │ plan │ │ acceptance │ │ • Commit on │ │
│ │ │ │ criteria │ │ success │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Complete │ │
│ │ or retry │ │
│ └──────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘

Core Features

Installation

pip install pyralph

git clone https://github.com/pavalso/pyralph.git
cd pyralph
pip install -e .

Requirements

Usage

Start the Agent

ralph
ralph --accept-all
ralph -y
ralph planner
ralph execute --accept-all

State Management

# Hard reset - clears all state
rm -rf .ralph/
# Re-plan - regenerate user stories
rm .ralph/prd.json

Skip a Task

CLI Reference

Quick Reference

Output/Verbosity

ralph -vvv --no-color execute

Intent/Input

ralph --intent "Build a REST API with user authentication" architect

Architect Control

ralph --tree-depth 4 --tree-ignore "test*" "spec*" architect

Execution Control

ralph --only TASK-001 TASK-003 --test-cmd "npm test" --timeout 900 execute

Context

ralph --include "src/**/*.py" --exclude "**/generated/**" execute

Model/LLM

ralph --model claude-3-opus --temperature 0 --seed 42 execute

Logging/IO

ralph --log-file debug.log --log-level debug --prd-out plan.json execute

Headless/CI

ralph --ci --intent-file requirements.txt all
# Or check completion status in a script
ralph --status-check && echo "All tasks complete"

Extensibility

ralph --pre "npm run lint" --post "curl -X POST https://hooks.example.com/notify" execute

Privacy

ralph --redact "sk-[a-zA-Z0-9]+" "password=\S+" --no-log-prompts execute

PRD Validation

ralph --schema prd-schema.json --min-criteria 3 --label team=backend priority=high planner

Enhancement Features

Enhancement Flags Reference

Intent Enhancement (--enhance-intent)

ralph --enhance-intent --intent "Build a todo app" architect

ralph --enhance-intent --enhance-intent-strict --intent "Build a todo app" architect

PRD Revision (--revise-prd)

ralph --revise-prd planner

ralph --revise-prd --schema prd-schema.json --min-criteria 3 planner

Using --enhance-all

ralph --enhance-all all

# Enable all enhancements except intent enhancement
ralph --enhance-all --no-enhance-intent planner
# Enable only PRD revision (disable intent enhancement)
ralph --enhance-all --no-enhance-intent planner

Combining Enhancement Flags with Other Options

ralph --ci --enhance-all --intent-file requirements.txt all

ralph --non-interactive --enhance-intent --intent "Build an API" architect

ralph --quiet --enhance-all execute

ralph --ci --enhance-all --intent-file requirements.txt --test-cmd "npm test" all

Fallback Behavior

Error Messages and Resolutions

Events Emitted by Enhancement Features

# .ralph/hooks/enhancement_monitor.py
from pyralph import Event # Optional: for type hints
EVENTS = [
 "INTENT_ENHANCE_SUCCESS",
 "INTENT_ENHANCE_FAILURE",
 "PRD_REVISE_SUCCESS"
]
def on_event(event: Event) -> None:
 if "FAILURE" in event.event_type.name:
 print(f"Enhancement failed: {event.event_type.name}")
 else:
 print(f"Enhancement completed: {event.event_type.name}")

How It Works

Project Structure

pyralph/
├── src/pyralph/ # Main package
│ ├── __init__.py # Package initialization with re-exports
│ ├── ralph.py # Thin entry point (backward-compatible)
│ ├── cli.py # CLI argument parsing (~50 parameters)
│ ├── orchestrator.py # Central coordinator (three-phase workflow)
│ ├── config.py # Configuration dataclass and path constants
│ ├── logger.py # Logging with verbosity, color, JSON support
│ ├── shell.py # Shell command execution utilities
│ ├── prd.py # PRD dataclasses (UserStory, PRD)
│ ├── templates.py # Prompt template management
│ ├── hooks.py # Event/hook system for extensibility
│ ├── fetch_ready_issues.py # GitHub issue fetcher utility
│ └── agents/ # Agent implementations
│ ├── __init__.py # Agent factory and registration
│ ├── base.py # Abstract BaseAgent interface
│ ├── claude.py # Claude CLI agent implementation
│ └── copilot.py # GitHub Copilot CLI agent implementation
├── prompt.md # Default user context prompt template
├── test_ralph.py # Comprehensive test suite
├── pyproject.toml # Build configuration
├── ARCH.md # Architecture decision record
└── .ralph/ # Runtime state directory
 ├── archive/ # Completed PRD archives
 ├── hooks/ # Custom hook scripts
 ├── templates/ # Prompt templates
 ├── prd.json # Current project plan
 ├── progress.txt # Error state (if failing)
 └── ralph_log.txt # Audit trail

Architecture

Testing Conventions

Core Components

Agent Architecture

┌─────────────────────────────────────────────────────────────┐
│ RalphOrchestrator │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ BaseAgent ││
│ │ - timeout, model, temperature, seed, max_tokens ││
│ │ - run(prompt) -> (exit_code, stdout, stderr) ││
│ │ - check_dependencies() -> bool ││
│ └─────────────────────────────────────────────────────────┘│
│ ▲さんかく ▲さんかく │
│ │ │ │
│ ┌────────┴────────┐ ┌────────┴────────┐ │
│ │ ClaudeAgent │ │ GithubAgent │ │
│ │ (claude CLI) │ │ (copilot CLI) │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Data Flow

Knowledge Injection

Debug

tail -n 50 .ralph/ralph_log.txt

Advanced Features

Hook/Event System

Available Event Types

Event Payload

event_type: EventType # The type of event
timestamp: str # ISO format timestamp
phase: Optional[str] # Current phase: architect/planner/execute
task_id: Optional[str] # Task identifier
task_description: Optional[str] # Task description
retry_count: Optional[int] # Current retry attempt
max_retries: Optional[int] # Maximum retries allowed
error: Optional[Any] # Error object if applicable
verification_command: Optional[str] # Test command
verification_exit_code: Optional[int] # Exit code from verification
prd_path: Optional[str] # Path to PRD file
metadata: Dict[str, Any] # Custom metadata

Creating Python Module Hooks

# .ralph/hooks/my_hook.py
from pyralph import Event, EventType # Optional: for type hints
EVENTS = ["TASK_SUCCESS", "TASK_FAILURE"] # Required: events to subscribe to
PRIORITY = 50 # Optional: lower = earlier (default: 100)
TIMEOUT = 10.0 # Optional: max seconds (default: 5.0)
MODIFIES_DATA = False # Optional: can modify events (default: False)
def on_event(event: Event) -> None:
 """Handle task completion events."""
 print(f"Task {event.task_id}: {event.event_type.name}")
 if event.error:
 print(f" Error: {event.error}")

Creating Executable Hooks

# .ralph/hooks/notify.sh
#!/bin/bash
EVENT_JSON=$(cat) # Receive JSON event via stdin
EVENT_TYPE=$(echo "$EVENT_JSON" | jq -r '.event_type')
TASK_ID=$(echo "$EVENT_JSON" | jq -r '.task_id')
echo "Task $TASK_ID: $EVENT_TYPE" >&2

# .ralph/hooks/notify.yaml
events:
 - TASK_SUCCESS
 - TASK_FAILURE
priority: 100
timeout: 5.0

Hook Execution Behavior

Plugin System

Loading Plugins

# Load a single plugin file
ralph --plugin /path/to/plugin.py
# Load all plugins from a directory
ralph --plugin /path/to/plugins/

Creating a Plugin

# ~/my_plugins/monitoring.py
from pyralph import Event, EventType # Optional: for type hints
EVENTS = ["PHASE_START", "PHASE_END", "TASK_SUCCESS", "TASK_FAILURE"]
PRIORITY = 50
TIMEOUT = 10.0
def on_event(event: Event) -> None:
 """Monitor Ralph lifecycle events."""
 if event.event_type.name == "TASK_SUCCESS":
 print(f"Task {event.task_id} completed")
 elif event.event_type.name == "TASK_FAILURE":
 print(f"Task {event.task_id} failed: {event.error}")
 elif event.event_type.name == "PHASE_START":
 print(f"Starting {event.phase} phase")

CLI Hook Options

CI/CD Integration

CI Mode

ralph --ci --intent-file requirements.txt all

ralph --non-interactive --no-color --no-emoji --json

Key CI/CD Flags

Status Check Exit Codes

JSON Output Format

{
 "event": "TASK_SUCCESS",
 "task_id": "TASK-001",
 "timestamp": "2024年01月15日T10:30:00Z",
 "phase": "execute",
 "verification_exit_code": 0
}

ralph --ci --ndjson all | jq 'select(.event == "TASK_FAILURE")'

Combining with Hooks for CI Notifications

# .ralph/hooks/ci_notify.py
import os
import requests
from pyralph import Event # Optional: for type hints
EVENTS = ["TASK_FAILURE", "PLANNER_SUCCESS", "EXECUTE_END"]
def on_event(event: Event) -> None:
 """Send notifications in CI environment."""
 webhook_url = os.environ.get("SLACK_WEBHOOK_URL")
 if not webhook_url:
 return
 if event.event_type.name == "TASK_FAILURE":
 requests.post(webhook_url, json={
 "text": f"Task {event.task_id} failed: {event.error}"
 })
 elif event.event_type.name == "EXECUTE_END":
 requests.post(webhook_url, json={
 "text": "Ralph execution completed"
 })

License