/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](https://bun.sh) runtime
• At least one of these AI coding agent CLIs installed and authenticated:
• `claude` — [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
• `codex` — [OpenAI Codex CLI](https://github.com/openai/codex)
• `copilot` — [GitHub Copilot CLI](https://github.com/github/copilot-cli)
• `cursor-agent` — [Cursor Agent CLI](https://cursor.com/cli/)
• `qwen` — [Qwen Code CLI](https://github.com/QwenLM/qwen-code)
• `opencode` — [OpenCode](https://opencode.ai)

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 variabl