ralph

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   ██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗                  │
│   ██╔══██╗██╔══██╗██║     ██╔══██╗██║  ██║                  │
│   ██████╔╝███████║██║     ██████╔╝███████║                  │
│   ██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║                  │
│   ██║  ██║██║  ██║███████╗██║     ██║  ██║                  │
│   ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝                  │
│                                                             │
│   Orchestrate LLM-powered development from user stories     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

ralph is a CLI tool that orchestrates iterative LLM sessions to implement features from a PRD (Product Requirements Document). It manages the feedback loop between you and your LLM, tracking progress, handling failures with automatic retries, and rendering rich terminal output with syntax highlighting.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Documentation
• Contributing
• License

Features

• Iterative Development Loop - Automatically runs multiple LLM iterations until all stories are complete
• Session Management - Track progress across sessions with unique slugs and iteration history
• Rich Terminal Output - Syntax highlighting for code, diffs, and tool results
• Failure Recovery - Automatic retry logic with configurable attempts and timeouts
• Replay Sessions - Review past sessions with full syntax highlighting
• Customizable Prompts - Use custom prompt templates or add additional instructions
• Theme Support - Multiple built-in themes or use custom .tmTheme files
• Team Strategy - Scaffold a project with default agent definitions and a strategy file via ralph strategy sync
• Multi-Agent Orchestration - Personas can delegate work to each other via ask and handover directives, with automatic routing and budget control

Installation

git clone https://github.com/yourusername/ralph.git
cd ralph
cargo xtask install              # Install to ~/.local/bin
cargo xtask install --path /usr/local/bin  # Custom path

Requirements

• Rust 1.82.0 or later
• An LLM CLI tool (default: Claude CLI)

Quick Start

1. Sync the project strategy:

ralph strategy sync

This creates .claude/agents/ with default agent definitions (architect, developer, reviewer, tester, product-manager) and a .claude/strategy.toml that ties them together. Safe to re-run — new bundled assets are added, existing agent files are preserved, and strategy.toml is updated to the latest version.

2. Create a PRD file at .local/plans/prd.toml:

[[stories]]
category = "feature"
description = "Add user authentication"
steps = [
  "Create login form component",
  "Add authentication API endpoint",
  "Store session tokens securely",
]
passes = false
acceptance = [
  "Users can log in with email and password",
  "Session persists across page refreshes",
]

3. Run ralph:

ralph strategy execute prd-loop

Ralph will iterate through your stories, invoking the LLM to implement each one until all stories pass or you interrupt the session.

4. Monitor progress:

# List all sessions
ralph sessions

# Replay a session's output
ralph replay quiet-mountain

# Replay a specific iteration
ralph replay quiet-mountain -i 3

Example Output

┌────────────────────────────────────────────────────────────────┐
│  ralph strategy execute prd-loop                               │
├────────────────────────────────────────────────────────────────┤
│  Session: quiet-mountain                                       │
│  Stories: 3 pending                                            │
└────────────────────────────────────────────────────────────────┘

Iteration 1/3...

[Tool: Edit] src/auth/login.rs
────────────────────────────────────────
  Before:
    1 │ fn login() {
    2 │     todo!()
    3 │ }
────────────────────────────────────────
  After:
    1 │ fn login(email: &str, password: &str) -> Result<Session> {
    2 │     let user = db.find_user_by_email(email)?;
    3 │     verify_password(password, &user.password_hash)?;
    4 │     Ok(Session::create(user.id))
    5 │ }
────────────────────────────────────────

Configuration

Ralph uses a TOML configuration file stored in platform-specific directories:

Platform	Location
Linux	~/.config/ralph/config.toml
macOS	~/Library/Application Support/ralph/config.toml
Windows	%APPDATA%\ralph\config.toml

Example Configuration

[theme]
name = "base16-ocean.dark"
no_background = false

Configuration Precedence

1. CLI flags (e.g., --theme "Solarized (dark)")
2. Environment variables (e.g., RALPH_THEME)
3. Config file (config.toml)
4. Default values

See Configuration for complete documentation.

Documentation

• CLI Reference - All commands, flags, and options
• Configuration - Config file format and options
• PRD Format - How to structure your PRD files
• Development Guide - Building and contributing

Contributing

Contributions are welcome! Please see the Development Guide for setup instructions.

# Build
cargo build

# Run tests
cargo test

# Run linter
cargo xtask lint

# Install locally for testing
cargo xtask install

License

MIT License - see LICENSE for details.