DOCSEARCHbyAlgolia
Submit Docs

Ralph Orchestrator Documentation

repository·main·Indexed 25 days ago

https://github.com/mikeyobrien/ralph-orchestrator

A hat-based orchestration framework implementing the 'Ralph Wiggum technique' for autonomous task completion via continuous iteration. It features specialized personas (hats), backpressure gates, and a Rust-native bootstrap runtime (ralph-api) for RPC v1 control. The system includes an E2E test harness (ralph-e2e) with cassette-based deterministic testing, a Telegram integration for human-in-the-loop interaction, and an MCP server for workspace management.

Tokens
209.9K
Snippets
563
Records
1.1K
Agent score
79%

What's inside Ralph Orchestrator

  2. Overview of Ralph Orchestrator Agent Skills

    main

    The skills/ directory provides a canonical public skill package for external agent harnesses to operate Ralph. It includes three distinct skills:

    • ralph-hats: Used for creating, inspecting, validating, and improving hat collections.
    • ralph-loop: Used for running, monitoring, resuming, merging, and debugging Ralph loops.
    • ralph-docs: Used for introspecting and improving Ralph via the published llms.txt doc map. This skill helps answer questions about Ralph's implementation and scopes code changes within the ralph-orchestrator repository.

    Note: These are public agent skills and are separate from Ralph's internal ralph tools skill registry.

  3. Overview of Ralph Orchestrator Architecture

    main

    Ralph Orchestrator is a multi-agent orchestration framework for AI coding assistants (such as Claude, Kiro, Gemini, and others) that uses an event-driven loop. It coordinates agents through "hats" (personas) that communicate via a pub/sub event bus with topic-based routing.

    Core Components

    • User Interfaces: ralph-cli (CLI), ralph-tui (Terminal UI), Web Dashboard (React), and ralph-telegram (Telegram Bot).
    • API Layer: ralph-api (Axum REST/WS) and @ralph-web/server (Fastify + tRPC).
    • Core Engine: ralph-core (Orchestration logic) and ralph-proto (Protocol types).
    • Agent Backends: ralph-adapters which integrates various AI backends.

  4. Overview of Prompt-Driven Development (PDD)

    main
    Prompt-Driven Development (PDD) is a methodology used to transform a rough idea into a detailed design document, an implementation plan, and a todo list. The process is iterative and involves refining requirements, conducting research, creating comprehensive designs, and developing actionable implementation plans.

  5. Overview of ralph-cli commands

    main

    The ralph-cli binary serves as the main entry point for the Ralph Orchestrator. It handles argument parsing, command routing, and runtime logging configuration.

    Available top-level commands include:

    • run, preflight, hooks, doctor, tutorial, events, init, clean, emit, plan, code-task (alias task), tools, loops, hats, tui, web, mcp, bot, completions.

  6. Overview of Ralph crates

    main

    Ralph is composed of several specialized crates. Use the following guide to identify which crate meets your needs:

    • ralph-proto: Provides core protocol types including Event, Hat, and Topic.
    • ralph-core: Contains the orchestration engine, including EventLoop and Config.
    • ralph-adapters: Provides backend integrations and CLI backends.
    • ralph-tui: Provides Terminal UI components (Experimental).
    • ralph-cli: The primary binary entry point for CLI commands.

  7. Overview of Ralph Orchestrator Features

    main

    Ralph provides several core capabilities for AI orchestration:

    • Multi-Backend Support: Integrates with Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, and OpenCode.
    • Hat System: Uses specialized personas with distinct behaviors that communicate via typed events.
    • Backpressure Enforcement: Uses gates (such as tests, linting, or typechecking) to reject incomplete or incorrect work.
    • Memories & Tasks: Provides persistent learning across sessions and tracks runtime work.
    • Interactive TUI: Includes a real-time terminal user interface for monitoring activity.
    • Presets: Includes 31 built-in workflows and a catalog of examples.

  9. Understand Agent Waves for parallel execution

    main

    Agent Waves provide a mechanism for intra-loop parallelism within Ralph's orchestration loop. Instead of executing hats sequentially, a dispatcher hat can fan out work to multiple concurrent backend instances (workers), collect their results, and aggregate them in a single orchestration run.

    Key Use Cases:

    • Deep research (parallel topic exploration)
    • Multi-perspective analysis
    • Parallel code review
    • Scatter-gather patterns
    • Multi-agent debate patterns

    Core Primitives:

    1. Wave-aware event emission: Events are tagged with correlation metadata (wave_id, wave_index, wave_total).
    2. Concurrent hat execution: The loop runner spawns multiple backend processes in parallel.
    3. Aggregator gate: A specific hat that buffers results and activates only once all correlated results have arrived.

  10. Explore the Orchestrator API Reference

    main

    The ralph_orchestrator module provides the core orchestration capabilities. For detailed information on specific components, refer to the following API documentation sections:

    • Configuration API: Manage orchestrator settings and parameters.
    • Agent API: Control and configure different agent types.
    • Metrics API: Access performance and operational metrics.
    • CLI Reference: Command-line interface usage and flags.

  11. Understand the scope of Agent Waves v1

    main

    Agent Waves v1 provides a framework for concurrent execution and event correlation.

    Included in v1:

    • Wave CLI tools: Commands for managing waves via ralph wave start, ralph wave emit, and ralph wave end.
    • Event correlation metadata: Every event includes wave_id, wave_index, and wave_total for tracking.
    • Concurrent execution: Backend spawning in the loop runner respects a defined concurrency limit.
    • Aggregation: Supports aggregate.mode: wait_for_all with a specified timeout.
    • Context injection: Downstream hat descriptions are injected into prompts for Natural Language (NL) dispatch.
    • Failure handling: Implements best-effort failure handling.
    • Accounting: Provides per-instance activation and cost accounting.
    • Workspace: Uses a shared workspace (no isolation).
    • Constraints: Does not support nested waves.

    Deferred to v2+:

    • Worktree isolation (isolation: worktree)
    • Nested waves
    • Additional aggregation modes (first_n, quorum, external_event)
    • Configurable failure modes (on_failure: fail_fast)
    • Wave-level cost limits (max_wave_cost)
    • Dedicated aggregator backends
    • Multi-round debate optimization

  12. Understand the Ralph Wiggum Technique

    main

    The Ralph Wiggum technique is an approach to autonomous AI task completion based on continuous iteration. Instead of directing an AI through step-by-step instructions, you define success criteria upfront and allow the AI to iterate in a loop until those criteria are met.

    Core Principles

    • Fresh Context Each Iteration: Each cycle starts with a clean slate, re-reading the prompt and codebase to prevent getting stuck in local minima.
    • Disk Is State: The only persistent state used by the agent is what is written to disk (e.g., PROMPT.md, the codebase, Git history, and .ralph/agent/memories.md).
    • Eventual Consistency: The technique relies on the idea that given enough iterations, a solution will emerge for any achievable task.
    • Predictable Failure Modes: Failures occur through observable limits such as iteration count, cost, time, or loop detection (repetitive outputs).

    When to Use

    • Recommended for: Large refactors, migrations, batch operations (docs, tests), greenfield scaffolding, and tasks with well-defined completion criteria.
    • Avoid for: Ambiguous requirements, tasks requiring human judgment, security-sensitive code, or exploratory work.