open-ralph-wiggum

name

open-ralph-wiggum

description

Use this skill whenever a user wants to run, install, configure, or understand open-ralph-wiggum (ralph). This skill can be used by any AI assistant or IDE agent (GitHub Copilot, Claude Code, Cursor, Windsurf, etc.). Triggers on: "ralph", "ralph wiggum", "agentic loop", "iterative AI loop", "autonomous coding loop", "how to install ralph", "how to use ralph with Claude Code / Codex / Copilot / Cursor Agent / Qwen Code / OpenCode", "ralph --agent", "ralph --tasks", "ralph --status", "--max-iterations", "--rotation", "how do I run ralph in VS Code / Cursor / JetBrains / Neovim", or any question about looping an AI coding agent until a task is done. Even if the user doesn't say "ralph" explicitly — if they want to run an AI agent in a loop until a promise tag appears in its output, use this skill.

Open Ralph Wiggum

Open Ralph Wiggum (ralph) wraps any supported AI coding agent in an autonomous loop: it sends the same prompt on every iteration, and the agent self-corrects by observing the state of the repo. The loop ends when the agent outputs a configurable completion promise (e.g. <promise>COMPLETE</promise>).

Supported agents: Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, Qwen Code, OpenCode (default).

---

Installation

Prerequisites

• Bun runtime
• At least one of these AI coding agent CLIs installed and authenticated:
  • claude — Claude Code
  • codex — OpenAI Codex CLI
  • copilot — GitHub Copilot CLI
  • cursor-agent — Cursor Agent CLI
  • qwen — Qwen Code CLI
  • opencode — OpenCode

npm (recommended)

npm install -g @th0rgal/ralph-wiggum

Bun

bun add -g @th0rgal/ralph-wiggum

From source (Linux/macOS)

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

From source (Windows)

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

After installation, the ralph command is available globally.

---

Quick Start

Always include a completion promise in your prompt — this is how ralph knows the task is done.

OpenCode (default)

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

Claude Code

ralph "Build a REST API with tests. Output <promise>COMPLETE</promise> when all tests pass." \
  --agent claude-code --model claude-sonnet-4 --max-iterations 20

Codex

ralph "Refactor auth module, ensure all tests pass. Output <promise>COMPLETE</promise> when done." \
  --agent codex --model gpt-5-codex --max-iterations 20

Copilot CLI

ralph "Implement login feature. Output <promise>COMPLETE</promise> when done." \
  --agent copilot --max-iterations 15

Requires GitHub Copilot subscription and prior authentication (copilot /login or GH_TOKEN env var).

Cursor Agent

ralph "Add integration tests for the API. Output <promise>COMPLETE</promise> when done." \
  --agent cursor-agent --max-iterations 15

Requires Cursor Agent CLI installed via curl https://cursor.com/install -fsSL | bash. For headless environments, set CURSOR_API_KEY.

Qwen Code

ralph "Refactor the database layer. Output <promise>COMPLETE</promise> when done." \
  --agent qwen-code --max-iterations 15

Requires Qwen Code installed via npm install -g @qwen-code/qwen-code.

---

Checking Available Agents and Models

Before running ralph, verify which agents are installed and what models they support.

Check available models per agent

OpenCode — lists all configured providers and models:

opencode models

Configure a default in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

Claude Code — check version and available models:

claude --version

Common models: claude-opus-4, claude-sonnet-4, claude-haiku-4

Codex — check version and available models:

codex --version

Common models: gpt-5-codex, o4-mini

Copilot CLI — uses GitHub Copilot subscription; verify auth:

copilot /status   # shows login state and available models
# If not logged in:
copilot /login
# Or set env var:
export GH_TOKEN=your_token

Qwen Code — check version and install if needed:

qwen --version
# If not installed:
npm install -g @qwen-code/qwen-code

Quick environment check (Linux/macOS)

for bin in opencode claude codex copilot cursor-agent qwen; do
  if command -v "$bin" &>/dev/null; then echo "✅ $bin: $(which $bin)"; else echo "❌ $bin: not found"; fi
done && \
  [[ -n "$GH_TOKEN" ]] && echo "✅ GH_TOKEN set (Copilot CLI)" || echo "ℹ️  GH_TOKEN not set (needed only for Copilot CLI)"

---

Agent Selection

Agent	--agent flag	Binary	Env override
OpenCode (default)	--agent opencode	opencode	RALPH_OPENCODE_BINARY
Claude Code	--agent claude-code	claude	RALPH_CLAUDE_BINARY
OpenAI Codex	--agent codex	codex	RALPH_CODEX_BINARY
Copilot CLI	--agent copilot	copilot	RALPH_COPILOT_BINARY
Cursor Agent	--agent cursor-agent	cursor-agent	RALPH_CURSOR_AGENT_BINARY
Qwen Code	--agent qwen-code	qwen	RALPH_QWEN_CODE_BINARY

Use environment variables to point to a custom binary path if the CLI is not on $PATH.

---

Key Options

--agent AGENT            Agent to use (opencode|claude-code|codex|copilot|cursor-agent|qwen-code)
--model MODEL            Model name (agent-specific, e.g. claude-sonnet-4, gpt-5-codex)
--max-iterations N       Stop after N iterations (always set this as a safety net)
--min-iterations N       Require at least N iterations before allowing completion (default: 1)
--completion-promise T   Text that signals task completion (default: COMPLETE)
--abort-promise TEXT     Text that signals early abort/precondition failure
--tasks / -t             Enable Tasks Mode (structured multi-task tracking)
--prompt-file / -f PATH  Read prompt from a file instead of CLI argument
--prompt-template PATH   Use a custom Mustache-style prompt template
--no-commit              Skip git auto-commit after each iteration
--no-plugins             Disable OpenCode plugins (useful to avoid plugin conflicts)
--allow-all              Auto-approve all tool permission prompts (default: on)
--status                 Show live loop status from another terminal
--add-context TEXT       Inject a hint for the next iteration without stopping the loop
--clear-context          Remove pending context
--list-tasks             List current tasks (Tasks Mode)
--add-task TEXT          Add a task (Tasks Mode)
--remove-task N          Remove task by index (Tasks Mode)
--rotation LIST          Cycle through agent/model pairs each iteration (comma-separated agent:model)
--verbose-tools          Print every tool line (disable compact tool summary)
--last-activity-timeout DURATION  Kill and restart iteration after inactivity (e.g., 30m, 1h)
--no-questions           Disable interactive question handling (agent will loop on questions)
--task-promise T        Text that signals task completion (default: READY_FOR_NEXT_TASK)
--no-stream             Buffer agent output and print at the end
--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
--questions             Enable interactive question handling (default: enabled)

---

IDE Integration

Ralph is a terminal CLI tool that runs inside any IDE's integrated terminal.

VS Code / Cursor

1. Open the integrated terminal (Ctrl+`` or View → Terminal).

2. Run ralph from your project root using the agent of your choice:

   OpenCode:

   ralph "Your task. Output <promise>COMPLETE</promise> when done." --max-iterations 20
   

   Claude Code:

   ralph "Your task. Output <promise>COMPLETE</promise> when done." \
     --agent claude-code --model claude-sonnet-4 --max-iterations 20
   

   Codex:

   ralph "Your task. Output <promise>COMPLETE</promise> when done." \
     --agent codex --model gpt-5-codex --max-iterations 20
   

   Copilot CLI:

   ralph "Your task. Output <promise>COMPLETE</promise> when done." \
     --agent copilot --max-iterations 20
   

   Note: --agent copilot uses the standalone Copilot CLI, not the VS Code extension. Both can be active at the same time.

   Cursor Agent:

   ralph "Your task. Output <promise>COMPLETE</promise> when done." \
     --agent cursor-agent --max-iterations 20
   

   Qwen Code:

   ralph "Your task. Output <promise>COMPLETE</promise> when done." \
     --agent qwen-code --max-iterations 20
   

3. Open a second terminal tab to monitor while the loop runs:

   ralph --status
   

4. Inject hints mid-loop from the second terminal:

   ralph --add-context "Focus on fixing the auth module first"
   

JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.)

1. Open the integrated terminal (Alt+F12).
2. Run the same agent-specific commands as above.
3. Use Run Configurations → Shell Script to save common ralph invocations per agent as reusable run configurations.

Neovim / Vim

Run ralph in a split terminal. Examples per agent:

OpenCode:

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --max-iterations 20

Claude Code:

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent claude-code --model claude-sonnet-4 --max-iterations 20

Codex:

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent codex --model gpt-5-codex --max-iterations 20

Copilot CLI:

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent copilot --max-iterations 20

Cursor Agent:

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent cursor-agent --max-iterations 20

Qwen Code:

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent qwen-code --max-iterations 20

Or use a plugin like toggleterm.nvim for a persistent terminal.

Any IDE — Prompt File Workflow

For complex prompts, save them as a file to avoid shell escaping issues and make prompts versionable.

OpenCode:

ralph --prompt-file ./task.md --max-iterations 30

Claude Code:

ralph --prompt-file ./task.md --agent claude-code --model claude-sonnet-4 --max-iterations 30

Codex:

ralph --prompt-file ./task.md --agent codex --model gpt-5-codex --max-iterations 30

Copilot CLI:

ralph --prompt-file ./task.md --agent copilot --max-iterations 30

Cursor Agent:

ralph --prompt-file ./task.md --agent cursor-agent --max-iterations 30

Qwen Code:

ralph --prompt-file ./task.md --agent qwen-code --max-iterations 30

---

Tasks Mode

Break large projects into a tracked task list:

# Start a loop in Tasks Mode
ralph "Build a full-stack app" --tasks --max-iterations 50

# Manage tasks while the loop is idle (or before starting)