# Ralph Orchestrator

> A hat-based orchestration framework that keeps AI agents in a loop until the task is done, supporting multiple backends like Claude Code, Gemini CLI, and Codex.

Ralph Orchestrator is an open-source, MIT-licensed CLI tool built in Rust that implements the "Ralph Wiggum technique" — autonomous task completion through continuous iteration. Created by mikeyobrien and mentioned in the Awesome Claude Code list, it has accumulated over 3,000 GitHub stars since its September 2025 creation. The project is actively maintained, with the latest release v2.10.1 published in June 2026.

## What It Is

Ralph Orchestrator is an agent orchestration framework that wraps AI coding assistant CLIs and keeps them running in a loop until a task is fully complete. Rather than issuing a single prompt and accepting whatever output comes back, Ralph iterates — checking backpressure gates like tests, lint, and typecheck — and only exits when the agent signals `LOOP_COMPLETE` or the iteration limit is reached. It is installed as a CLI tool via npm, Cargo, or a GitHub Releases shell installer.

## The Hat System and Backends

The core abstraction in Ralph is the "hat" — a specialized persona that coordinates work through an event system. Five built-in hats ship out of the box:

- **code-assist** — general coding tasks
- **debug** — targeted debugging sessions
- **research** — information gathering
- **review** — code review workflows
- **pdd-to-code-assist** — planning-driven development to implementation

Ralph supports eight AI coding backends: Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, and OpenCode. Users initialize with `ralph init --backend <name>` and then run tasks against whichever backend is configured.

## Planning and Workflow

Ralph includes a structured planning workflow called PDD (Planning-Driven Development). Running `ralph plan "Add user authentication with JWT"` opens an interactive session that produces `requirements.md`, `design.md`, and `implementation-plan.md` under `.ralph/specs/`. The subsequent `ralph run` command picks up those specs and drives the agent through implementation. For simpler tasks, the planning step can be skipped entirely.

## RObot: Human-in-the-Loop via Telegram

Ralph ships a human-in-the-loop feature called RObot that routes agent questions and human guidance through Telegram. Agents can emit `human.interact` events that block the loop until a human responds; humans can also send proactive steering messages at any time. Parallel loop routing supports reply-to threading, `@loop-id` prefixes, and a default primary loop. Telegram commands `/status`, `/tasks`, and `/restart` provide real-time loop visibility without leaving the messaging app.

## Web Dashboard and MCP Server

An alpha web dashboard (`ralph web`) starts a Rust RPC API alongside a Node.js frontend for monitoring and managing orchestration loops. The dashboard is under active development and the README notes to expect rough edges and breaking changes. Ralph also runs as an MCP server over stdio (`ralph mcp serve`), scoped to a single workspace root per instance, making it compatible with any MCP-capable client. Multi-repo setups run one server instance per workspace.

## Update: v2.10.1

The latest release is v2.10.1, published on 2026-06-23. The repository was last pushed to on 2026-07-10, indicating active ongoing development. The project is listed in the Awesome Claude Code curated list and has 284 forks, signaling community adoption and contribution activity. System requirements are Rust 1.75+, Node.js 18+, and at least one supported AI coding assistant CLI.

## Features
- Hat-based orchestration with specialized personas
- Multi-backend support: Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode
- Backpressure gates (tests, lint, typecheck) that reject incomplete work
- Persistent memories and runtime task tracking
- Planning-Driven Development (PDD) workflow
- RObot human-in-the-loop via Telegram
- Alpha web dashboard for monitoring orchestration loops
- MCP server mode over stdio
- 5 built-in presets: code-assist, debug, research, review, pdd-to-code-assist
- Continuous iteration until LOOP_COMPLETE signal

## Integrations
Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Telegram, MCP clients, npm, Cargo

## Platforms
MACOS, WEB, API, CLI

## Pricing
Open Source

## Version
v2.10.1

## Links
- Website: https://github.com/mikeyobrien/ralph-orchestrator
- Documentation: https://mikeyobrien.github.io/ralph-orchestrator/
- Repository: https://github.com/mikeyobrien/ralph-orchestrator
- EveryDev.ai: https://www.everydev.ai/tools/ralph-orchestrator