Ralph Workflow

Ralph Workflow is an unattended AI agent orchestrator for long-running development tasks. Write a detailed specification in PROMPT.md, start Ralph, and walk away. It coordinates AI agents through multiple development iterations and review cycles, producing commits automatically.

Ralph works best when you think like a Product Manager: scope out every detail of the feature you need. The more detail in your specification, the better Ralph performs. It is designed to run for hours without babysitting.

Inspired by Geoffrey Huntley's Ralph Workflow concept.

When to Use Ralph

Ralph excels at:

Long-running feature implementations with detailed specifications
Systematic refactoring workflows requiring multiple iterations
Test suite generation with comprehensive review
Documentation writing with multiple review passes
Any task where you can write a detailed spec and let it run unattended

Not ideal for:

Vague or undefined requirements (Ralph needs detailed specs)
Simple one-off commands (use Claude Code directly)
Real-time interactive debugging
Tasks requiring human judgment at each step

How It Works

Ralph runs a multi-phase workflow:

Developer Phase: AI agent implements your spec through multiple iterations
- Creates PLAN.md internally from your PROMPT.md
- Executes the plan and makes code changes
- Evaluate the code change and see if requires more work
- Goes back if necessary and then make more code change, repeat until the plan is met
- Auto-commits after each iteration
- Cleans up and repeats for configured iterations
Review Phase: AI reviewer checks quality and fixes issues
- Reviews code and creates ISSUES.md with problems found
- Developer agent fixes the issues
- Repeats until no issues or max cycles reached
Final Commit: Generates a meaningful commit message via AI

Ralph workflow automatically cleans context of AI agent to ensure that no context pollution exists when AI agents is being ran. The idea behind this is to ensure that context pollution makes the code quality worse, so we ensure review agent has no context on what was done except for the diff and the current state of the code, same thing as dev agent vs planning agent.

All orchestration files (PLAN.md, ISSUES.md) are controlled by Ralph, not the AI agents. This ensures deterministic, reliable operation.

Quick Start

1. Install

git clone https://codeberg.org/mistlight/RalphWithReviewer.git
cd RalphWithReviewer

# Install from source
cargo install --path ralph-workflow --locked

# Or build + install via Makefile
make install-local

Alternatively you can use cargo crate

cargo install ralph-workflow --locked

2. Install AI Agents

Install at least one AI agent:

Agent	Install	Recommended Role
Claude Code	`npm install -g @anthropic/claude-code`	Developer
Codex	`npm install -g @openai/codex`	Reviewer
OpenCode	See opencode.ai	Either

3. Run Ralph

# Create config file (smart init detects what you need)
ralph --init

# Navigate to your git repo
cd /path/to/your/project

# Create PROMPT.md from a Work Guide
ralph --init feature-spec
# Edit PROMPT.md with detailed requirements

# Run Ralph and walk away
ralph

Work Guides

Work Guides are templates for describing your tasks to the AI. Use them with --init:

# See all available Work Guides
ralph --list-work-guides

# Create PROMPT.md from a Work Guide
ralph --init bug-fix              # Bug fix with investigation guidance
ralph --init feature-spec         # Comprehensive product specification
ralph --init refactor             # Code refactoring
ralph --init quick                # Quick/small changes
ralph --init test                 # Test writing

# Overwrite existing PROMPT.md
ralph --init bug-fix --force-overwrite

Note: Work Guides (for PROMPT.md) are different from Agent Prompts (backend AI behavior). Run ralph --extended-help for details.

Writing Effective Specifications

Your PROMPT.md should be detailed. Example:

# Task: Refactor Auth Module

## Description
Refactor the authentication module to use OAuth2 instead of basic auth.

## Requirements
1. Use passport-oauth2 library
2. Support GitHub and Google providers
3. Maintain backward compatibility with API keys
4. Add comprehensive tests

## Files to Update
- src/auth/mod.rs
- src/auth/oauth.rs (new)
- tests/auth_test.rs

## Constraints
- No breaking changes to public API
- All existing tests must pass

Common Commands

Preset Modes (control thoroughness)

ralph -Q              # Quick: 1 dev + 1 review
ralph -U              # Rapid: 2 dev + 1 review
ralph -S              # Standard: 5 dev + 2 reviews (default)
ralph -T              # Thorough: 10 dev + 5 reviews
ralph -L              # Long: 15 dev + 10 reviews

Custom Iterations

ralph -D 3 -R 2       # 3 dev iterations, 2 review cycles
ralph -D 10 -R 0      # Skip review phase entirely

Choose Agents

ralph -a claude -r codex    # Claude for dev, Codex for review
ralph -a opencode           # Use OpenCode for development

Verbosity Control

ralph -q              # Quiet mode
ralph -f              # Full output (no truncation)
ralph -d              # Diagnose: show system info

Recovery

ralph --resume                         # Resume from last checkpoint
ralph --dry-run                        # Validate setup without running

Configuration

Ralph uses ~/.config/ralph-workflow.toml:

ralph --init              # Smart init: creates config or PROMPT.md as needed
ralph --init bug-fix      # Create PROMPT.md from a specific Work Guide
ralph --list-work-guides  # Show all available Work Guides
ralph --extended-help     # Show comprehensive help

Configure agent chains and defaults:

[general]
developer_iters = 5
reviewer_reviews = 2

[agent_chain]
developer = ["claude", "codex", "opencode"]
reviewer = ["codex", "claude"]
max_retries = 3

Environment variables override config:

RALPH_DEVELOPER_AGENT - Developer agent
RALPH_REVIEWER_AGENT - Reviewer agent
RALPH_DEVELOPER_ITERS - Developer iterations
RALPH_REVIEWER_REVIEWS - Review cycles
RALPH_VERBOSITY - Output detail (0-4)

Files Created by Ralph

.agent/
├── PLAN.md            # Current iteration plan (orchestrator-written)
├── ISSUES.md          # Review findings (orchestrator-written)
├── STATUS.md          # Current status
├── commit-message.txt # Generated commit message
├── checkpoint.json    # For --resume
├── start_commit       # Baseline for diffs
└── logs/              # Detailed per-phase logs

Documentation

Full documentation is available on Codeberg:

Quick Reference - Cheat sheet for commands and flags
Agent Compatibility - Supported AI agents and configuration
Git Workflow - How Ralph handles commits and diffs
Template Guide - PROMPT.md Work Guides and agent prompt customization
Architecture - Reducer/event-loop architecture and codebase tour

Note: When viewing on crates.io, these links point to the source repository on Codeberg.

FAQ

Can I use Ralph at work?

Yes. Ralph is a local CLI tool. The AGPL license covers only the Ralph source code, not anything you create with it.

Does AGPL apply to my generated code?

No. The AGPL covers only Ralph itself, not your code or Ralph's output.

What if Ralph gets interrupted?

Use ralph --resume to continue from the last checkpoint.

Cargo Features

Feature	Default	Description
`monitoring`	Yes	Enable streaming metrics and debugging APIs
`test-utils`	No	Enable test utilities (TestLogger, TestPrinter, MemoryWorkspace)
`hardened-resume`	Yes	Enable execution history and file state capture for recovery

To use test-utils for integration testing:

[dev-dependencies]
ralph-workflow = { version = "0.6", features = ["test-utils"] }

Contributing

Contributions welcome!

Fork the repository
Create a feature branch
Run tests: cargo test
Run lints: cargo clippy && cargo fmt --check
Submit a pull request

License

AGPL-3.0. See LICENSE.

ralph-workflow 0.7.1