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 Open the integrated terminal ( Ctrl+`` or View → Terminal ). 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 Open a second terminal tab to monitor while the loop runs: ralph --status Inject hints mid-loop from the second terminal: ralph --add-context "Focus on fixing the auth module first" JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.) Open the integrated terminal ( Alt+F12 ). Run the same agent-specific commands as above. 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)