Open Ralph Wiggum CLI
The ralph command repeats one prompt for Claude Code, Codex, Cursor Agent or OpenCode until a completion tag appears in the reply
- 1,906 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Runs the agent CLI with no iteration limit and, by default, no confirmations, so the agent can change and delete project files and run commands
- Commits to git after every iteration and writes state to `.ralph/`, while repeated requests spend the agent's paid plan
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/open-ralph-wiggumDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Runs the agent CLI with no iteration limit and, by default, no confirmations, so the agent can change and delete project files and run commands
- Commits to git after every iteration and writes state to `.ralph/`, while repeated requests spend the agent's paid plan
This is third-party code. Review the repository files before installing.
What it does
Open Ralph Wiggum is a command-line wrapper on Bun and TypeScript that runs an AI coding agent in a loop. You give it `ralph "prompt" --max-iterations 20` and the program passes the same text to the agent again and again. The agent remembers nothing between iterations: it sees only the state of the files and the git history, so it fixes its own mistakes from test results. The loop ends when the output contains a tag like `<promise>COMPLETE</promise>`, or at the iteration limit. The `--agent` flag picks the agent: `claude-code`, `codex`, `copilot`, `cursor-agent`, `qwen-code`, and `opencode` by default. The agent CLIs themselves must be installed and signed in beforehand. The `--tasks` mode splits a big job into tasks in the `.ralph/ralph-tasks.md` file and hands the agent one per iteration. The `--rotation` parameter alternates agents and models across iterations. With `--prompt-template` you can supply your own prompt template with variables such as `{{iteration}}` and `{{tasks}}`. You can follow progress from another terminal: `ralph --status` shows the iteration number, elapsed time, recent tool calls and signs that the agent is stuck. `ralph --add-context` queues a hint for the next iteration. State lives in the project's `.ralph/` folder. For Codex there is a `--codex-goal` mode where each iteration starts with `/goal` while Ralph keeps the outer loop. The skill in `skills/` explains these commands to an assistant.
Who it is for. For developers who want to carry a task with a verifiable result, such as green tests, to the end without restarting the agent by hand, and for anyone comparing Claude Code, Codex and OpenCode on one prompt.
Good fit when
- You need every test to pass and the task allows many small attempts in a row without you
- A new project with clear completion criteria runs overnight and you review the commits in the morning
- You want to run one prompt through Claude Code and Codex and compare results with the `--agent` flag
- A large piece of work from a PRD has to go through tasks, one per iteration, logged in `.ralph/ralph-tasks.md`
Not a fit when
- The result cannot be checked automatically: a loop without tests or a linter repeats the prompt blindly and burns paid model requests
- The task needs a human decision or a one-off action, such as debugging on a production server
- You have no Bun: the program runs only on it, and you also need at least one installed agent CLI that is signed in
- You want a ready system with review and quality rules, in which case Ralph Orchestrator fits better: it blocks incomplete work with tests and a linter
Example request
Run ralph with Claude Code for twenty iterations: add a CSV report export and finish when all tests passLimitations
- The iteration count is unlimited by default. The author advises always setting `--max-iterations`, otherwise the loop does not stop until the reply holds the completion tag.
- Agent permissions are approved automatically by default (`--allow-all` is on), and a git commit follows every iteration. Use `--no-allow-all` for confirmations and `--no-commit` to turn commits off.
- The program does not replace the agent: you need Bun, an installed and authorized CLI of at least one agent, and a model configured in it. Request costs follow that agent's plan.
- For OpenCode without a default model the `ProviderModelNotFoundError` error appears; set the model in `opencode.json` or with the `--model` flag.
- The author calls the method the Ralph Wiggum technique after Geoffrey Huntley and advises against it where the success criterion is vague. License MIT.
How to disable. Run `npm uninstall -g @th0rgal/ralph-wiggum`, or `uninstall.sh` from the cloned repository, `uninstall.ps1` on Windows. A running loop stops with Ctrl+C. State files live in the project's `.ralph/` folder, which you can delete by hand.
FAQ
How does Ralph know the task is done?
It looks in the agent's output for the tag from the `--completion-promise` flag, `COMPLETE` by default, written as `<promise>COMPLETE</promise>`. The tag is ignored until the `--min-iterations` count has passed. A phrase from `--abort-promise` stops the loop early.
Can Ralph switch agents in the middle of a loop?
Yes, through `--rotation`: a comma-separated list of agents and models decides who runs each next iteration. Without it the whole loop uses the one agent from `--agent`. Variables such as `RALPH_CLAUDE_BINARY` and `RALPH_CODEX_BINARY` override the paths to agent binaries.
How do I steer the agent without stopping the loop?
In another terminal run `ralph --add-context "The bug is in utils/parser.ts, line 42"`. The hint goes into the next iteration's prompt and is used once. `ralph --clear-context` empties the queue.
What does the `--tasks` mode do?
It keeps a task list in `.ralph/ralph-tasks.md` with `[ ]`, `[/]` and `[x]` marks and hands the agent one at a time. A task closes with the `READY_FOR_NEXT_TASK` tag. `--list-tasks`, `--add-task` and `--remove-task` edit the list, and `--task-min-iterations` requires a minimum of attempts per task.
How does the `--codex-goal` mode work?
The `--codex-goal` flag hands each iteration to Codex with a prompt starting with `/goal`, while restarts, limits and tag detection stay with Ralph. Every step is recorded in `.ralph/codex-goal-ledger.jsonl`. For OMX the mode is switched on by `RALPH_CODEX_GOAL=1` and `RALPH_CODEX_BACKEND=omx`.
Which prompt suits a loop best?
One with verifiable conditions: tests, a linter, types. The author recommends a short PRD with a goal, scope, numbered requirements and a completion tag. For big projects they advise a `features.json` file with a `passes` field so the agent does not rewrite the success criteria.
Discussion
No questions or reviews yet.
Related
CLI toolsA 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
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
Autonomous plan execution task by task: each task in a fresh Claude Code or Codex session, then a multi-pass review. Written in Go
OpenRig
openrig
A CLI for persistent teams of Claude Code and Codex agents: the team is described in YAML and started with one command, with roles and monitoring
The author's personal Claude Code toolbox: meta-prompt and todo commands, skills to create skills, hooks and MCP servers, auditors and a Ralph loop
oah links 80-plus skills, five roles and /commit, /review, /test-tdd commands into Claude Code, Cursor, Codex and other agent folders
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Open Ralph Wiggum (this entry) | no | 1,906 | ||
| Ralphy | no | 2,981 | runs agents in a loop over a task list or PRD until everything is done | |
| Ralph Orchestrator | no | not required | 3,190 | an orchestrator that blocks incomplete work with tests and a linter |
| Ralph | no | 22,083 | a Bash loop with clean context for Claude Code or Amp, plus two PRD skills |
README in short
The repository holds the main TypeScript loop in a single file, an npm wrapper, install and uninstall scripts for Linux, macOS and Windows, a completion module, tests with agent stubs, a skill for the assistant and an OMX integration in the `contrib` folder. The front page opens with a table of supported agents, followed by the principle of the method, installation, commands, tips on writing prompts and a diagram of the loop.