Ralph Orchestrator

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

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

Notice: Ralph Orchestrator is under active development. It works today, but expect rough edges and breaking changes between releases.

v1.0.0 was ralphed into existence with little oversight and guidance. v2.0.0 is a simpler, more-structured implementation. Looking for the old version? See v1.2.3.

Table of Contents

• What is Ralph?
• Features
• Installation
• Quick Start
• Configuration
• Custom Backends and Per-Hat Configuration
• Presets
• Key Concepts
• Orchestration and Coordination Patterns
• Multi-Loop Concurrency
• CLI Reference
• Architecture
• Building & Testing
• Contributing
• License
• Acknowledgments

What is Ralph?

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

"The orchestrator is a thin coordination layer, not a platform. Ralph is smart; let Ralph do the work."

Two Modes of Operation

Ralph supports two orchestration styles:

Traditional mode is the original Ralph Wiggum approach: start a loop, let it run until it outputs the completion promise. No roles, no events, just iteration.

Hat-based mode adds structure: specialized personas coordinate through events. You define the roles that fit your workflow — reviewers, testers, documenters, whatever makes sense. Presets provide ready-made patterns like TDD or spec-driven development.

The Ralph Tenets

1. Fresh Context Is Reliability — Each iteration clears context. Re-read specs, plan, code every cycle.
2. Backpressure Over Prescription — Don't prescribe how; create gates that reject bad work.
3. The Plan Is Disposable — Regeneration costs one planning loop. Cheap.
4. Disk Is State, Git Is Memory — Files are the handoff mechanism.
5. Steer With Signals, Not Scripts — Add signs, not scripts.
6. Let Ralph Ralph — Sit on the loop, not in it.

See AGENTS.md for the full philosophy.

Features

• Multi-Backend Support — Works with Claude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, and OpenCode
• Hat System — Specialized Ralph personas with distinct behaviors
• Event-Driven Coordination — Hats communicate through typed events with glob pattern matching
• Backpressure Enforcement — Gates that reject incomplete work (tests, lint, typecheck)
• Presets Library — 20+ pre-configured workflows for common development patterns
• Interactive TUI — Real-time terminal UI for monitoring Ralph's activity (enabled by default)
• Memories — Persistent learning across sessions stored in .agent/memories.md
• Tasks — Runtime work tracking stored in .agent/tasks.jsonl
• Multi-Loop Concurrency — Run parallel loops in git worktrees with automatic merge workflow
• Session Recording — Record and replay sessions for debugging and testing (experimental)

Installation

Prerequisites

• Rust 1.75+
• At least one AI CLI:
  • Claude Code (recommended)
  • Kiro
  • Gemini CLI
  • Codex
  • Amp
  • Copilot CLI (`npm install -g @

...