VerifiedPlugin
Development
sandboxedsh
Safe runtime for autonomous on-chain AI agents: isolated sandboxes, Library skills, encrypted secrets.
5 skills
@th0rgalDevelopment
Plugin
open-ralph-wiggum
Type `ralph "prompt"` to start open code in a ralph loop. Also supports a prompt file & status check. Open Code, Claude Code, Codex, Copilot
Plugin Signal58/100Fair
maintained66
capable14
documented100
adopted70
Install
$ npx -y skills add Th0rgal/open-ralph-wiggum --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
1,874
Stars
142
Forks
Maintained
Maintenance
TypeScript
Language
MIT
License
2mo ago
Last commit
7mo ago
Created
Repo: Th0rgal/open-ralph-wiggum
What's inside
README
1Supported Agents
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
What is Open Ralph Wiggum?
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.
Multi-Agent Flexibility
Switch between AI coding agents without changing your workflow:
- Claude Code (
--agent claude-code) — Anthropic's powerful coding agent - Codex (
--agent codex) — OpenAI's code-specialized model - Copilot CLI (
--agent copilot) — GitHub's agentic coding tool - Cursor Agent (
--agent cursor-agent) — Cursor's headless AI coding agent - Qwen Code (
--agent qwen-code) — Alibaba's Qwen Code headless CLI agent - OpenCode (
--agent opencode) — Open-source default option
Key Features
- 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
--tasksmode - Live Monitoring — Check progress with
--statusfrom another terminal - Mid-Loop Hints — Inject guidance with
--add-contextwithout stopping
Why Use an Agentic Loop?
| 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 |
Installation
Prerequisites:
- Bun runtime
- At least one AI coding agent CLI:
- Claude Code — Anthropic's Claude Code CLI
- Codex — OpenAI's Codex CLI
- Copilot CLI — GitHub's Copilot CLI
- Cursor Agent — Cursor's headless Agent CLI
- Qwen Code — Alibaba's Qwen Code CLI
- OpenCode — Open-source AI coding assistant
npm (recommended)
npm install -g @th0rgal/ralph-wiggum
Bun
bun add -g @th0rgal/ralph-wiggum
From source
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.
Quick Start
# 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 Codex goal mode through OMX: Ralph owns cross-iteration retries, /goal owns one iteration
RALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx \
ralph "Complete the task described in .harness/goal.md. Output <promise>COMPLETE</promise> when everything passes." \
--agent 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
Environment Variables
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_CODEX_GOAL | Enable Codex goal mode for --agent codex (1, true, yes, on) | unset |
RALPH_CODEX_BACKEND | Goal-mode backend: codex or omx | detected from configured codex command |
RALPH_CODEX_GOAL_NATIVE | Force native /goal attempt even when support is not pre-confirmed | unset |
OMX_RALPH_OMX_BIN | Path to OMX CLI when RALPH_CODEX_BACKEND=omx | "omx" |
OMX_RALPH_REASONING | model_reasoning_effort passed to omx exec in goal mode | "high" |
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.
Commands
Running a Loop
ralph "<prompt>" [options]
Options:
--agent AGENT AI agent to use: opencode (default), claude-code, codex, copilot, cursor-agent, qwen-code
--codex-goal Run Codex iterations in goal mode; final Codex/OMX prompt starts with /goal
--codex-backend BACKEND Backend for --codex-goal: codex or omx (default: detect)
--codex-goal-native Force a native /goal attempt even when backend support is unconfirmed
--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-min-iterations N Require each top-level task to receive N Ralph iterations before completion (default: 1)
--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-commit Don't auto-commit after iterations
--allow-all Auto-approve all tool permissions (default: on)
--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
--help Show help
Codex / OMX Goal Mode
--codex-goal is an opt-in mode for --agent codex. Open Ralph still owns the outer loop: max iterations, process restarts, promise detection, .ralph/ralph-history.json, git/file-system state, and optional auto-commits. Inside each Ralph iteration, the Codex backend receives a final prompt whose first token is /goal, so Codex goal mode can own the single-session push for that iteration.
ralph \
"Complete the task in .harness/goal.md. Run .harness/checks.sh. Output <promise>COMPLETE</promise> when everything passes." \
--agent codex \
--codex-goal \
--codex-backend omx \
--max-iterations 5
Equivalent environment form:
RALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx ralph \
"Complete the task in .harness/goal.md. Run .harness/checks.sh. Output <promise>COMPLETE</promise> when everything passes." \
--agent codex \
--max-iterations 5
Goal-mode iterations write a small durable audit ledger to .ralph/codex-goal-ledger.jsonl. 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 cannot 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.
Tasks Mode
Tasks 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.
# Enable Tasks Mode
ralph "Build a complete web application" --tasks --max-iterations 20
# Custom task completion signal
ralph "Multi-feature project" --tasks --task-promise "TASK_DONE"
# Require each top-level task to receive three Ralph iterations before task/final completion
ralph "Multi-feature project" --tasks --task-min-iterations 3 --max-iterations 20
Task Management Commands
# List current tasks
ralph --list-tasks
# Add a new task
ralph --add-task "Implement user authentication"
# Remove task by index
ralph --remove-task 3
# Show status (tasks shown automatically when tasks mode is active)
ralph --status
How Tasks Mode Works
- Task File: Tasks are stored in
.ralph/ralph-tasks.md - 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>), Ralph moves to the next eligible task - Task Minimum Iterations:
--task-min-iterations 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, which gates the whole run. - Task Ledger Fallback: With task minimums enabled, if the selected top-level task is already
[x]with all subtasks[x]after its required iterations, Ralph advances from the task ledger even if the agent forgets to emitREADY_FOR_NEXT_TASK - Persistent State: Tasks survive loop restarts; per-task attempt counts are stored in
.ralph/ralph-task-runs.jsonwhen task minimums are enabled - Focused Context: Smaller contexts per iteration reduce costs and improve reliability
Task status indicators:
[ ]- Not started[/]- In progress[x]- Complete
Example task file:
# Ralph Tasks
- [ ] Set up project structure
- [x] Initialize git repository
- [/] Implement user authentication
- [ ] Create login page
- [ ] Add JWT handling
- [ ] Build dashboard UI
Custom Prompt Templates
You can fully customize the prompt sent to the agent using --prompt-template. This is useful for integrating with custom workflows or tools.
ralph "Build a REST API" --prompt-template ./my-template.md
Available variables:
| Variable | Description |
|---|---|
{{iteration}} | Current iteration number |
{{max_iterations}} | Maximum iterations (or "unlimited") |
{{min_iterations}} | Minimum iterations |
{{prompt}} | The user's task prompt |
{{completion_promise}} | Completion promise text (e.g., "COMPLETE") |
{{abort_promise}} | Abort promise text (if configured) |
{{task_promise}} | Task promise text (for tasks mode) |
{{task_min_iterations}} | Configured per-task minimum Ralph iterations (for tasks mode) |
{{task_id}} | Current selected top-level task id when task-min tracking is active |
{{task_text}} | Current selected top-level task text when task-min tracking is active |
{{task_attempt}} | Current selected task attempt count when task-min tracking is active |
{{task_min_required}} | Required attempts for the current selected task |
{{task_can_complete}} | true when the selected task has met its task minimum |
{{task_gate_instruction}} | Ready-to-embed task-min guidance for custom templates |
{{context}} | Additional context added mid-loop |
{{tasks}} | Task list content (for tasks mode) |
Example template (my-template.md):
# Iteration {{iteration}} / {{max_iterations}}
## Task
{{prompt}}
## Instructions
1. Check beads for current status
2. Decide what to do next
3. When the epic in beads is complete, output:
<promise>{{completion_promise}}</promise>
{{context}}
Monitoring & Control
# Check status of active loop (run from another terminal)
ralph --status
# Add context/hints for the next iteration
ralph --add-context "Focus on fixing the auth module first"
# Clear pending context
ralph --clear-context
Status Dashboard
The --status command shows:
- 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) - Iteration history: Last 5 iterations with tools used, duration
- Struggle indicators: Warnings if agent is stuck (no progress, repeated errors)
╔══════════════════════════════════════════════════════════════════╗
║ Ralph Wiggum Status ║
╚══════════════════════════════════════════════════════════════════╝
🔄 ACTIVE LOOP
Iteration: 3 / 10
Elapsed: 5m 23s
Promise: COMPLETE
Prompt: Build a REST API...
📊 HISTORY (3 iterations)
Total time: 5m 23s
Recent iterations:
🔄 #1: 2m 10s | Bash:5 Write:3 Read:2
🔄 #2: 1m 45s | Edit:4 Bash:3 Read:2
🔄 #3: 1m 28s | Bash:2 Edit:1
⚠️ STRUGGLE INDICATORS:
- No file changes in 3 iterations
💡 Consider using: ralph --add-context "your hint here"
Mid-Loop Context Injection
Guide a struggling agent without stopping the loop:
# In another terminal while loop is running
ralph --add-context "The bug is in utils/parser.ts line 42"
ralph --add-context "Try using the singleton pattern for config"
Context is automatically consumed after one iteration.
Troubleshooting
Plugin errors
This package is CLI-only. If OpenCode tries to load a ralph-wiggum or open-ralph-wiggum plugin,
remove it from your OpenCode plugin list (opencode.json), or run:
ralph "Your task" --no-plugins
ProviderModelNotFoundError / Model not configured
If you see ProviderModelNotFoundError or "Provider returned error", you need to configure a default model:
For OpenCode:
- Edit
~/.config/opencode/opencode.json:{ "$schema": "https://opencode.ai/config.json", "model": "your-provider/model-name" } - Or use the
--modelflag:ralph "task" --model provider/model
For other agents:
Use the --model flag to specify the model explicitly.
"command not found" on Windows
Ralph automatically tries .cmd extensions on Windows. If you still have issues:
- Set the full path using environment variables:
$env:RALPH_OPENCODE_BINARY = "C:\path\to\opencode.cmd" - Or add the CLI to your PATH
"bun: command not found"
Install Bun: https://bun.sh
Writing Good Prompts
Include Clear Success Criteria
❌ Bad:
Build a todo API
✅ Good:
Build a REST API for todos with:
- CRUD endpoints (GET, POST, PUT, DELETE)
- Input validation
- Tests for each endpoint
Run tests after changes. Output <promise>COMPLETE</promise> when all tests pass.
Use Verifiable Conditions
❌ Bad:
Make the code better
✅ Good:
Refactor auth.ts to:
1. Extract validation into separate functions
2. Add error handling for network failures
3. Ensure all existing tests still pass
Output <promise>DONE</promise> when refactored and tests pass.
Always Set Max Iterations
# Safety net for runaway loops
ralph "Your task" --max-iterations 20
Recommended PRD Format
Ralph treats prompt files as plain text, so any format works. For best results, use a concise PRD with:
- 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>(or match your--completion-promise)
Example (Markdown):
# PRD: Add Export Button
## Goal
Let users export reports as CSV from the dashboard.
## Scope
- In: export current report view
- Out: background exports, scheduling
## Requirements
1. Add "Export CSV" button to dashboard header.
2. CSV includes columns: date, revenue, sessions.
3. Works for reports up to 10k rows.
## Constraints
- Keep current UI styling.
- Use existing CSV utility in utils/csv.ts.
## Acceptance Criteria
- Clicking button downloads a valid CSV.
- CSV opens cleanly in Excel/Sheets.
- All existing tests pass.
## Completion Promise
<promise>COMPLETE</promise>
JSON Feature List (Recommended for Complex Projects)
For larger projects, a structured JSON feature list works better than prose. Based on Anthropic's research on effective agent harnesses, JSON format reduces the chance of agents inappropriately modifying test definitions.
Create a features.json file:
{
"features": [
{
"category": "functional",
"description": "Export button downloads CSV with current report data",
"steps": [
"Navigate to dashboard",
"Click 'Export CSV' button",
"Verify CSV file downloads",
"Open CSV and verify columns: date, revenue, sessions",
"Verify data matches displayed report"
],
"passes": false
},
{
"category": "functional",
"description": "Export handles large reports up to 10k rows",
"steps": [
"Load report with 10,000 rows",
"Click 'Export CSV' button",
"Verify export completes without timeout",
"Verify all rows present in CSV"
],
"passes": false
},
{
"category": "ui",
"description": "Export button matches existing dashboard styling",
"steps": [
"Navigate to dashboard",
"Verify button uses existing button component",
"Verify button placement in header area"
],
"passes": false
}
]
}
Then reference it in your prompt:
Read features.json for the feature list. Work through each feature one at a time.
After verifying a feature works end-to-end, update its "passes" field to true.
Do NOT modify the description or steps - only change the passes boolean.
Output <promise>COMPLETE</promise> when all features pass.
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.
When to Use Ralph
Good for:
- Tasks with automatic verification (tests, linters, type checking)
- Well-defined tasks with clear completion criteria
- Greenfield projects where you can walk away
- Iterative refinement (getting tests to pass)
Not good for:
- Tasks requiring human judgment
- One-shot operations
- Unclear success criteria
- Production debugging
How It Works
┌─────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ same prompt ┌──────────┐ │
│ │ │ ───────────────▶ │ │ │
│ │ ralph │ │ AI Agent │ │
│ │ CLI │ ◀─────────────── │ │ │
│ │ │ output + files │ │ │
│ └──────────┘ └──────────┘ │
│ │ │ │
│ │ check for │ modify │
│ │ <promise> │ files │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Complete │ │ Git │ │
│ │ or │ │ Repo │ │
│ │ Retry │ │ (state) │ │
│ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
- Ralph sends your prompt to the selected agent
- The agent works on the task, modifies files
- Ralph checks output for completion promise
- If not found, repeat with same prompt
- AI sees previous work in files
- Loop until success or max iterations
Project Structure
ralph-wiggum/
├── bin/ralph.js # CLI entrypoint (npm wrapper)
├── ralph.ts # Main loop implementation
├── package.json # Package config
├── install.sh / install.ps1 # Installation scripts
└── uninstall.sh / uninstall.ps1 # Uninstallation scripts
State Files (in .ralph/)
During operation, Ralph stores state in .ralph/:
ralph-loop.state.json- Active loop stateralph-history.json- Iteration history and metricsralph-context.md- Pending context for next iterationralph-tasks.md- Task list for Tasks Mode (created when--tasksis used)ralph-questions.json- Pending user answers to agent questions
Uninstall
npm uninstall -g @th0rgal/ralph-wiggum
npm uninstall -g @th0rgal/ralph-wiggum
Agent-Specific Notes
Claude Code
Claude Code is Anthropic's official CLI for Claude. Use it with Open Ralph Wiggum for powerful autonomous coding:
ralph "Refactor the auth module and ensure tests pass" \
--agent claude-code \
--model claude-sonnet-4 \
--max-iterations 15
OpenAI Codex
Codex is OpenAI's code-specialized agent. Perfect for code generation and refactoring tasks:
ralph "Generate unit tests for all utility functions" \
--agent codex \
--model gpt-5-codex \
--max-iterations 10
OpenCode
OpenCode is an open-source AI coding assistant. It's the default agent:
ralph "Fix all TypeScript errors" --max-iterations 10
Copilot CLI
Copilot CLI is GitHub's agentic coding tool (public preview). It requires a GitHub Copilot subscription and authentication via GH_TOKEN, GITHUB_TOKEN, or prior copilot /login.
Install:
npm install -g @github/copilot
# or
brew install copilot-cli
Usage:
ralph "Refactor the auth module and add tests" \
--agent copilot \
--max-iterations 15
# With a specific model
ralph "Build a REST API" \
--agent copilot \
--model claude-opus-4.6 \
--max-iterations 10
Notes:
- Default model is Claude Sonnet 4.5; override with
--model --allow-all(default) maps to--allow-all+--no-ask-userin Copilot CLI--no-pluginshas no effect with Copilot CLI- Authentication: set
GH_TOKEN/GITHUB_TOKENenv var, or runcopilot /loginfirst
Qwen Code
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.
Install:
npm install -g @qwen-code/qwen-code
Usage:
ralph "Refactor the database layer" \
--agent qwen-code \
--max-iterations 10
# With a specific model
ralph "Add integration tests for the API" \
--agent qwen-code \
--model qwen-coder-plus \
--max-iterations 15
Notes:
- The CLI binary is
qwen; override path withRALPH_QWEN_CODE_BINARYenv var --allow-all(default) maps to--yoloin Qwen Code CLI (auto-approves all actions)--no-pluginshas no effect with Qwen Code- Headless mode uses
--output-format stream-json --include-partial-messages - See headless docs for details
Cursor Agent
Cursor Agent is Cursor's headless CLI agent. It works with any model available through your Cursor subscription.
Install:
curl https://cursor.com/install -fsSL | bash
Usage:
ralph "Add integration tests for the API" \
--agent cursor-agent \
--max-iterations 10
# With a specific model
ralph "Refactor the database layer" \
--agent cursor-agent \
--model sonnet-4 \
--max-iterations 15
Notes:
--allow-all(default) maps to--forcein Cursor Agent CLI--no-pluginshas no effect with Cursor Agent- For headless environments (no Cursor window), set the
CURSOR_API_KEYenvironment variable - The binary is
cursor-agent; override withRALPH_CURSOR_AGENT_BINARYenv var
Agent Rotation
Agent 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.
Format
Each rotation entry uses the agent:model format:
--rotation "agent1:model1,agent2:model2,agent3:model3"
Valid agents: opencode, claude-code, codex, copilot, cursor-agent, qwen-code
Example Usage
# Alternate between OpenCode and Claude Code
ralph "Build a REST API" \
--rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4" \
--max-iterations 10
# Cycle through three different configurations
ralph "Refactor the auth module" \
--rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4,codex:gpt-5-codex" \
--max-iterations 15
# Include Copilot in the rotation
ralph "Build a REST API" \
--rotation "opencode:claude-sonnet-4,copilot:claude-sonnet-4" \
--max-iterations 10
Flag Interaction
When --rotation is used, the --agent and --model flags are ignored. The rotation list takes precedence for agent/model selection.
Cycling Behavior
The rotation cycles back to the first entry after reaching the end:
- Iteration 1 → Entry 1
- Iteration 2 → Entry 2
- Iteration 3 → Entry 1 (wraps around for a 2-entry rotation)
- ...and so on
Error Messages
Invalid rotation entries produce clear error messages:
Invalid agent name:
Error: Invalid agent 'invalid' in rotation entry 'invalid:model'. Valid agents: opencode, claude-code, codex, copilot, cursor-agent, qwen-code
Malformed entry (missing colon):
Error: Invalid rotation entry 'opencode-model'. Expected format: agent:model
Empty values:
Error: Invalid rotation entry 'opencode:'. Both agent and model are required.
Status Display
When using --status with an active rotation, the output shows all rotation entries and marks the current one:
🔄 ACTIVE LOOP
Iteration: 3 / 10
Prompt: Build a REST API...
Rotation (position 1/2):
1. opencode:claude-sonnet-4 **ACTIVE**
2. claude-code:claude-sonnet-4
Iteration History
The --status command shows which agent and model was used for each iteration:
📊 HISTORY (3 iterations)
Total time: 5m 23s
Recent iterations:
#1 2m 10s opencode / claude-sonnet-4 Bash(5) Write(3) Read(2)
#2 1m 45s claude-code / claude-sonnet-4 Edit(4) Bash(3) Read(2)
#3 1m 28s opencode / claude-sonnet-4 Bash(2) Edit(1)
Learn More
See Also
Check out 🏝️ sandboxed.sh — a dashboard for orchestrating AI agents with workspace management, real-time monitoring, and multi-agent workflows.
License
MIT
File tree
28Th0rgal/open-ralph-wiggumView on GitHub
.github/
workflows/
ci.yml
.gitignore
bin/
ralph.js
bun.lock
completion.ts
contrib/
omx/
agents.example.json
install.sh
omx-codex-exec-for-ralph
ralph-omx
README.md
test-smoke.sh
docs/
ralph-omx.md
install.ps1
install.sh
LICENSE
package.json
ralph.ts
README.md
screenshot.webp
scripts/
test-codex-goal-mode.sh
skills/
open-ralph-wiggum/
SKILL.md
tests/
fixtures/
fake-opencode.ts
fake-successful-model-output.ts
model-error-detection.test.ts
ralph.test.ts
sigint-cleanup.test.ts
uninstall.ps1
uninstall.shMore Flows by @th0rgal.
@th0rgalFAQ
open-ralph-wiggum is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes open-ralph-wiggum. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is open-ralph-wiggum?
- Type `ralph "prompt"` to start open code in a ralph loop. Also supports a prompt file & status check. Open Code, Claude Code, Codex, Copilot
- How do I install open-ralph-wiggum?
- Run these in Claude Code: npx -y skills add Th0rgal/open-ralph-wiggum --agent claude-code. Then prompt normally.
- Does open-ralph-wiggum auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is open-ralph-wiggum free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.