Ralph Orchestrator

A hat-based orchestration framework that keeps AI agents in a loop until the task is done.

"Me fail English? That's unpossible!" - Ralph Wiggum

Documentation | Getting Started | Presets

Installation

Via npm (Recommended)

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

Via Homebrew (macOS)

brew install ralph-orchestrator

Via Cargo

cargo install ralph-cli

Quick Start

# 1. Initialize Ralph with your preferred backend
ralph init --backend claude

# 2. Plan your feature (interactive PDD session)
ralph plan "Add user authentication with JWT"
# Creates: specs/user-authentication/requirements.md, design.md, implementation-plan.md

# 3. Implement the feature
ralph run -p "Implement the feature in specs/user-authentication/"

Ralph iterates until it outputs LOOP_COMPLETE or hits the iteration limit.

For simpler tasks, skip planning and run directly:

ralph run -p "Add input validation to the /users endpoint"

What is Ralph?

Ralph implements the Ralph Wiggum technique — autonomous task completion through continuous iteration. It supports:

• Multi-Backend Support — Claude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, OpenCode
• Hat System — Specialized personas coordinating through events
• Backpressure — Gates that reject incomplete work (tests, lint, typecheck)
• Memories & Tasks — Persistent learning and runtime work tracking
• 31 Presets — TDD, spec-driven, debugging, and more

Documentation

Full documentation is available at mikeyobrien.github.io/ralph-orchestrator:

• Installation
• Quick Start
• Configuration
• CLI Reference
• Presets
• Concepts: Hats & Events
• Architecture

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards.

License

MIT License — See LICENSE for details.

Acknowledgments

• Geoffrey Huntley — Creator of the Ralph Wiggum technique
• Strands Agents SOP — Agent SOP framework
• ratatui — Terminal UI framework

"I'm learnding!" - Ralph Wiggum