Ralph Orchestrator
A CLI orchestrator that loops Claude Code, Codex, Gemini CLI and other agents until a task is done and blocks incomplete work with tests and lint
Medium risk
We rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.
Why this level
- Runs the agent through several iterations autonomously without a per-step confirmation
- The agent backend gets access to the project code and runs commands as part of the loop
Install
Manual install
npm install -g @ralph-orchestrator/ralph-cliRecommended install method.
This is third-party code. Review the repository files before installing.
What it does
Ralph Orchestrator puts a chosen agent backend into a loop: the agent works on the task, the orchestrator checks the result through gates like tests, lint and type checks, and if a gate fails it sends the agent back for another iteration until it reports completion or the iteration limit is hit. Work is organized through a hat system — specialized roles like planning, implementation, review and debugging that hand off to each other on events. The tool has a planning mode with an interactive session before code is written, a web dashboard for watching loops, and a Telegram bot for asking the agent questions or stepping in mid-run.
Who it is for. For developers who want to run Claude Code, Codex or another CLI agent in an autonomous loop on a task and get a result that passes tests and lint without manually restarting it.
Good fit when
- A task needs to be driven to completion through a checked loop rather than a single agent request
- You want a web dashboard or Telegram bot to watch the agent's autonomous work and step in occasionally
- The project needs specialized roles such as separate planning and separate code review passes
Not a fit when
- The task is simple and one-off, where a plain agent request is faster
- There are no tests, lint or another completion criterion the gates could check the result against
- Rust and Node.js are not installed to build the API and web dashboard
Example request
Run Ralph on the claude backend and loop the task of adding JWT authentication until the tests passLimitations
The web dashboard is marked alpha and requires the Rust toolchain and Node.js 18+. The loop stops on a LOOP_COMPLETE signal from the agent or the iteration limit; there is no guarantee of a correct result, gates only check what you configure them to. The Telegram bot needs its own bot token.
How to disable. Remove the global package: npm uninstall -g @ralph-orchestrator/ralph-cli, or cargo uninstall ralph-cli if it was installed via Cargo.
Security check
- Runs the agent through several iterations autonomously without a per-step confirmation
- The agent backend gets access to the project code and runs commands as part of the loop
README in short
The README describes Ralph Orchestrator as an implementation of the Ralph Wiggum technique: keep an agent looping until a task is done, using a hat system for planning, implementation, debugging and review. It installs via npm, a GitHub Releases installer or Cargo. There is a ralph plan mode before code is written, an MCP server for MCP clients through ralph mcp serve, a web dashboard for watching loops, and a Telegram bot called RObot for agent questions and manual human intervention. It supports backends including Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Pi, Roo and OMP. MIT licensed.
FAQ
How does Ralph differ from a one-off agent request?
Ralph does not stop after a single agent reply; it runs the result through gates like tests and lint and repeats the loop until the task passes or the iteration limit is reached.
Can it be used without the web dashboard?
Yes, the dashboard is a separate alpha feature for observation. The base ralph run loop works from the command line without Rust and Node.js for the API.
Related
Open-source personal AI assistant on your own machine: answers in Telegram, Slack, Discord and WhatsApp, extended with skills and plugins
A self-improving agent from Nous Research with a TUI, messaging gateway, cron jobs and skills it writes itself
An open source coding agent for the terminal and desktop with build and plan modes
Open prompt library with a Claude Code plugin, MCP server and CLI: search, fetch and improve prompts and skills from an agent