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 from your PROMPT.md
- Executes the plan and makes code changes
- 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

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

Design Philosophy

Ralph makes deterministic decisions whenever possible, only calling on AI when needed:

Conflict Resolution: Prompts AI specifically about conflicts, then resolves automatically
File I/O: The orchestrator controls all file writes, not the agents
Git Operations: Ralph handles rebasing, committing, and status checks deterministically
Checkpoint/Resume: Saves state after each phase; interrupted runs can resume with --resume

Quick Start

1. Install

git clone https://codeberg.org/mistlight/RalphWithReviewer.git
cd RalphWithReviewer
cargo install --path .
make install # (if you want to install this system wide)

Alternatively you can use cargo crate

cargo install ralph-workflow

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 "feat: your commit message"

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 "fix: small bug"              # Quick: 1 dev + 1 review
ralph -U "feat: minor change"          # Rapid: 2 dev + 1 review
ralph -S "feat: add feature"           # Standard: 5 dev + 2 reviews (default)
ralph -T "refactor: optimize"          # Thorough: 10 dev + 5 reviews
ralph -L "feat: complex feature"       # Long: 15 dev + 10 reviews

Custom Iterations

ralph -D 3 -R 2 "feat: implement feature"  # 3 dev iterations, 2 review cycles
ralph -D 10 -R 0 "feat: no review"         # Skip review phase entirely

Choose Agents

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

Verbosity Control

ralph -q "fix: typo"                   # Quiet mode
ralph -f "feat: complex change"        # 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

Quick Reference - Cheat sheet for commands and flags
Agent Compatibility - Supported AI agents
Git Workflow - How Ralph handles commits and diffs
Work Guide Reference - PROMPT.md Work Guides (templates for your tasks)

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.

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.6.0