Supported Agents

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

| Agent | Flag | Description | |-------|------|-------------| | Claude Code | --agent claude-code | Anthropic's Claude Code CLI for autonomous coding | | Codex | --agent codex | OpenAI's Codex CLI for AI-powered development | | Copilot CLI | --agent copilot | GitHub Copilot CLI for agentic coding | | Cursor Agent | --agent cursor-agent | Cursor Agent CLI for headless AI coding | | Qwen Code | --agent qwen-code | Alibaba's Qwen Code CLI for headless AI coding | | OpenCode | --agent opencode | Default agent, open-source AI coding assistant |

# 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?

| Benefit | How it works | |---------|--------------| | Self-Correction | AI sees test failures from previous runs, fixes them | | Persistence | Walk away, come back to completed work | | Iteration | Complex tasks broken into incremental progress | | Automation | No babysitting—loop handles retries | | Observability | Monitor progress with --status, see history and struggle indicators | | Mid-Loop Guidance | Inject hints with --add-context without stopping the 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 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:

| Variable | Description | Default | |----------|-------------|---------| | RALPH_OPENCODE_BINARY | Path to OpenCode CLI | "opencode" | | RALPH_CLAUDE_BINARY | Path to Claude Code CLI | "claude" | | RALPH_CODEX_BINARY | Path to Codex CLI | "codex" | | RALPH_COPILOT_BINARY | Path to Copilot CLI | "copilot" | | RALPH_CURSOR_AGENT_BINARY | Path to Cursor Agent CLI | "cursor-agent" | | RALPH_QWEN_CODE_BINARY | Path to Qwen Code CLI | "qwen" |

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
  --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-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-co

open-ralph-wiggum

Related Skills