Ralph Orchestrator

Ralph Orchestrator

A hat-based orchestration framework that keeps AI agents in a loop until the task is done.
"Me fail English? That's unpossible!" - Ralph Wiggum

Documentation | Getting Started | Presets

Installation

Via npm (Recommended)

Via GitHub Releases installer

Via Cargo
Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.

Quick Start

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

For simpler tasks, skip planning and run directly:

Web Dashboard (Alpha)
Alpha: The web dashboard is under active development. Expect rough edges and breaking changes.

Ralph includes a web dashboard for monitoring and managing orchestration loops.

MCP Server Workspace Scope

ralph mcp serve is scoped to a single workspace root per server instance.

Precedence is:

1. --workspace-root
2. RALPH_API_WORKSPACE_ROOT
3. current working directory

For multi-repo use, run one MCP server instance per repo/workspace. Ralph's current
control-plane APIs persist config, tasks, loops, planning sessions, and collections
under a single workspace root, so server-per-workspace is the deterministic model.

Requirements:
- Rust toolchain (for ralph-api)
- Node.js >= 18 + npm (for the frontend)

On first run, ralph web auto-detects missing node_modules and runs npm install.

To set up Node.js:

For development:

MCP Server Mode

Ralph can run as an MCP server over stdio for MCP-compatible clients:

Use this mode from an MCP client configuration rather than an interactive terminal workflow.

What is Ralph?

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

- Multi-Backend Support — Claude Code, Kiro, Gemini CLI, Codex,…