open-ralph-wiggum

# 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) ```bash npm install -g @th0rgal/ralph-wiggum ``` ### Bun ```bash bun add -g @th0rgal/ralph-wiggum ``` ### From source (Linux/macOS) ```bash git clone https://github.com/Th0rgal/open-ralph-wiggum cd open-ralph-wiggum ./install.sh ``` ### From source (Windows) ```powershell 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) ```bash ralph "Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete." \ --max-iterations 5 ``` ### Claude Code ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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: ```bash opencode models ``` Configure a default in `~/.config/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-5" } ``` **Claude Code** — check version and available models: ```bash claude --version ``` Common models: `claude-opus-4`, `claude-sonnet-4`, `claude-haiku-4` **Codex** — check version and available models: ```bash codex --version ``` Common models: `gpt-5-codex`, `o4-mini` **Copilot CLI** — uses GitHub Copilot subscription; verify auth: ```bash 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: ```bash qwen --version # If not installed: npm install -g @qwen-code/qwen-code ``` ### Quick environment check (Linux/macOS) ```bash 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:** ```bash ralph "Your task. Output <promise>COMPLETE</promise> when done." --max-iterations 20 ``` **Claude Code:** ```bash ralph "Your task. Output <promise>COMPLETE</promise> when done." \ --agent claude-code --model claude-sonnet-4 --max-iterations 20 ``` **Codex:** ```bash ralph "Your task. Output <promise>COMPLETE</promise> when done." \ --agent codex --model gpt-5-codex --max-iterations 20 ``` **Copilot CLI:** ```bash 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:** ```bash ralph "Your task. Output <promise>COMPLETE</promise> when done." \ --agent cursor-agent --max-iterations 20 ``` **Qwen Code:** ```bash 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: ```bash ralph --status ``` 4. Inject hints mid-loop from the second terminal: ```bash 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:** ```vim :split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --max-iterations 20 ``` **Claude Code:** ```vim :split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent claude-code --model claude-sonnet-4 --max-iterations 20 ``` **Codex:** ```vim :split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent codex --model gpt-5-codex --max-iterations 20 ``` **Copilot CLI:** ```vim :split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent copilot --max-iterations 20 ``` **Cursor Agent:** ```vim :split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent cursor-agent --max-iterations 20 ``` **Qwen Code:** ```vim :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:** ```bash ralph --prompt-file ./task.md --max-iterations 30 ``` **Claude Code:** ```bash ralph --prompt-file ./task.md --agent claude-code --model claude-sonnet-4 --max-iterations 30 ``` **Codex:** ```bash ralph --prompt-file ./task.md --agent codex --model gpt-5-codex --max-iterations 30 ``` **Copilot CLI:** ```bash ralph --prompt-file ./task.md --agent copilot --max-iterations 30 ``` **Cursor Agent:** ```bash ralph --prompt-file ./task.md --agent cursor-agent --max-iterations 30 ``` **Qwen Code:** ```bash ralph --prompt-file ./task.md --agent qwen-code --max-iterations 30 ``` --- ## Tasks Mode Break large projects into a tracked task list: ```bash # 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)