# Ralph Orchestrator: the hat-based loop that keeps AI coding agents working until LOOP_COMPLETE

> Ralph Orchestrator is a Rust CLI that runs Claude Code, Codex, Gemini CLI and other backends in a loop, coordinating specialised hats through events and rejecting incomplete work with backpressure gates. It suits engineers who already drive a coding agent from the terminal and want the loop, the specs and the human handoff managed for them.

**mikeyobrien/ralph-orchestrator** — An improved implementation of the Ralph Wiggum technique for autonomous AI agent orchestration

- Repository: https://github.com/mikeyobrien/ralph-orchestrator
- Stars: 3,164 · Forks: 299
- Language: Rust
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/mikeyobrien-ralph-orchestrator

## The problem Ralph Orchestrator solves, and who it is for

Most coding agents stop when they believe they are finished. Ralph Orchestrator assumes the opposite: an agent stops too early, and the fix is to run it again, in a structured loop, until a completion signal appears. The README describes the project as "a hat-based orchestration framework that keeps AI agents in a loop until the task is done", and the loop terminates when the agent outputs LOOP_COMPLETE or the iteration limit is reached.

The target user is an engineer already comfortable with a terminal-driven agent such as Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Pi, Roo or OMP. Those are the backends the README lists as supported. If you have never run one of those CLIs, Ralph adds a layer before it adds value.

The second audience is anyone who wants planning separated from implementation. The ralph plan command runs an interactive PDD session and writes requirements.md, design.md and implementation-plan.md into a spec directory, which the later run consumes. That is a deliberate choice: the plan becomes a file on disk rather than a conversation you have to remember.

## Hats, events and backpressure: the mechanism

The core abstraction is the hat, a specialised persona that reacts to events. Instead of one agent prompt doing everything, several hats coordinate, and the orchestration layer decides which one acts next. The repository ships five builtins the README names explicitly: code-assist, debug, research, review and pdd-to-code-assist. Anything beyond those is documented as examples rather than builtins, which is a meaningful boundary: if your workflow does not resemble one of the five, you are authoring hats, not configuring them.

Backpressure is the second half of the mechanism. Gates reject incomplete work on tests, lint and typecheck, so a loop iteration that produces failing output does not count as progress. This is where the design earns its keep. A plain while loop around an agent will happily accept a half-finished refactor; a gate will not.

State lives in the workspace. The README states that the control-plane APIs persist config, tasks, loops, planning sessions and collections under a single workspace root. That single-root assumption explains the MCP server design below, and it also means your repository layout is part of the configuration surface.

RObot adds a human channel. Agents emit human.interact events and the loop blocks until a response arrives or the request times out. Proactive messages can be sent at any time, and routing works via reply-to, an @loop-id prefix, or a default to the primary loop. The commands /status, /tasks and /restart give visibility while a loop is running.

## Installing Ralph Orchestrator and running a first loop

The README recommends npm. Pick one of the three documented routes; the note in the installation section says Homebrew is not currently published from the repository's automated release flow, so npm, Cargo or the GitHub Releases installer are the options.

```bash
npm install -g @ralph-orchestrator/ralph-cli
```

The Cargo route installs the same CLI if you already have a Rust toolchain. The badge in the README lists rust 1.75+.

```bash
cargo install ralph-cli
```

There is also a shell installer that pulls the latest release asset.

```bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh
```

Initialise against a backend, then plan. The plan step is interactive and, per the README, creates .ralph/specs/user-authentication/ with requirements.md, design.md and implementation-plan.md.

```bash
ralph init --backend claude
ralph plan "Add user authentication with JWT"
```

Finally, run the loop against the spec directory. Ralph iterates until the agent outputs LOOP_COMPLETE or the iteration limit is hit.

```bash
ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
```

For a smaller change you can skip planning entirely and run directly against a prompt, as the README shows with an input-validation example. The web dashboard is a separate command, ralph web, which starts the Rust RPC API and the frontend and opens a browser; it accepts --backend-port, --frontend-port and --no-open, plus --legacy-node-api for the deprecated Node tRPC backend.

## Where Ralph Orchestrator gets awkward

The toolchain requirement is real. The dashboard needs a Rust toolchain for ralph-api and Node.js >= 18 plus npm for the frontend; the package.json engines field asks for node >=22.0.0. On first run ralph web auto-detects missing node_modules and runs npm install, which means the first launch is not instant and depends on network access. If you wanted a single static binary with no runtime dependencies, this is not that.

The web dashboard is labelled Alpha in the README, with the warning that you should "expect rough edges and breaking changes". Treat the CLI as the stable surface and the dashboard as a preview.

The MCP server is scoped to one workspace root per instance. Precedence is --workspace-root, then the RALPH_API_WORKSPACE_ROOT environment variable, then the current working directory. The README is explicit that for multi-repo use you run one server instance per repo, because the control-plane APIs persist under a single workspace root. That is a deliberate constraint rather than a bug, but it rules out a single MCP server fronting several repositories.

The Dockerfile in the repository is worth reading before you assume it matches the Rust CLI. It builds from python:3.11-slim, installs uv, and copies a Python environment, and the docker-compose service passes flags like --agent and --prompt to a ralph_orchestrator.py entrypoint. The README's installation section points at npm, Cargo and the release installer instead. If you plan to deploy with docker-compose.yml, verify which generation of the tool that image actually runs before you build a pipeline around it.

## How it differs from a plain agent loop or a workflow engine

The obvious alternative is the loop you write yourself: a shell for-loop that pipes a prompt into your agent CLI and greps the output for a stop token. That gets you iteration and nothing else. Ralph Orchestrator adds three things on top: hats that route work between personas, gates that validate output before the loop advances, and memories and tasks that persist across iterations. If your task is genuinely one-shot, the shell loop is less machinery for the same result.

The second alternative is a general workflow engine such as a CI pipeline with staged jobs. Those are deterministic: you declare the steps and they run. Ralph Orchestrator is not deterministic in that sense, because the agent decides what to do inside an iteration. What it borrows from CI is the gate idea, applied to work an LLM produced rather than to work a compiler produced.

The third comparison is the original Ralph Wiggum technique, which the README links to. Ralph Orchestrator calls itself "an improved implementation", and the additions are the hat system, backpressure, memories and multi-backend support. If you only want the raw technique, the loop is a few lines of shell; the value here is in the coordination layer around it.

## Licence, releases and what upgrades cost you

The project is MIT licensed, and the workspace Cargo.toml sets license = "MIT" for every crate. That is permissive and imposes no copyleft obligation on your own code, though the usual caveat applies: this is a description of the licence field, not legal advice, and the LICENSE file in the repository root is the authoritative text.

The release cadence visible in the repository is uneven. v2.10.1 was tagged on 2026-06-22 and v2.10.0 the day before; v2.9.3 landed on 2026-05-08. The last push to the default branch was on 2026-09-10, so the codebase has moved since the most recent release. That gap matters if you pin to a release: you may be running something several weeks behind the branch.

Upgrade cost is dominated by the Alpha dashboard and by configuration drift. The README documents a --legacy-node-api flag for a deprecated Node tRPC backend, which tells you the web layer has already changed shape once. If your setup depends on the dashboard rather than the CLI, budget for breakage between minor versions. The CLI commands shown in the README (init, plan, run, web, mcp serve, bot onboard) are the surface most likely to stay put.

## Conclusion

Adopt Ralph Orchestrator if you already run a coding agent from the terminal and want the iteration loop, spec files and a human handoff channel handled by one binary; the npm install, ralph init --backend claude and ralph run -p sequence is short enough to evaluate in an afternoon. Skip it if you need a single-command installer with no Rust or Node toolchain, if you want a stable web UI (the dashboard is labelled Alpha), or if you cannot accept that one MCP server instance is scoped to one workspace root. Verify two things first: that your chosen backend appears in the supported list, and that the presets/ directory contains a hat graph matching your workflow, because the README documents five builtins and describes the rest as examples.

## FAQ

### What is the purpose of Ralph Orchestrator?

It keeps an AI coding agent in a loop until a task is finished, coordinating specialised hats through events and using backpressure gates to reject incomplete work. The README describes it as a hat-based orchestration framework that supports multiple backends such as Claude Code, Kiro, Gemini CLI and Codex.

### Is the Ralph loop still relevant?

The repository's last push to the default branch was on 2026-09-10 and the most recent release, v2.10.1, was tagged on 2026-06-22, so the project is still being worked on. Whether the technique suits you depends on your task: it fits work that needs repeated attempts and validation gates, and is unnecessary for one-shot changes.

### What does Ralph Loop stand for?

The README ties the name to the Ralph Wiggum technique, which it describes as autonomous task completion through continuous iteration, and links to an external write-up on the technique. The loop itself ends when the agent outputs LOOP_COMPLETE or the iteration limit is reached.

### What are the top 3 AI agents?

The README does not rank backends. It lists Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Pi, Roo and OMP as supported, and you select one with ralph init --backend.

## Sources

- [Issues](https://github.com/mikeyobrien/ralph-orchestrator/issues)
- [License: MIT](https://github.com/mikeyobrien/ralph-orchestrator/blob/main/LICENSE)
- [mikeyobrien/ralph-orchestrator on GitHub](https://github.com/mikeyobrien/ralph-orchestrator)
- [README](https://github.com/mikeyobrien/ralph-orchestrator/blob/main/README.md)
- [Releases](https://github.com/mikeyobrien/ralph-orchestrator/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mikeyobrien-ralph-orchestrator