Skip to content

Concepts

Understanding Ralph's core concepts will help you use it effectively.

Overview

Ralph is built around a few key ideas:

  1. The Ralph Wiggum Technique — Continuous iteration until success
  2. The Six Tenets — Guiding principles for orchestration
  3. Hats & Events — Specialized personas coordinating through typed events
  4. Coordination Patterns — Multi-agent workflow architectures
  5. Memories & Tasks — Persistent learning and runtime work tracking
  6. Backpressure — Quality gates that reject incomplete work

The Core Philosophy

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

Ralph is intentionally simple. Rather than building complex features into the orchestrator, Ralph:

  • Trusts the agent to do the actual work
  • Provides structure through hats and events
  • Enforces quality through backpressure gates
  • Maintains state through files on disk

Traditional vs Hat-Based Mode

Ralph supports two orchestration styles:

Traditional Mode

A simple loop that runs until completion:

cli:
  backend: "claude"

event_loop:
  completion_promise: "LOOP_COMPLETE"
  max_iterations: 100

The agent iterates until it outputs LOOP_COMPLETE or hits limits.

Hat-Based Mode

Specialized personas coordinate through events:

cli:
  backend: "claude"

event_loop:
  starting_event: "task.start"
  completion_promise: "LOOP_COMPLETE"

hats:
  planner:
    triggers: ["task.start"]
    publishes: ["plan.ready"]
    instructions: "Create a plan..."

  builder:
    triggers: ["plan.ready"]
    publishes: ["build.done"]
    instructions: "Implement the plan..."

Events flow between hats, each contributing to the task.

Key Concepts Summary

Concept Description
Iteration One cycle of the orchestration loop
Completion Promise Signal that ends the loop (default: LOOP_COMPLETE)
Hat Specialized Ralph persona with specific triggers and behaviors
Event Typed message that triggers hats and carries state
Backpressure Quality gate (tests, lint, typecheck) that rejects bad work
Memory Persistent learning stored in .ralph/agent/memories.md
Task Runtime work item stored in .ralph/agent/tasks.jsonl

Next Steps