Open Ralph Wiggum Documentation

The Ralph Wiggum technique is an autonomous agentic loop where an AI coding agent receives the same prompt repeatedly until a task is completed.

Instead of the AI

while true; do
  claude-code "Build feature X. Output <promise>DONE</promise> when complete."  # or codex, copilot, cursor-agent, qwen, opencode
done

The ralph-omx integration is a lightweight layer that does not modify the core Open Ralph runtime. It achieves OMX/Codex execution through three components:

1. ralph-omx: A convenience launcher that starts the standard Open Ralph entrypoint with the --agent codex flag and the model specified by $RALPH_OMX_MODEL.
2. agents.example.json: An Open Ralph configuration that overrides the built-in codex agent command.
3. omx-codex-exec-for-ralph: An adapter that intercepts Open Ralph's Codex-style command line arguments and routes them through omx exec.

This architecture allows you to keep Open Ralph's loop mechanics while using OMX/Codex as the execution backend.

When using --tasks mode, you can use --task-min-iterations N to ensure every top-level todo in .ralph/ralph-tasks.md receives at least N implementation and verification iterations.

This is distinct from the global --min-iterations flag. If a task is marked as completed [x] before reaching its minimum count, Ralph will continue selecting that task for additional verification rounds.

ralph-omx \
  --tasks \
  --task-promise READY_FOR_NEXT_TASK \
  --task-min-iterations 3 \
  --codex-goal \
  --codex-backend omx \
  --min-iterations 3 \
  --max-iterations 20 \
  --completion-promise FEATURE_VERIFIED \
  --prompt-file .omx/prompts/feature-ralph-omx.md

Ralph operates in an iterative loop to achieve task completion:

1. Prompting: Ralph sends your prompt to the selected AI Agent.
2. Execution: The agent works on the task and modifies files in your Git repository.
3. Verification: Ralph checks the agent's output for the specified completion promise (e.g., <promise>COMPLETE</promise>).
4. Iteration: If the promise is not found, Ralph repeats the loop with the same prompt, allowing the agent to see its previous work in the files.
5. Termination: The loop continues until the promise is detected or the --max-iterations limit is reached.

The --rotation flag allows you to cycle through different agent/model combinations across iterations. This is useful for leveraging the strengths of multiple models. When --rotation is used, the individual --agent and --model flags are ignored. The list cycles back to the first entry after the last one is used.

Supported agents: opencode, claude-code, codex, copilot, cursor-agent, and qwen-code.

Format: agent:model entries separated by commas.

# Alternate between OpenCode and Claude Code
ralph "Build a REST API" \
  --rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4" \
  --max-iterations 10

# Three-way rotation
ralph "Refactor the auth module" \
  --rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4,codex:gpt-5-codex" \
  --max-iterations 15

Open Ralph Wiggum (ralph) wraps an AI coding agent in an autonomous loop. In each iteration, ralph sends the same prompt to the agent. The agent observes the repository state and self-corrects.

Crucial Requirement: You must include a completion promise in your prompt. This is a specific string that tells ralph the task is finished. By default, ralph looks for the text COMPLETE. If the agent outputs this string, the loop terminates. If the agent fails to output the promise, ralph will continue iterating until --max-iterations is reached.

To use the copilot agent, you must have a GitHub Copilot subscription and be authenticated.

Setup:

1. Install: npm install -g @github/copilot or brew install copilot-cli.
2. Authenticate: copilot /login or set GH_TOKEN / GITHUB_TOKEN environment variables.

Usage Notes:

• Default model is claude-sonnet-4.5. Use --model to override.
• --allow-all (default) maps to --allow-all + --no-ask-user in the underlying CLI.
• --no-plugins has no effect.

# Basic usage
ralph "Refactor the auth module and add tests" \
  --agent copilot --max-iterations 15

# With a specific model
ralph "Build a REST API" \
  --agent copilot --model claude-opus-4.6 --max-iterations 10

After installation, you can run ralph-omx by providing environment variables for the model and reasoning level, along with iteration limits and a completion promise.

Note that Open Ralph maintains control over iteration limits, promises, task handling, and session state, while OMX handles the Codex execution command for each iteration.

cd /path/to/open-ralph-wiggum
bash contrib/omx/install.sh
RALPH_OMX_MODEL=gpt-5.5 \
OMX_RALPH_REASONING=high \
OMX_RALPH_SANDBOX=danger-full-access \
ralph-omx \
  --min-iterations 1 \
  --max-iterations 20 \
  --completion-promise YOUR_COMPLETION_PROMISE \
  --prompt-file .omx/prompts/your-task.md

Cursor Agent is Cursor's headless CLI agent. It works with any model available through your Cursor subscription.

Setup:

curl https://cursor.com/install -fsSL | bash

Usage Notes:

• --allow-all maps to --force in Cursor Agent CLI.
• For headless environments (no Cursor window), set the CURSOR_API_KEY environment variable.
• The binary is cursor-agent. You can override the path using the RALPH_CURSOR_AGENT_BINARY environment variable.

ralph "Add integration tests for the API" \
  --agent cursor-agent \
  --max-iterations 10

# With a specific model
ralph "Refactor the database layer" \
  --agent cursor-agent \
  --model sonnet-4 \
  --max-iterations 15