open-ralph-wiggum

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       St