ralph-loop — Claude Code command: what it does, how to install
Runs an iterative task loop in Claude Code, returning the original prompt to the agent whenever it attempts to exit.
/plugin install ralph-loop@claude-plugins-officialWhat ralph-loop does
The command invokes ${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh along with your arguments. Whenever the agent tries to end the session, the Ralph loop sends the original prompt back. Claude inspects modified project files and git commits to refine its work on the next iteration.
Execution supports --max-iterations N and --completion-promise TEXT. If a promise text is defined, the agent is strictly prohibited from emitting that string unless the condition is completely true. Fake promises to escape the session are barred by prompt rules. Running without an iteration cap or a valid exit condition keeps the agent looping indefinitely.
What it helps with
- prevent premature session exits on unfinished development tasks
- iterate automatically on failing test suites across multiple runs
- cap automated cycles using the
--max-iterationsflag - verify genuine completion using the
--completion-promisestring
Example prompts for the agent
- /ralph-loop "Fix failing unit tests in auth.test.ts" --completion-promise "ALL TESTS PASS"
- /ralph-loop "Refactor database models to match OpenAPI spec" --max-iterations 5
How to install ralph-loop
1Plugin marketplace
/plugin install ralph-loop@claude-plugins-official2Manually: put the files in place
.claude/commands/ralph-loop.mdCall it with /ralph-loop. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/ralph-loop.mdCall it with /prompts:ralph-loop. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/ralph-loop.prompt.mdManually: put the files in place
.gemini/commands/ralph-loop.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about ralph-loop
How to install ralph-loop in Claude Code?
Run /plugin install ralph-loop@claude-plugins-official in your terminal. You can also install it manually by saving the command markdown file to .claude/commands/ralph-loop.md.
What does ralph-loop do?
It launches a loop script that re-feeds the initial prompt to Claude Code upon exit. The model iterates on the codebase by reviewing previous changes in git and local files.
What is the purpose of --completion-promise?
It defines a specific phrase that the model may print only when the task is genuinely complete. This stops the agent from quitting early when stuck.
Source text
ralph-loop.md · Apache-2.0
---
description: "Start Ralph Loop in current session"
argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
hide-from-slash-command-tool: "true"
---
# Ralph Loop Command
Execute the setup script to initialize the Ralph loop:
```!
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
```
Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.
© Anthropic · Apache-2.0 · anthropics/claude-plugins-official
