{"slug": "open-ralph-wiggum-autonomous-agentic-loop", "title": "Open Ralph Wiggum – Autonomous Agentic Loop", "summary": "Open Ralph Wiggum, a new CLI tool implementing the Ralph Wiggum technique, launches with support for multiple AI coding agents including Claude Code, OpenAI Codex, Copilot CLI, Cursor Agent, Qwen Code, and OpenCode. The tool wraps agents in an autonomous loop that repeatedly prompts the same task until completion, enabling self-correction and incremental progress without manual intervention.", "body_md": "*Works with Claude Code, OpenAI Codex, Copilot CLI, Cursor Agent, Qwen Code, and OpenCode — switch agents with *\n\n`--agent`\n\n.*Based on the*\n\n[Ralph Wiggum technique](https://ghuntley.com/ralph/)by Geoffrey Huntley\n[Supported Agents](#supported-agents) •\n[What is Ralph?](#what-is-open-ralph-wiggum) •\n[Installation](#installation) •\n[Quick Start](#quick-start) •\n[Commands](#commands)\n\n**Tired of agents breaking your local environment?**\n\n🏝️ [sandboxed.sh](https://github.com/Th0rgal/sandboxed.sh) gives each task an isolated Linux workspace. Self-hosted. Git-backed.\n\n💬 **Join the community:** [relens.ai/community](https://relens.ai/community)\n\nOpen Ralph Wiggum works with multiple AI coding agents. Switch between them using the `--agent`\n\nflag:\n\n| Agent | Flag | Description |\n|---|---|---|\nClaude Code |\n`--agent claude-code` |\nAnthropic's Claude Code CLI for autonomous coding |\nCodex |\n`--agent codex` |\nOpenAI's Codex CLI for AI-powered development |\nCopilot CLI |\n`--agent copilot` |\nGitHub Copilot CLI for agentic coding |\nCursor Agent |\n`--agent cursor-agent` |\nCursor Agent CLI for headless AI coding |\nQwen Code |\n`--agent qwen-code` |\nAlibaba's Qwen Code CLI for headless AI coding |\nOpenCode |\n`--agent opencode` |\nDefault agent, open-source AI coding assistant |\n\n```\n# Use Claude Code\nralph \"Build a REST API\" --agent claude-code --max-iterations 10\n\n# Use OpenAI Codex\nralph \"Create a CLI tool\" --agent codex --max-iterations 10\n\n# Use Copilot CLI\nralph \"Refactor the auth module\" --agent copilot --max-iterations 10\n\n# Use Cursor Agent\nralph \"Add unit tests\" --agent cursor-agent --max-iterations 10\n\n# Use Qwen Code\nralph \"Add unit tests\" --agent qwen-code --max-iterations 10\n\n# Use OpenCode (default)\nralph \"Fix the failing tests\" --max-iterations 10\n```\n\nOpen 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.\n\nThis is a **CLI tool** that wraps any supported AI coding agent in a persistent development loop. No plugins required — just install and run.\n\n```\n# The essence of the Ralph loop:\nwhile true; do\n  claude-code \"Build feature X. Output <promise>DONE</promise> when complete.\"  # or codex, copilot, cursor-agent, qwen, opencode\ndone\n```\n\n**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.\n\nSwitch between AI coding agents without changing your workflow:\n\n**Claude Code**(`--agent claude-code`\n\n) — Anthropic's powerful coding agent**Codex**(`--agent codex`\n\n) — OpenAI's code-specialized model**Copilot CLI**(`--agent copilot`\n\n) — GitHub's agentic coding tool**Cursor Agent**(`--agent cursor-agent`\n\n) — Cursor's headless AI coding agent**Qwen Code**(`--agent qwen-code`\n\n) — Alibaba's Qwen Code headless CLI agent**OpenCode**(`--agent opencode`\n\n) — Open-source default option\n\n**Multi-Agent Support**— Use Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code, or OpenCode with the same workflow** Self-Correcting Loops**— Agent sees its previous work and fixes its own mistakes** Autonomous Execution**— Set it running and come back to finished code** Task Tracking**— Built-in task management with`--tasks`\n\nmode**Live Monitoring**— Check progress with`--status`\n\nfrom another terminal**Mid-Loop Hints**— Inject guidance with`--add-context`\n\nwithout stopping\n\n| Benefit | How it works |\n|---|---|\nSelf-Correction |\nAI sees test failures from previous runs, fixes them |\nPersistence |\nWalk away, come back to completed work |\nIteration |\nComplex tasks broken into incremental progress |\nAutomation |\nNo babysitting—loop handles retries |\nObservability |\nMonitor progress with `--status` , see history and struggle indicators |\nMid-Loop Guidance |\nInject hints with `--add-context` without stopping the loop |\n\n**Prerequisites:**\n\n[Bun](https://bun.sh)runtime- At least one AI coding agent CLI:\n[Claude Code](https://docs.anthropic.com/en/docs/claude-code)— Anthropic's Claude Code CLI[Codex](https://github.com/openai/codex)— OpenAI's Codex CLI[Copilot CLI](https://github.com/github/copilot-cli)— GitHub's Copilot CLI[Cursor Agent](https://cursor.com/cli/)— Cursor's headless Agent CLI[Qwen Code](https://github.com/QwenLM/qwen-code)— Alibaba's Qwen Code CLI[OpenCode](https://opencode.ai)— Open-source AI coding assistant\n\n```\nnpm install -g @th0rgal/ralph-wiggum\nbun add -g @th0rgal/ralph-wiggum\ngit clone https://github.com/Th0rgal/open-ralph-wiggum\ncd open-ralph-wiggum\n./install.sh\ngit clone https://github.com/Th0rgal/open-ralph-wiggum\ncd open-ralph-wiggum\n.\\install.ps1\n```\n\nThis installs the `ralph`\n\nCLI command globally.\n\n```\n# Simple task with iteration limit\nralph \"Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete.\" \\\n  --max-iterations 5\n\n# Build something real\nralph \"Build a REST API for todos with CRUD operations and tests. \\\n  Run tests after each change. Output <promise>COMPLETE</promise> when all tests pass.\" \\\n  --max-iterations 20\n\n# Use Claude Code instead of OpenCode\nralph \"Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done.\" \\\n  --agent claude-code --model claude-sonnet-4 --max-iterations 5\n\n# Use Codex instead of OpenCode\nralph \"Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done.\" \\\n  --agent codex --model gpt-5-codex --max-iterations 5\n\n# Use Codex goal mode through OMX: Ralph owns cross-iteration retries, /goal owns one iteration\nRALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx \\\nralph \"Complete the task described in .harness/goal.md. Output <promise>COMPLETE</promise> when everything passes.\" \\\n  --agent codex --max-iterations 5\n\n# Use Copilot CLI\nralph \"Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done.\" \\\n  --agent copilot --max-iterations 5\n\n# Use Qwen Code\nralph \"Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done.\" \\\n  --agent qwen-code --max-iterations 5\n\n# Complex project with Tasks Mode\nralph \"Build a full-stack web application with user auth and database\" \\\n  --tasks --max-iterations 50\n```\n\nConfigure agent binaries with these environment variables:\n\n| Variable | Description | Default |\n|---|---|---|\n`RALPH_OPENCODE_BINARY` |\nPath to OpenCode CLI | `\"opencode\"` |\n`RALPH_CLAUDE_BINARY` |\nPath to Claude Code CLI | `\"claude\"` |\n`RALPH_CODEX_BINARY` |\nPath to Codex CLI | `\"codex\"` |\n`RALPH_CODEX_GOAL` |\nEnable Codex goal mode for `--agent codex` (`1` , `true` , `yes` , `on` ) |\nunset |\n`RALPH_CODEX_BACKEND` |\nGoal-mode backend: `codex` or `omx` |\ndetected from configured codex command |\n`RALPH_CODEX_GOAL_NATIVE` |\nForce native `/goal` attempt even when support is not pre-confirmed |\nunset |\n`OMX_RALPH_OMX_BIN` |\nPath to OMX CLI when `RALPH_CODEX_BACKEND=omx` |\n`\"omx\"` |\n`OMX_RALPH_REASONING` |\n`model_reasoning_effort` passed to `omx exec` in goal mode |\n`\"high\"` |\n`RALPH_COPILOT_BINARY` |\nPath to Copilot CLI | `\"copilot\"` |\n`RALPH_CURSOR_AGENT_BINARY` |\nPath to Cursor Agent CLI | `\"cursor-agent\"` |\n`RALPH_QWEN_CODE_BINARY` |\nPath to Qwen Code CLI | `\"qwen\"` |\n\n**Note for Windows users:** Ralph automatically resolves `.cmd`\n\nextensions 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.\n\n```\nralph \"<prompt>\" [options]\n\nOptions:\n  --agent AGENT            AI agent to use: opencode (default), claude-code, codex, copilot, cursor-agent, qwen-code\n  --codex-goal             Run Codex iterations in goal mode; final Codex/OMX prompt starts with /goal\n  --codex-backend BACKEND  Backend for --codex-goal: codex or omx (default: detect)\n  --codex-goal-native      Force a native /goal attempt even when backend support is unconfirmed\n  --min-iterations N       Minimum iterations before completion allowed (default: 1)\n  --max-iterations N       Stop after N iterations (default: unlimited)\n  --completion-promise T   Text that signals completion (default: COMPLETE)\n  --abort-promise TEXT     Phrase that signals early abort (e.g., precondition failed)\n  --tasks, -t              Enable Tasks Mode for structured task tracking\n  --task-min-iterations N   Require each top-level task to receive N Ralph iterations before completion (default: 1)\n  --task-promise T         Text that signals task completion (default: READY_FOR_NEXT_TASK)\n  --model MODEL            Model to use (agent-specific)\n  --rotation LIST          Agent/model rotation for each iteration (comma-separated)\n  --prompt-file, --file, -f  Read prompt content from a file\n  --prompt-template PATH   Use custom prompt template (see Custom Prompts)\n  --no-stream              Buffer agent output and print at the end\n  --verbose-tools          Print every tool line (disable compact tool summary)\n  --questions              Enable interactive question handling (default: enabled)\n  --no-questions           Disable interactive question handling (agent will loop on questions)\n  --no-plugins             Disable non-auth OpenCode plugins for this run (opencode only)\n  --no-commit              Don't auto-commit after iterations\n  --allow-all              Auto-approve all tool permissions (default: on)\n  --no-allow-all           Require interactive permission prompts\n  --config PATH            Use custom agent config file\n  --init-config [PATH]     Write default agent config to PATH and exit\n  --help                   Show help\n```\n\n`--codex-goal`\n\nis an opt-in mode for `--agent codex`\n\n. Open Ralph still owns the outer loop: max iterations, process restarts, promise detection, `.ralph/ralph-history.json`\n\n, git/file-system state, and optional auto-commits. Inside each Ralph iteration, the Codex backend receives a final prompt whose first token is `/goal`\n\n, so Codex goal mode can own the single-session push for that iteration.\n\n```\nralph \\\n  \"Complete the task in .harness/goal.md. Run .harness/checks.sh. Output <promise>COMPLETE</promise> when everything passes.\" \\\n  --agent codex \\\n  --codex-goal \\\n  --codex-backend omx \\\n  --max-iterations 5\n```\n\nEquivalent environment form:\n\n```\nRALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx ralph \\\n  \"Complete the task in .harness/goal.md. Run .harness/checks.sh. Output <promise>COMPLETE</promise> when everything passes.\" \\\n  --agent codex \\\n  --max-iterations 5\n```\n\nGoal-mode iterations write a small durable audit ledger to `.ralph/codex-goal-ledger.jsonl`\n\n. This is intentionally file-system state, not Codex thread state, so later Ralph iterations can start fresh while retaining repo-native progress evidence. If native `/goal`\n\ncannot be pre-confirmed, Ralph prints an explicit warning; simulated fallback is used only when native Codex goal support is not available for the selected backend.\n\nTasks Mode allows you to break complex projects into smaller, manageable tasks. Ralph works on one task at a time and tracks progress in a markdown file.\n\n```\n# Enable Tasks Mode\nralph \"Build a complete web application\" --tasks --max-iterations 20\n\n# Custom task completion signal\nralph \"Multi-feature project\" --tasks --task-promise \"TASK_DONE\"\n\n# Require each top-level task to receive three Ralph iterations before task/final completion\nralph \"Multi-feature project\" --tasks --task-min-iterations 3 --max-iterations 20\n# List current tasks\nralph --list-tasks\n\n# Add a new task\nralph --add-task \"Implement user authentication\"\n\n# Remove task by index\nralph --remove-task 3\n\n# Show status (tasks shown automatically when tasks mode is active)\nralph --status\n```\n\n**Task File**: Tasks are stored in`.ralph/ralph-tasks.md`\n\n**One Task Per Iteration**: Ralph focuses on a single task to reduce confusion** Automatic Progression**: When a task completes (`<promise>READY_FOR_NEXT_TASK</promise>`\n\n), Ralph moves to the next eligible task**Task Minimum Iterations**:`--task-min-iterations N`\n\nrequires every top-level task to receive N Ralph outer-loop iterations before task or final completion is accepted. This is separate from global`--min-iterations`\n\n, which gates the whole run.**Task Ledger Fallback**: With task minimums enabled, if the selected top-level task is already`[x]`\n\nwith all subtasks`[x]`\n\nafter its required iterations, Ralph advances from the task ledger even if the agent forgets to emit`READY_FOR_NEXT_TASK`\n\n**Persistent State**: Tasks survive loop restarts; per-task attempt counts are stored in`.ralph/ralph-task-runs.json`\n\nwhen task minimums are enabled**Focused Context**: Smaller contexts per iteration reduce costs and improve reliability\n\nTask status indicators:\n\n`[ ]`\n\n- Not started`[/]`\n\n- In progress`[x]`\n\n- Complete\n\nExample task file:\n\n```\n# Ralph Tasks\n\n- [ ] Set up project structure\n- [x] Initialize git repository\n- [/] Implement user authentication\n  - [ ] Create login page\n  - [ ] Add JWT handling\n- [ ] Build dashboard UI\n```\n\nYou can fully customize the prompt sent to the agent using `--prompt-template`\n\n. This is useful for integrating with custom workflows or tools.\n\n```\nralph \"Build a REST API\" --prompt-template ./my-template.md\n```\n\n**Available variables:**\n\n| Variable | Description |\n|---|---|\n`{{iteration}}` |\nCurrent iteration number |\n`{{max_iterations}}` |\nMaximum iterations (or \"unlimited\") |\n`{{min_iterations}}` |\nMinimum iterations |\n`{{prompt}}` |\nThe user's task prompt |\n`{{completion_promise}}` |\nCompletion promise text (e.g., \"COMPLETE\") |\n`{{abort_promise}}` |\nAbort promise text (if configured) |\n`{{task_promise}}` |\nTask promise text (for tasks mode) |\n`{{task_min_iterations}}` |\nConfigured per-task minimum Ralph iterations (for tasks mode) |\n`{{task_id}}` |\nCurrent selected top-level task id when task-min tracking is active |\n`{{task_text}}` |\nCurrent selected top-level task text when task-min tracking is active |\n`{{task_attempt}}` |\nCurrent selected task attempt count when task-min tracking is active |\n`{{task_min_required}}` |\nRequired attempts for the current selected task |\n`{{task_can_complete}}` |\n`true` when the selected task has met its task minimum |\n`{{task_gate_instruction}}` |\nReady-to-embed task-min guidance for custom templates |\n`{{context}}` |\nAdditional context added mid-loop |\n`{{tasks}}` |\nTask list content (for tasks mode) |\n\n**Example template ( my-template.md):**\n\n```\n# Iteration {{iteration}} / {{max_iterations}}\n\n## Task\n{{prompt}}\n\n## Instructions\n1. Check beads for current status\n2. Decide what to do next\n3. When the epic in beads is complete, output:\n   <promise>{{completion_promise}}</promise>\n\n{{context}}\n# Check status of active loop (run from another terminal)\nralph --status\n\n# Add context/hints for the next iteration\nralph --add-context \"Focus on fixing the auth module first\"\n\n# Clear pending context\nralph --clear-context\n```\n\nThe `--status`\n\ncommand shows:\n\n**Active loop info**: Current iteration, elapsed time, prompt** Pending context**: Any hints queued for next iteration** Current tasks**: Automatically shown when tasks mode is active (or use`--tasks`\n\n)**Iteration history**: Last 5 iterations with tools used, duration** Struggle indicators**: Warnings if agent is stuck (no progress, repeated errors)\n\n```\n╔══════════════════════════════════════════════════════════════════╗\n║                    Ralph Wiggum Status                           ║\n╚══════════════════════════════════════════════════════════════════╝\n\n🔄 ACTIVE LOOP\n   Iteration:    3 / 10\n   Elapsed:      5m 23s\n   Promise:      COMPLETE\n   Prompt:       Build a REST API...\n\n📊 HISTORY (3 iterations)\n   Total time:   5m 23s\n\n   Recent iterations:\n   🔄 #1: 2m 10s | Bash:5 Write:3 Read:2\n   🔄 #2: 1m 45s | Edit:4 Bash:3 Read:2\n   🔄 #3: 1m 28s | Bash:2 Edit:1\n\n⚠️  STRUGGLE INDICATORS:\n   - No file changes in 3 iterations\n   💡 Consider using: ralph --add-context \"your hint here\"\n```\n\nGuide a struggling agent without stopping the loop:\n\n```\n# In another terminal while loop is running\nralph --add-context \"The bug is in utils/parser.ts line 42\"\nralph --add-context \"Try using the singleton pattern for config\"\n```\n\nContext is automatically consumed after one iteration.\n\nThis package is **CLI-only**. If OpenCode tries to load a `ralph-wiggum`\n\nor `open-ralph-wiggum`\n\nplugin,\nremove it from your OpenCode `plugin`\n\nlist (opencode.json), or run:\n\n```\nralph \"Your task\" --no-plugins\n```\n\nIf you see `ProviderModelNotFoundError`\n\nor \"Provider returned error\", you need to configure a default model:\n\n**For OpenCode:**\n\n- Edit\n`~/.config/opencode/opencode.json`\n\n:\n\n```\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"model\": \"your-provider/model-name\"\n}\n```\n\n- Or use the\n`--model`\n\nflag:`ralph \"task\" --model provider/model`\n\n**For other agents:**\nUse the `--model`\n\nflag to specify the model explicitly.\n\nRalph automatically tries `.cmd`\n\nextensions on Windows. If you still have issues:\n\n- Set the full path using environment variables:\n\n```\n$env:RALPH_OPENCODE_BINARY = \"C:\\path\\to\\opencode.cmd\"\n```\n\n- Or add the CLI to your PATH\n\nInstall Bun: [https://bun.sh](https://bun.sh)\n\n❌ Bad:\n\n```\nBuild a todo API\n```\n\n✅ Good:\n\n```\nBuild a REST API for todos with:\n- CRUD endpoints (GET, POST, PUT, DELETE)\n- Input validation\n- Tests for each endpoint\n\nRun tests after changes. Output <promise>COMPLETE</promise> when all tests pass.\n```\n\n❌ Bad:\n\n```\nMake the code better\n```\n\n✅ Good:\n\n```\nRefactor auth.ts to:\n1. Extract validation into separate functions\n2. Add error handling for network failures\n3. Ensure all existing tests still pass\n\nOutput <promise>DONE</promise> when refactored and tests pass.\n# Safety net for runaway loops\nralph \"Your task\" --max-iterations 20\n```\n\nRalph treats prompt files as plain text, so any format works. For best results, use a concise PRD with:\n\n**Goal**: one sentence summary of the desired outcome** Scope**: what is in/out** Requirements**: numbered, testable items** Constraints**: tech stack, performance, security, compatibility** Acceptance criteria**: explicit success checks** Completion promise**: include`<promise>COMPLETE</promise>`\n\n(or match your`--completion-promise`\n\n)\n\nExample (Markdown):\n\n```\n# PRD: Add Export Button\n\n## Goal\nLet users export reports as CSV from the dashboard.\n\n## Scope\n- In: export current report view\n- Out: background exports, scheduling\n\n## Requirements\n1. Add \"Export CSV\" button to dashboard header.\n2. CSV includes columns: date, revenue, sessions.\n3. Works for reports up to 10k rows.\n\n## Constraints\n- Keep current UI styling.\n- Use existing CSV utility in utils/csv.ts.\n\n## Acceptance Criteria\n- Clicking button downloads a valid CSV.\n- CSV opens cleanly in Excel/Sheets.\n- All existing tests pass.\n\n## Completion Promise\n<promise>COMPLETE</promise>\n```\n\nFor larger projects, a structured JSON feature list works better than prose. Based on [Anthropic's research on effective agent harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), JSON format reduces the chance of agents inappropriately modifying test definitions.\n\nCreate a `features.json`\n\nfile:\n\n```\n{\n  \"features\": [\n    {\n      \"category\": \"functional\",\n      \"description\": \"Export button downloads CSV with current report data\",\n      \"steps\": [\n        \"Navigate to dashboard\",\n        \"Click 'Export CSV' button\",\n        \"Verify CSV file downloads\",\n        \"Open CSV and verify columns: date, revenue, sessions\",\n        \"Verify data matches displayed report\"\n      ],\n      \"passes\": false\n    },\n    {\n      \"category\": \"functional\",\n      \"description\": \"Export handles large reports up to 10k rows\",\n      \"steps\": [\n        \"Load report with 10,000 rows\",\n        \"Click 'Export CSV' button\",\n        \"Verify export completes without timeout\",\n        \"Verify all rows present in CSV\"\n      ],\n      \"passes\": false\n    },\n    {\n      \"category\": \"ui\",\n      \"description\": \"Export button matches existing dashboard styling\",\n      \"steps\": [\n        \"Navigate to dashboard\",\n        \"Verify button uses existing button component\",\n        \"Verify button placement in header area\"\n      ],\n      \"passes\": false\n    }\n  ]\n}\n```\n\nThen reference it in your prompt:\n\n```\nRead features.json for the feature list. Work through each feature one at a time.\nAfter verifying a feature works end-to-end, update its \"passes\" field to true.\nDo NOT modify the description or steps - only change the passes boolean.\nOutput <promise>COMPLETE</promise> when all features pass.\n```\n\n**Why JSON?** Agents are less likely to inappropriately modify JSON test definitions compared to Markdown. The structured format keeps agents focused on implementation rather than redefining success criteria.\n\n**Good for:**\n\n- Tasks with automatic verification (tests, linters, type checking)\n- Well-defined tasks with clear completion criteria\n- Greenfield projects where you can walk away\n- Iterative refinement (getting tests to pass)\n\n**Not good for:**\n\n- Tasks requiring human judgment\n- One-shot operations\n- Unclear success criteria\n- Production debugging\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                                                             │\n│   ┌──────────┐    same prompt    ┌──────────┐              │\n│   │          │ ───────────────▶  │          │              │\n│   │  ralph   │                   │ AI Agent │              │\n│   │   CLI    │ ◀─────────────── │          │              │\n│   │          │   output + files  │          │              │\n│   └──────────┘                   └──────────┘              │\n│        │                              │                     │\n│        │ check for                    │ modify              │\n│        │ <promise>                    │ files               │\n│        ▼                              ▼                     │\n│   ┌──────────┐                   ┌──────────┐              │\n│   │ Complete │                   │   Git    │              │\n│   │   or     │                   │  Repo    │              │\n│   │  Retry   │                   │ (state)  │              │\n│   └──────────┘                   └──────────┘              │\n│                                                             │\n└─────────────────────────────────────────────────────────────┘\n```\n\n- Ralph sends your prompt to the selected agent\n- The agent works on the task, modifies files\n- Ralph checks output for completion promise\n- If not found, repeat with same prompt\n- AI sees previous work in files\n- Loop until success or max iterations\n\n```\nralph-wiggum/\n├── bin/ralph.js                  # CLI entrypoint (npm wrapper)\n├── ralph.ts                      # Main loop implementation\n├── package.json                  # Package config\n├── install.sh / install.ps1     # Installation scripts\n└── uninstall.sh / uninstall.ps1 # Uninstallation scripts\n```\n\nDuring operation, Ralph stores state in `.ralph/`\n\n:\n\n`ralph-loop.state.json`\n\n- Active loop state`ralph-history.json`\n\n- Iteration history and metrics`ralph-context.md`\n\n- Pending context for next iteration`ralph-tasks.md`\n\n- Task list for Tasks Mode (created when`--tasks`\n\nis used)`ralph-questions.json`\n\n- Pending user answers to agent questions\n\n```\nnpm uninstall -g @th0rgal/ralph-wiggum\nnpm uninstall -g @th0rgal/ralph-wiggum\n```\n\n[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's official CLI for Claude. Use it with Open Ralph Wiggum for powerful autonomous coding:\n\n```\nralph \"Refactor the auth module and ensure tests pass\" \\\n  --agent claude-code \\\n  --model claude-sonnet-4 \\\n  --max-iterations 15\n```\n\n[Codex](https://github.com/openai/codex) is OpenAI's code-specialized agent. Perfect for code generation and refactoring tasks:\n\n```\nralph \"Generate unit tests for all utility functions\" \\\n  --agent codex \\\n  --model gpt-5-codex \\\n  --max-iterations 10\n```\n\n[OpenCode](https://opencode.ai) is an open-source AI coding assistant. It's the default agent:\n\n```\nralph \"Fix all TypeScript errors\" --max-iterations 10\n```\n\n[Copilot CLI](https://github.com/github/copilot-cli) is GitHub's agentic coding tool (public preview). It requires a GitHub Copilot subscription and authentication via `GH_TOKEN`\n\n, `GITHUB_TOKEN`\n\n, or prior `copilot /login`\n\n.\n\n**Install:**\n\n```\nnpm install -g @github/copilot\n# or\nbrew install copilot-cli\n```\n\n**Usage:**\n\n```\nralph \"Refactor the auth module and add tests\" \\\n  --agent copilot \\\n  --max-iterations 15\n\n# With a specific model\nralph \"Build a REST API\" \\\n  --agent copilot \\\n  --model claude-opus-4.6 \\\n  --max-iterations 10\n```\n\n**Notes:**\n\n- Default model is Claude Sonnet 4.5; override with\n`--model`\n\n`--allow-all`\n\n(default) maps to`--allow-all`\n\n+`--no-ask-user`\n\nin Copilot CLI`--no-plugins`\n\nhas no effect with Copilot CLI- Authentication: set\n`GH_TOKEN`\n\n/`GITHUB_TOKEN`\n\nenv var, or run`copilot /login`\n\nfirst\n\n[Qwen Code](https://github.com/QwenLM/qwen-code) is Alibaba's headless AI coding CLI agent based on the Qwen model family. It uses the same stream-JSON output format as Claude Code.\n\n**Install:**\n\n```\nnpm install -g @qwen-code/qwen-code\n```\n\n**Usage:**\n\n```\nralph \"Refactor the database layer\" \\\n  --agent qwen-code \\\n  --max-iterations 10\n\n# With a specific model\nralph \"Add integration tests for the API\" \\\n  --agent qwen-code \\\n  --model qwen-coder-plus \\\n  --max-iterations 15\n```\n\n**Notes:**\n\n- The CLI binary is\n`qwen`\n\n; override path with`RALPH_QWEN_CODE_BINARY`\n\nenv var `--allow-all`\n\n(default) maps to`--yolo`\n\nin Qwen Code CLI (auto-approves all actions)`--no-plugins`\n\nhas no effect with Qwen Code- Headless mode uses\n`--output-format stream-json --include-partial-messages`\n\n- See\n[headless docs](https://qwenlm.github.io/qwen-code-docs/en/users/features/headless/)for details\n\n[Cursor Agent](https://cursor.com/cli/) is Cursor's headless CLI agent. It works with any model available through your Cursor subscription.\n\n**Install:**\n\n```\ncurl https://cursor.com/install -fsSL | bash\n```\n\n**Usage:**\n\n```\nralph \"Add integration tests for the API\" \\\n  --agent cursor-agent \\\n  --max-iterations 10\n\n# With a specific model\nralph \"Refactor the database layer\" \\\n  --agent cursor-agent \\\n  --model sonnet-4 \\\n  --max-iterations 15\n```\n\n**Notes:**\n\n`--allow-all`\n\n(default) maps to`--force`\n\nin Cursor Agent CLI`--no-plugins`\n\nhas no effect with Cursor Agent- For headless environments (no Cursor window), set the\n`CURSOR_API_KEY`\n\nenvironment variable - The binary is\n`cursor-agent`\n\n; override with`RALPH_CURSOR_AGENT_BINARY`\n\nenv var\n\nAgent rotation lets you cycle through different agent/model combinations across iterations. This is useful for leveraging the strengths of different models or comparing their performance on a task.\n\nEach rotation entry uses the `agent:model`\n\nformat:\n\n```\n--rotation \"agent1:model1,agent2:model2,agent3:model3\"\n```\n\n**Valid agents:** `opencode`\n\n, `claude-code`\n\n, `codex`\n\n, `copilot`\n\n, `cursor-agent`\n\n, `qwen-code`\n\n```\n# Alternate between OpenCode and Claude Code\nralph \"Build a REST API\" \\\n  --rotation \"opencode:claude-sonnet-4,claude-code:claude-sonnet-4\" \\\n  --max-iterations 10\n\n# Cycle through three different configurations\nralph \"Refactor the auth module\" \\\n  --rotation \"opencode:claude-sonnet-4,claude-code:claude-sonnet-4,codex:gpt-5-codex\" \\\n  --max-iterations 15\n\n# Include Copilot in the rotation\nralph \"Build a REST API\" \\\n  --rotation \"opencode:claude-sonnet-4,copilot:claude-sonnet-4\" \\\n  --max-iterations 10\n```\n\nWhen `--rotation`\n\nis used, the `--agent`\n\nand `--model`\n\nflags are **ignored**. The rotation list takes precedence for agent/model selection.\n\nThe rotation cycles back to the first entry after reaching the end:\n\n- Iteration 1 → Entry 1\n- Iteration 2 → Entry 2\n- Iteration 3 → Entry 1 (wraps around for a 2-entry rotation)\n- ...and so on\n\nInvalid rotation entries produce clear error messages:\n\n**Invalid agent name:**\n\n```\nError: Invalid agent 'invalid' in rotation entry 'invalid:model'. Valid agents: opencode, claude-code, codex, copilot, cursor-agent, qwen-code\n```\n\n**Malformed entry (missing colon):**\n\n```\nError: Invalid rotation entry 'opencode-model'. Expected format: agent:model\n```\n\n**Empty values:**\n\n```\nError: Invalid rotation entry 'opencode:'. Both agent and model are required.\n```\n\nWhen using `--status`\n\nwith an active rotation, the output shows all rotation entries and marks the current one:\n\n```\n🔄 ACTIVE LOOP\n   Iteration:    3 / 10\n   Prompt:       Build a REST API...\n\n   Rotation (position 1/2):\n   1. opencode:claude-sonnet-4  **ACTIVE**\n   2. claude-code:claude-sonnet-4\n```\n\nThe `--status`\n\ncommand shows which agent and model was used for each iteration:\n\n```\n📊 HISTORY (3 iterations)\n   Total time:   5m 23s\n\n   Recent iterations:\n   #1  2m 10s  opencode / claude-sonnet-4  Bash(5) Write(3) Read(2)\n   #2  1m 45s  claude-code / claude-sonnet-4  Edit(4) Bash(3) Read(2)\n   #3  1m 28s  opencode / claude-sonnet-4  Bash(2) Edit(1)\n```\n\nCheck out 🏝️ [sandboxed.sh](https://github.com/Th0rgal/sandboxed.sh) — a dashboard for orchestrating AI agents with workspace management, real-time monitoring, and multi-agent workflows.\n\nMIT", "url": "https://wpnews.pro/news/open-ralph-wiggum-autonomous-agentic-loop", "canonical_source": "https://github.com/Th0rgal/open-ralph-wiggum", "published_at": "2026-06-21 08:35:12+00:00", "updated_at": "2026-06-21 08:38:09.576029+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "large-language-models", "generative-ai"], "entities": ["Open Ralph Wiggum", "Claude Code", "OpenAI Codex", "Copilot CLI", "Cursor Agent", "Qwen Code", "OpenCode", "Geoffrey Huntley"], "alternates": {"html": "https://wpnews.pro/news/open-ralph-wiggum-autonomous-agentic-loop", "markdown": "https://wpnews.pro/news/open-ralph-wiggum-autonomous-agentic-loop.md", "text": "https://wpnews.pro/news/open-ralph-wiggum-autonomous-agentic-loop.txt", "jsonld": "https://wpnews.pro/news/open-ralph-wiggum-autonomous-agentic-loop.jsonld"}}