by Th0rgal
Type `ralph "prompt"` to start open code in a ralph loop. Also supports a prompt file & status check. Open Code, Claude Code, Codex, Copilot
# Add to your Claude Code skills
git clone https://github.com/Th0rgal/open-ralph-wiggumGuides for using ai agents skills like open-ralph-wiggum.
Last scanned: 4/27/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-04-27T06:28:01.997Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
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
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.
Switch between AI coding agents without changing your workflow:
--agent claude-code) — Anthropic's powerful coding agent--agent codex) — OpenAI's code-specialized model--agent copilot) — GitHub's agentic coding tool--agent cursor-agent) — Cursor's headless AI coding agent--agent qwen-code) — Alibaba's Qwen Code headless CLI agent--agent opencode) — Open-source default option--tasks mode--status from another terminal--add-context without stopping| 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 |
Prerequisites:
npm install -g @th0rgal/ralph-wiggum
bun add -g @th0rgal/ralph-wiggum
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.
# 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
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.
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