opencode-ralph-wiggum

What is Ralph?

Ralph is a development methodology where an AI agent 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 package provides a CLI-only implementation (no OpenCode/Claude Code/Codex plugin).

# The essence of Ralph (agent CLI varies):
while true; do
  opencode run "Build feature X. Output <promise>DONE</promise> when complete."
done

Use --agent claude-code or --agent codex to run the loop with Claude Code or Codex instead of OpenCode.

The AI doesn't talk to itself. It sees the same prompt each time, but the files have changed from previous iterations. This creates a feedback loop where the AI iteratively improves its work until success.

Why Ralph?

| 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 and at least one supported agent CLI: OpenCode, Claude Code, or Codex

npm (recommended)

npm install -g @th0rgal/ralph-wiggum

Bun

bun add -g @th0rgal/ralph-wiggum

From source

git clone https://github.com/Th0rgal/ralph-wiggum
cd opencode-ralph-wiggum
./install.sh

git clone https://github.com/Th0rgal/ralph-wiggum
cd opencode-ralph-wiggum
.\install.ps1

This installs:

• ralph CLI command (global)

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

# Complex project with Tasks Mode
ralph "Build a full-stack web application with user auth and database" \
  --tasks --max-iterations 50

Commands

Running a Loop

ralph "<prompt>" [options]

Options:
  --agent AGENT            AI agent to use: opencode (default), claude-code, codex
  --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)
  --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)
  --prompt-file, --file, -f  Read prompt content from a file
  --no-stream              Buffer agent output and print at the end
  --verbose-tools          Print every tool line (disable compact tool summary)
  --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
  --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

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

"ralph-wiggum" plugin errors

This package is CLI-only. If OpenCode tries to load a ralph-wiggum plugin, remove it from your OpenCode plugin list (opencode.json), or run:

ralph "Your task" --no-plugins

"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