Skip to content

Ralph Orchestrator

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

License Rust Build

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

What is Ralph?

Ralph implements the Ralph Wiggum technique — autonomous task completion through continuous iteration. Give Ralph a task, and it will keep working until it's done.

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

Two Modes of Operation

Mode Description Best For
Traditional Simple loop — Ralph iterates until done Quick tasks, simple automation
Hat-Based Specialized personas coordinate through events Complex workflows, multi-step processes

Key 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 coordinating through typed events

  • Backpressure Enforcement

    Gates that reject incomplete work — tests, lint, typecheck must pass

  • Memories & Tasks

    Persistent learning across sessions and runtime work tracking

  • Interactive TUI

    Real-time terminal UI for monitoring Ralph's activity

  • 31 Presets

    Pre-configured workflows for TDD, spec-driven development, debugging, and more

Quick Example

# Initialize with traditional mode
ralph init --backend claude

# Create a task
cat > PROMPT.md << 'EOF'
Build a REST API with these endpoints:
- POST /users - Create user
- GET /users/:id - Get user by ID
- PUT /users/:id - Update user

Use Express.js with TypeScript.
EOF

# Run Ralph
ralph run

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

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.

Getting Started

Architecture

Ralph is organized as a Cargo workspace with seven crates:

Crate Purpose
ralph-proto Protocol types: Event, Hat, Topic
ralph-core Business logic: EventLoop, Config
ralph-adapters CLI backend integrations
ralph-tui Terminal UI with ratatui
ralph-cli Binary entry point
ralph-e2e End-to-end testing
ralph-bench Benchmarking

Community

License

Ralph Orchestrator is open source software licensed under the MIT License.

"I'm learnding!" - Ralph Wiggum