Ralph Orchestrator is an open-source, Rust-based harness created by Mikey O'Brien that implements the Ralph Wiggum technique for autonomous AI agent execution. Instead of terminating after a single response, Ralph executes underlying AI agents inside continuous feedback loops, repeating cycles until tasks meet validation criteria or emit a completion signal. In daily development, users operate Ralph through the CLI, an alpha web UI, or an MCP server interface. Workflows can start with prompt-driven development (PDD) planning to generate requirements, design specifications, and implementation steps in the `.ralph/specs/` directory. Ralph then drives tasks across multiple CLI backends—including Claude Code, Kiro, Gemini CLI, Codex, Copilot CLI, and OpenCode—managing state and context between iterations. What differentiates Ralph from standard single-agent runners is its hat-based architecture and backpressure enforcement. Hats act as specialized personas that coordinate through event emission, while backpressure gates automatically execute tests, linter passes, and typechecks to reject incomplete or broken agent outputs. It also includes RObot, an optional Telegram integration for human-in-the-loop blocking questions and mid-flight steering. Ralph Orchestrator is free, open-source software released under the MIT license. It is distributed via npm, Cargo, and pre-built shell installers.
Tags: agent harness, ai agent, cli, coding agent, OpenSource
LOOP_COMPLETE, or hit loop limits. - Multi-Backend Engine — Integrates with CLI agent tools including Claude Code, Kiro, Gemini CLI, Codex, OpenCode, Copilot CLI, Amp, Pi, Roo, and OMP. - Hat Persona System — Coordinates task execution through specialized event-driven roles, including builtins for code-assist, debug, research, review, and pdd-to-code-assist. - Automated Backpressure Gates — Prevents premature completion by running automated verification checks (unit tests, typecheckers, linters) before closing loops. - Prompt-Driven Development (PDD) — Interactively generates structured design, requirements, and plan artifacts in .ralph/specs/ before implementation. - Human-in-the-Loop (RObot) — Pauses agent execution to ask questions via Telegram and accepts real-time steering messages while tasks run. - MCP Server Support — Runs as a workspace-scoped Model Context Protocol server over stdio for integration with external MCP-compatible editors and clients.ralph plan to create structured requirement and design documents inside .ralph/specs/. Ralph then executes the plan in a continuous loop using the selected CLI backend (such as Claude Code), verifying code output against project test suites until complete.debug preset and pass in a failing test suite command. Ralph iterates on the codebase, inspecting error traces and modifying files until the test command exits cleanly without breaking existing tests.Ralph Orchestrator is designed for software engineers and teams seeking autonomous, test-verified execution loops on top of existing terminal AI agents like Claude Code or Codex CLI. It is not intended for non-technical users or developers looking for a simple single-turn conversational IDE extension.
bash npm install -g @ralph-orchestrator/ralph-cli Alternatively, install via Cargo or the shell installer: bash cargo install ralph-cli # or curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | shbash ralph init --backend claude If you plan to use human-in-the-loop Telegram notifications, run the onboarding command: bash ralph bot onboard --telegrambash ralph plan "Add JWT authentication to the /api/v1/auth routes" Execute the generated specification in an autonomous loop: bash ralph run -p "Implement the feature in .ralph/specs/jwt-authentication/" To run a task directly without a specification file: bash ralph run -p "Fix type errors and lint failures in src/auth/"Part of CLI Coding Agents
Categories: AI Coding Agents, Code Assistants, Developer Tools