Ralph Orchestrator — Codebase Summary

Multi-agent orchestration framework for AI coding assistants. Version 2.6.0 | Rust + TypeScript | MIT License

---

Table of Contents

• Project Overview
• Architecture
• Workspace Structure
• Crate & Package Guide
• Core Concepts
• Interfaces & Protocols
• Data Models
• Key Workflows
• Configuration
• Testing
• Detailed Documentation

---

Project Overview

Ralph Orchestrator coordinates AI coding assistants (Claude, Kiro, Gemini, Codex, Amp, Pi) through an event-driven loop. Agents wear "hats" (personas) that define their behavior, and communicate via a pub/sub event bus with topic-based routing.

---

Architecture

graph TB
    subgraph "User Interfaces"
        CLI["ralph-cli<br/>CLI Entry Point"]
        TUI["ralph-tui<br/>Terminal UI"]
        WEB["Web Dashboard<br/>React + Vite"]
        TEL["ralph-telegram<br/>Telegram Bot"]
    end

    subgraph "API Layer"
        API["ralph-api<br/>Axum REST/WS"]
        WEBAPI["@ralph-web/server<br/>Fastify + tRPC"]
    end

    subgraph "Core Engine"
        CORE["ralph-core<br/>Orchestration Logic"]
        PROTO["ralph-proto<br/>Protocol Types"]
    end

    subgraph "Agent Backends"
        ADAPT["ralph-adapters"]
        CLAUDE["Claude"] 
        KIRO["Kiro"]
        GEMINI["Gemini"]
        OTHER["Codex / Amp / Pi"]
    end

    CLI --> CORE
    TUI --> API
    TUI --> CORE
    WEB --> WEBAPI
    TEL --> CORE
    API --> CORE
    CORE --> PROTO
    CORE --> ADAPT
    ADAPT --> CLAUDE
    ADAPT --> KIRO
    ADAPT --> GEMINI
    ADAPT --> OTHER

Design Principles (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 (tests, typechecks, lints).
3. The Plan Is Disposable — Regeneration costs one planning loop.
4. Disk Is State, Git Is Memory — Memories and Tasks are the handoff mechanisms.
5. Steer With Signals, Not Scripts — The codebase is the instruction manual.
6. Let Ralph Ralph — Sit on the loop, not in it.

---

Workspace Structure

ralph-orchestrator/
├── crates/                 # Rust workspace (9 crates)
│   ├── ralph-proto/        # Protocol definitions, shared types, traits
│   ├── ralph-core/         # Event loop, hats, memories, tasks, hooks, coordination
│   ├── ralph-adapters/     # Backend integrations (Claude, Kiro, Gemini, etc.)
│   ├── ralph-cli/          # CLI entry point, all user-facing commands
│   ├── ralph-tui/          # Terminal UI (ratatui-based, 3 operating modes)
│   ├── ralph-telegram/     # Telegram bot for human-in-the-loop
│   ├── ralph-api/          # REST/WebSocket API server (Axum)
│   ├── ralph-e2e/          # End-to-end test framework
│   └── ralph-bench/        # Benchmarking
├── backend/ralph-web-server/  # @ralph-web/server (Fastify + tRPC + SQLite)
├── frontend/ralph-web/        # @ralph-web/dashboard (React + Vite + TailwindCSS)
├── presets/                # Hat collection YAML presets
├── cassettes/              # Replay fixtures for smoke/E2E tests
├── docs/                   # MkDocs documentation site
├── scripts/                # Build and CI helpers
└── .ralph/                 # Runtime state directory
    ├── agent/memories.md   # Persistent learning
    ├── agent/tasks.jsonl   # Runtime task tracking
    ├── events.jsonl        # Event history
    ├── loop.lock           # Primary loop PID lock
    ├── loops.json          # Loop registry
    └── merge-queue.jsonl   # Worktree merge queue

---

Crate & Package Guide

ralph-proto — Protocol Definitions

Foundational types used across all crates: Event, EventBus, Hat, Topic, RpcCommand/RpcEvent, RobotService trait, DaemonAdapter trait, UxEvent.

ralph-core — Orchestration Engine

The largest crate, containing:

• Event Loop (event_loop/mod.rs): Main orchestration loop
• HatlessRalph (hatless_ralph.rs): Constant coordinator, prompt builder
• Configuration (config.rs): Full config model with v1/v2 support
• Memory System (memory.rs, memory_store.rs): Persistent learning in markdown
• Task System (task.rs, task_store.rs): JSONL-based work tracking
• Hooks (hooks/): Lifecycle event handlers with warn/block/suspend
• Skills (skill.rs, skill_registry.rs): Skill discovery and injection
• Parallel Loops (worktree.rs, loop_lock.rs, merge_queue.rs): Git worktree coordination
• Diagnostics (diagnostics/): Agent output, orchestration, error, performance collectors

ralph-adapters — Backend Integrations

Executes AI coding assistants: CliBackend (command construction), CliExecutor (output capture), PtyExecutor (PTY-based execution), auto_detect (PATH scanning), stream parsers for Claude and Pi protocols.

ralph-cli — CLI Entry Point

All user-facing commands: run, init, plan, code-task, tools, loops, hats, events, clean, emit, bot, web, tui, hooks, preflight, doctor, completions. Implements subprocess TUI mode (two-process architecture).

ralph-tui — Terminal UI

Three operating modes: in-process (EventBus observer), RPC client (HTTP/WS to ralph-api), subprocess RPC (JSON-lines over stdin/stdout). Built with ratatui + crossterm.

ralph-telegram — Telegram Bot

Bidirectional human-in-the-loop: human.interact (agent asks question, loop blocks), human.response (human replies), human.guidance (proactive guidance). Implements RobotService trait via TelegramService.

ralph-api — REST/WebSocket Server

Axum-based API with domains: loop management, task CRUD, planning sessions, preset browsing, configuration, hat collections, real-time event streaming.

@ralph-web/server — Node.js Backend

Fastify + tRPC + SQLite: task queue with persistent storage, Ralph process supervision, event parsing, log streaming, config merging.

@ralph-web/dashboard — React Frontend

Task management, visual hat collection builder (React Flow), PDD planning UI, loop monitoring with WebSocket updates.

---

Core Concepts

Event-Driven Orchestration

The EventBus routes events between hats using topic-based pub/sub:

1. Agent writes events to .ralph/events.jsonl
2. Event loop parses and publishes events
3. EventBus routes to subscribed hats (specific patterns > wildcard fallbacks)
4. Next hat with pending events is activated

Hat System

Hats define agent behavior per iteration. Default topology: Planner (subscribes: task.start, build.done, build.blocked; publishes: build.task) → Builder (subscribes: build.task; publishes: build.done, build.blocked). Custom hats are defined in YAML with triggers, publications, instructions, and optional per-hat backends.

Parallel Loops

When the primary loop lock is held, Ralph spawns parallel loops in git worktrees (.worktrees/<loop-id>/). Shared state (memories, specs, tasks) is symlinked. Completed loops queue for merge via .ralph/merge-queue.jsonl.

Hook Lifecycle

Hooks fire at 12 lifecycle points (pre/post for: loop.start, iteration.start, plan.created, human.interact, loop.complete, loop.error). Failure modes: warn (continue), block (stop), suspend (pause and await recovery).

---

Interfaces & Protocols

JSON-RPC Protocol (stdin/stdout)

Newline-delimited JSON for IPC between loop and frontends.

Commands (stdin → Ralph): prompt, guidance, steer, follow_up, abort, get_state, get_iterations, set_hat, extension_ui_response

Events (Ralph → stdout): loop_started, iteration_start, iteration_end, text_delta, tool_call_start, tool_call_end, error, hat_changed, task_status_changed, task_counts_updated, guidance_ack, loop_terminated, orchestration_event, response

Key Rust Traits

• RobotService (ralph-proto): Human-in-the-loop communication (send question, wait response, send checkin)
• DaemonAdapter (ralph-proto): Persistent bot daemon (run_daemon)
• FrameCapture (ralph-proto): Terminal output capture for recording/replay
• HookExecutorContract (ralph-core): Hook command execution

EventBus Routing Rules

1. Direct target → route only to that hat
2. Specific subscriptions → route to matching non-wildcard patterns
3. Fallback wildcards → global * subscribers
4. Self-routing allowed (handles LLM non-determinism)
5. human.* events use separate queue

---

Data Models

Core Types

File-Based State

Termination Reasons

---

Key Workflows

Orchestration Loop

flowchart TD
    START([ralph run]) --> LOAD[Load & Validate Config]
    LOAD --> LOCK{Acquire Loop Lock}
    LOCK -->|Success| INIT[Initialize Event Loop]
    LOCK -->|Locked| WT[Create Worktree Loop]
    WT --> INIT
    INIT --> PROMPT[Build Prompt<br/>Guardrails + Hat + Memories + Skills]
    PROMPT --> EXEC[Execute Agent Backend]
    EXEC --> PARSE[Parse Events from JSONL]
    PARSE --> ROUTE[Route via EventBus]
    ROUTE --> CHECK{Termination?}
    CHECK -->|No| NEXT[Select Next Hat]
    NEXT --> PROMPT
    CHECK -->|Yes| DONE[Landing & Cleanup]

Subprocess TUI Mode (Default)

flowchart LR
    subgraph Parent
        TUI[ratatui UI]
        WRITER[RPC Writer]
        READER[Event Reader]
    end
    subgraph Child["ralph run --rpc"]
        RPC_IN[stdin reader]
        LOOP[Event Loop]
        RPC_OUT[stdout JSON]
    end
    WRITER -->|commands| RPC_IN
    RPC_OUT -->|events| READER
    READER --> TUI

---

Configuration

Configuration uses a split model:

1. Core config (ralph.yml): backend, event loop, features, hooks, memories, tasks
2. Hat collections (-H builtin:feature or YAML): hat definitions, event metadata

Supports both v1 (flat: agent: claude, max_iterations: 100) and v2 (nested: cli.backend, event_loop.max_iterations) formats with automatic normalization.

Key config sections: event_loop (iterations, runtime, cost limits, completion_promise), cli (backend, prompt_mode), core (scratchpad, specs_dir, guardrails), hats (custom hat definitions), hooks (lifecycle hooks), memories (inject mode, budget, filters), tasks (enabled), skills (directories, overrides), features (parallel, auto_merge, preflight), RObot (Telegram integration).

---

Testing

cargo build                                    # Build all crates
cargo test                                     # Run all tests
cargo test -p ralph-core test_name             # Single test
cargo test -p ralph-core smoke_runner          # Smoke tests (replay-based)
cargo run -p ralph-e2e -- --mock               # E2E tests (CI-safe)
npm run test:server                            # Backend tests

• Unit tests: Throughout all crates
• Smoke tests: Replay-based using recorded JSONL fixtures in crates/ralph-core/tests/fixtures/
• E2E tests: Full orchestration with mock or live backends, reports in .e2e-tests/
• Session recording: ralph run --record-session file.jsonl captures sessions for replay

---

Detailed Documentation

For in-depth information, see the .agents/summary/ directory: