Ralph Orchestrator
A hat-based orchestration framework that keeps AI agents looping until tasks are done, with multi-backend support and human-in-the-loop.
- Source repo
- mikeyobrien/ralph-orchestrator
- Stars
- ★ 3.2k
- Last updated
- 3d ago
- License
- MIT
- Primary language
- Rust
- FA score
- 48/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeChatGPT (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer uses Ralph with Claude Code backend to automatically implement complex features, reducing manual coding iterations.
- Not a fit if
- Teams needing a stable production web UI; the dashboard is alpha
- Users wanting a single runtime; Rust and Node.js are both required
- Teams unwilling to pay for or configure external AI coding CLIs
- Source review
- 48/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
Ralph Orchestrator is a Rust-based CLI framework implementing the Ralph Wiggum technique, driving AI agents in continuous iteration until task completion (LOOP_COMPLETE or iteration limit). It uses a "hat system" with specialized personas (code-assist, debug, research, review, pdd-to-code-assist) coordinating via events. It supports multiple backends: Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, and OpenCode. It includes a CLI, an alpha web dashboard, an MCP server mode, and an optional Telegram bot (RObot) for human-in-the-loop interaction. Installation is via npm, Cargo, or a GitHub Releases installer.
Ralph initializes projects (ralph init --backend), plans features (ralph plan) generating requirements, design, and implementation plan docs, then executes loops via ralph run -p. Agents loop until LOOP_COMPLETE or iteration limit. It uses the hat system with specialized personas and backpressure gates (tests, lint, typecheck) to reject incomplete work. ralph web starts a Rust RPC API and frontend dashboard for monitoring. ralph mcp serve provides an MCP server scoped to a single workspace root. ralph bot enables Telegram-based human interaction: agents can ask questions and block, humans can send proactive guidance. Configuration is in YAML files (e.g., ralph.yml).
- A developer uses Ralph with Claude Code backend to automatically implement complex features, reducing manual coding iterations.
- A team uses the web dashboard to monitor multiple agent loops in real time, tracking progress.
- An IDE or MCP client integrates Ralph via
ralph mcp servefor automated coding within the editor. - A remote developer uses the Telegram bot to receive agent questions and provide guidance, enabling human-in-the-loop workflows.
- A team uses the planning (PDD) feature to break down large features into spec documents before implementation, ensuring structured development.
How do you install or deploy this agent?
Recommended npm global install: npm install -g @ralph-orchestrator/ralph-cli. Alternatively via Cargo: cargo install ralph-cli, or using the GitHub Releases installer: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh. Requires Rust 1.75+ and Node.js >= 18 + npm (for the web dashboard).
How do you use this agent?
Initialize: ralph init --backend claude. Plan a feature: ralph plan "Add user authentication with JWT", generating spec docs. Run the implementation: ralph run -p "Implement the feature in .ralph/specs/user-authentication/". For simpler tasks, you can skip planning and run directly. Start the web dashboard with ralph web. For MCP server mode: ralph mcp serve --workspace-root /path/to/repo. To configure the Telegram bot: ralph bot onboard --telegram for guided setup.
What are this agent's strengths and limitations?
- Multi-backend support (Claude Code, Kiro, Gemini CLI, Codex, etc.) provides flexibility.
- Hat system with specialized roles and backpressure gates ensures work quality.
- Built-in memories and tasks for persistent learning and runtime tracking.
- Web dashboard and MCP server mode enable monitoring and integration.
- Web dashboard is in alpha; expect rough edges and breaking changes.
- Requires multiple runtimes (Rust, Node.js), adding environment complexity.
- Depends on external AI coding CLIs (e.g., Claude Code), which may incur costs.
- Homebrew is not officially supported, limiting installation options.
How does this agent compare with similar options?
Unlike single-shot AI assistants, Ralph iterates until completion using a hat system with specialized personas and backpressure gates. It supports multiple backends (Claude Code, Codex, etc.), whereas many competitors are tied to a single model.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Ralph Orchestrator This agent | 48 · Major gaps | CLIFree + model costs | ★ 3.2k | 3d ago | Rust | Codex · Claude Code |
| no_human | 67 · Some gaps | CLIFree + model costs | ★ 331 | 9d ago | Python | Claude Code |
| Rovai AI | 49 · Major gaps | — | ★ 195 | today | Rust | Codex · Claude Code |
| MetaHarness | 86 · Good | CLIFree + model costs | ★ 707 | 9d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: repository includes MIT license, CI workflows, dependency manifests (Cargo.toml/package.json), but lacks explicit documentation of permission model, user confirmation mechanisms, data flow transparency, sensitive data handling, dependency security audits, external effect controls, or rollback mechanisms. Deductions: these aspects lack concrete implementation or documentation evidence.
Evidence shows: good consistency among README, Cargo.toml, package.json, CI workflows, and test scenario files; dependency versions are explicit, but failure message handling is not detailed. Deductions: insufficient evidence for failure message handling.
Evidence shows: README describes multiple usage scenarios (CLI, MCP, Web, Telegram), multiple backend support, configuration options, and system requirements; capability boundaries and trigger conditions are explained. Deductions: environment fit details (e.g., specific platform limitations) are not fully covered.
Evidence shows: README provides installation instructions, quick start, FAQ, documentation links; license is explicit, version number exists, but clear changelog and known limitations are missing. Deductions: changelog and known limitations are absent.
Evidence shows: README demonstrates output formats (e.g., LOOP_COMPLETE), usage examples, and multiple installation methods, but cost-benefit analysis is not provided. Deductions: insufficient evidence for cost-benefit.
Evidence shows: claims in README (e.g., multi-backend support) are partially supported by test scenario files, but lack external corroboration and clear separation of facts and inferences. Deductions: insufficient cross-source corroboration and fact-inference separation.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- No explicit least-privilege or user confirmation mechanisms found; review actual code before use.
- Sensitive data handling (e.g., Telegram token) storage and transmission not documented; configure with caution.
- Dependency security audit not mentioned; recommend vulnerability scanning before use.
- Rollback mechanism not mentioned; implement if needed.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2.10.1 2.10.1 - 2026-06-22
Release notes excerpt
Release Notes Fixed - Restore e2e mock-mode verification by passing prompts to the cassette-backed custom backend over stdin. - Update the mock e2e single-iteration scenario to validate the completion signal instead of legacy scratchpad writes. - Isolate gitignore integration tests from user/global Git exclude files. ralph-bench 2.10.1 Install ralph-bench 2.10.1 Install prebuilt binaries via shell script ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.10.1/ralph-bench-installer.sh | sh ``` …View on GitHub ↗ -
v2.10.0 2.10.0 - 2026-06-21
Release notes excerpt
Release Notes Added - Forge CLI backend integration. - RObot (human-in-the-loop) RPC domain in the control plane, plus a file-backed web mode that drives human interaction through files instead of a live socket. - Worktree loops can publish remote review branches, with rebase support. - Local file-based hat imports in preflight, including import resolution and schema validation with imported-file context. - On-demand export of TUI iteration buffers to disk: e exports the current iteration, E exports all iterations. - Context-window utilization telemetry, surfaced in the TUI. …View on GitHub ↗ -
Release notes excerpt
ralph-bench 2.9.3 Install ralph-bench 2.9.3 Install prebuilt binaries via shell script ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.9.3/ralph-bench-installer.sh | sh ``` Install prebuilt binaries into your npm project ```sh npm install @ralph-orchestrator/[email protected] ``` Download ralph-bench 2.9.3 | File | Platform | Checksum | |--------|----------|----------| …View on GitHub ↗