Open Ralph Wiggum

Autonomous Agentic Loop for Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code & OpenCode

Works with Claude Code, OpenAI Codex, Copilot CLI, Cursor Agent, Qwen Code, and OpenCode — switch agents with --agent.

Based on the Ralph Wiggum technique by Geoffrey Huntley

Supported Agents • What is Ralph? • Installation • Quick Start • Commands

Tired of agents breaking your local environment?

🏝️ sandboxed.sh gives each task an isolated Linux workspace. Self-hosted. Git-backed.

💬 Join the community: relens.ai/community

---

Supported 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 --tasks mode
• Live Monitoring — Check progress with --status from another terminal
• Mid-Loop Hints — Inject guidance with --add-context without 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 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_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
  --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-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

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"

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

1. Task File: Tasks are stored in .ralph/ralph-tasks.md
2. One Task Per Iteration: Ralph focuses on a single task to reduce confusion
3. Automatic Progression: When a task completes (<promise>READY_FOR_NEXT_TASK</promise>), Ralph moves to the next
4. Persistent State: Tasks survive loop restarts
5. 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)
{{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