Ralph Orchestrator CLI
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
- 3,203 ★ on the repository
- Last commit
- MIT
Extended access
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
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/ralph-orchestratorDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- 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
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.
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.
Discussion
No questions or reviews yet.
Related
CLI toolsThe ralph command repeats one prompt for Claude Code, Codex, Cursor Agent or OpenCode until a completion tag appears in the reply
A Ralph loop for long tasks: an agent in a Docker sandbox works through a PRD task list, checks each task with tests and commits until the list is done
A terminal dashboard that drives Claude Code, Codex and five more agents through a task list in a loop until the list is done
Autonomous plan execution task by task: each task in a fresh Claude Code or Codex session, then a multi-pass review. Written in Go
One agent launches others in the background: Claude Code, Codex, Copilot CLI, Grok Build and Pi, with a model chosen per stage.
One runtime for Claude Code, Codex, OpenCode and more: a run counts as done only when checks the agent did not write pass
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Ralph Orchestrator (this card) | no | not required | 3,203 | |
| Helmor | no | 1,306 | a desktop app that runs Claude Code | |
| Gauntlet Loop | no | 1,237 | a skill that turns a goal into a ready prompt | |
| Open Ralph Wiggum | no | 1,906 | the ralph command repeats one prompt for Claude Code |
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.