open-ralph-wiggum

Works with Claude Code, OpenAI Codex, Copilot CLI, Cursor Agent, Qwen Code, and OpenCode — switch agents with --agent. Based on the Ralph Wiggum technique by Geoffrey Huntley

Supported Agents • What is Ralph? • Installation • Quick Start • Commands

Tired of agents breaking your local environment? 🏝️ sandboxed.sh gives each task an isolated Linux workspace. Self-hosted. Git-backed.

💬 Join the community: relens.ai/community

Supported Agents

Open Ralph Wiggum works with multiple AI coding agents. Switch between them using the --agent flag:

# Use Claude Code
ralph "Build a REST API" --agent claude-code --max-iterations 10

# Use OpenAI Codex
ralph "Create a CLI tool" --agent codex --max-iterations 10

# Use Copilot CLI
ralph "Refactor the auth module" --agent copilot --max-iterations 10

# Use Cursor Agent
ralph "Add unit tests" --agent cursor-agent --max-iterations 10

# Use Qwen Code
ralph "Add unit tests" --agent qwen-code --max-iterations 10

# Use OpenCode (default)
ralph "Fix the failing tests" --max-iterations 10

What is Open Ralph Wiggum?

Open Ralph Wiggum implements the Ralph Wiggum technique — an autonomous agentic loop where an AI coding agent (Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code, or OpenCode) receives the same prompt repeatedly until it completes a task. Each iteration, the AI sees its previous work in files and git history, enabling self-correction and incremental progress.

This is a CLI tool that wraps any supported AI coding agent in a persistent development loop. No plugins required — just install and run.

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

Why this works: The AI doesn't talk to itself between iterations. It sees the same prompt each time, but the codebase has changed from previous iterations. This creates a powerful feedback loop where the agent iteratively improves its work until all tests pass.

Multi-Agent Flexibility

Switch between AI coding agents without changing your workflow:

• Claude Code (--agent claude-code) — Anthropic's powerful coding agent
• Codex (--agent codex) — OpenAI's code-specialized model
• Copilot CLI (--agent copilot) — GitHub's agentic coding tool
• Cursor Agent (--agent cursor-agent) — Cursor's headless AI coding agent
• Qwen Code (--agent qwen-code) — Alibaba's Qwen Code headless CLI agent
• OpenCode (--agent opencode) — Open-source default option

Key Features

• Multi-Agent Support — Use Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code, or OpenCode with the same workflow
• Self-Correcting Loops — Agent sees its previous work and fixes its own mistakes
• Autonomous Execution — Set it running and come back to finished code
• Task Tracking — Built-in task management with --tasks mode
• Live Monitoring — Check progress with --status from another terminal
• Mid-Loop Hints — Inject guidance with --add-context without stopping

Why Use an Agentic Loop?

Installation

Prerequisites:

• Bun runtime
• At least one AI coding agent CLI:
  • Claude Code — Anthropic's Claude Code CLI
  • Codex — OpenAI's Codex CLI
  • Copilot CLI — GitHub's Copilot CLI
  • Cursor Agent — Cursor's headless Agent CLI
  • Qwen Code — Alibaba's Qwen Code CLI
  • OpenCode — Open-source AI coding assistant

npm (recommended)

npm install -g @th0rgal/ralph-wiggum

Bun

bun add -g @th0rgal/ralph-wiggum

From source

git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
./install.sh

git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
.\install.ps1

This installs the ralph CLI command globally.

Quick Start

# Simple task with iteration limit
ralph "Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete." \
  --max-iterations 5

# Build something real
ralph "Build a REST API for todos with CRUD operations and tests. \
  Run tests after each change. Output <promise>COMPLETE</promise> when all tests pass." \
  --max-iterations 20

# Use Claude Code instead of OpenCode
ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  --agent claude-code --model claude-sonnet-4 --max-iterations 5

# Use Codex instead of OpenCode
ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  --agent codex --model gpt-5-codex --max-iterations 5

# Use Codex goal mode through OMX: Ralph owns cross-iteration retries, /goal owns one iteration
RALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx \
ralph "Complete the task described in .harness/goal.md. Output <promise>COMPLETE</promise> when everything passes." \
  --agent codex --max-iterations 5

# Use Copilot CLI
ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  --agent copilot --max-iterations 5

# Use Qwen Code
ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  --agent qwen-code --max-iterations 5

# Complex project with Tasks Mode
ralph "Build a full-stack web application with user auth and database" \
  --tasks --max-iterations 50

Environment Variables

Configure agent binaries with these environment variables:

Note for Windows users: Ralph automatically resolves .cmd extensions for npm-installed CLIs. If you encounter "command not found" errors, you can use these environment variables to specify the full path to the executable.

Commands

Running a Loop

ralph "<prompt>" [options]

Options:
  --agent AGENT            AI agent to use: opencode (default), claude-code, codex, copilot, cursor-agent, qwen-code
  --codex-goal             Run Codex iterations in goal mode; final Codex/OMX prompt starts with /goal
  --codex-backend BACKEND  Backend for --codex-goal: codex or omx (default: detect)
  --codex-goal-native      Force a native /goal attempt even when backend support is unconfirmed
  --min-iterations N       Minimum iterations before completion allowed (default: 1)
  --max-iterations N       Stop after N iterations (default: unlimited)
  --completion-promise T   Text that signals completion (default: COMPLETE)
  --abort-promise TEXT     Phrase that signals early abort (e.g., precondition failed)
  --tasks, -t              Enable Tasks Mode for structured task tracking
  --task-min-iterations N   Require each top-level task to receive N Ralph iterations before completion (default: 1)
  --task-promise T         Text that signals task completion (default: READY_FOR_NEXT_TASK)
  --model MODEL            Model to use (agent-specific)
  --rotation LIST          Agent/model rotation for each iteration (comma-separated)
  --prompt-file, --file, -f  Read prompt content from a file
  --prompt-template PATH   Use custom prompt template (see Custom Prompts)
  --no-stream              Buffer agent output and print at the end
  --verbose-tools          Print every tool line (disable compact tool summary)
  --questions              Enable interactive question handling (default: enabled)
  --no-questions           Disable interactive question handling (agent will loop on questions)
  --no-plugins             Disable non-auth OpenCode plugins for this run (opencode only)
  --no-commit              Don't auto-commit after iterations
  --allow-all              Auto-approve all tool permissions (default: on)
  --no-allow-all           Require interactive permission prompts
  --config PATH            Use custom agent config file
  --init-config [PATH]     Write default agent config to PATH and exit
  --help                   Show help

Codex / OMX Goal Mode

--codex-goal is an opt-in mode for --agent codex. Open Ralph still owns the outer loop: max iterations, process restarts, promise detection, .ralph/ralph-history.json, git/file-system state, and optional auto-commits. Inside each Ralph iteration, the Codex backend receives a final prompt whose first token is /goal, so Codex goal mode can own the single-session push for that iteration.