Th0rgal/open-ralph-wiggum: Multi-Agent AI Coding Loop CLI

Th0rgal/open-ralph-wiggum: Multi-Agent AI Coding Loop CLI

AI coding agents are powerful but brittle. A single prompt often produces incomplete code, failing tests, or half-implemented features. Developers find themselves babysitting these tools—checking output, fixing errors, re-prompting. Open Ralph Wiggum solves this by wrapping popular AI coding agents in a persistent, self-correcting loop that keeps working until the job is done.

Built by Th0rgal and inspired by Geoffrey Huntley's Ralph Wiggum technique, this open-source CLI tool (1,841 GitHub stars, MIT licensed) turns one-shot agent interactions into iterative, autonomous workflows. Instead of manually retrying failed attempts, you set a prompt, define completion criteria, and let the loop run—across Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, Qwen Code, and OpenCode.

The core insight: the agent doesn't talk to itself between iterations. It sees the same prompt each time, but the codebase has changed from previous runs. This creates a feedback loop where the agent iteratively improves its work until tests pass or the task completes.

What is Open Ralph Wiggum?

Open Ralph Wiggum is a TypeScript CLI tool built on Bun that implements the Ralph Wiggum technique—an autonomous agentic loop for AI coding agents. Released under the MIT License with active development (last commit June 2, 2026), it occupies a specific niche in the developer tooling landscape: orchestration for AI coding agents, not the agents themselves.

The project is maintained by Thomas Marchand (Th0rgal), a developer known for practical open-source tools including sandboxed.sh—a self-hosted, Git-backed sandbox for AI agent workspaces. This context matters: Open Ralph Wiggum is part of a broader ecosystem focused on making AI agents safer and more autonomous in real development environments.

The tool's relevance stems from a genuine market gap. As of mid-2026, developers have access to multiple capable AI coding agents (Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code, OpenCode), but each requires manual interaction. Open Ralph Wiggum abstracts this away, providing a unified interface where you switch agents with a single --agent flag while keeping the same loop semantics.

Crucially, this is not an AI model or training framework. It is a control layer—a wrapper that handles iteration management, completion detection, git state tracking, and mid-loop intervention. For teams already using these agents, it removes the friction of manual retry loops without replacing their existing tooling investments.

Key Features

Multi-Agent Support

The defining feature is agent flexibility. Open Ralph Wiggum supports six AI coding agents through a unified interface: Claude Code (--agent claude-code), OpenAI Codex (--agent codex), GitHub Copilot CLI (--agent copilot), Cursor Agent (--agent cursor-agent), Qwen Code (--agent qwen-code), and OpenCode (--agent opencode, default). Each agent has its own CLI binary path configurable via environment variables, allowing custom installations or version pinning.

Self-Correcting Iteration Loops

The core mechanism sends the same prompt repeatedly until the agent emits a configurable completion promise (default: <promise>COMPLETE</promise>). Between iterations, the agent sees its previous work in the file system and git history, enabling genuine self-correction. The loop includes safety bounds: --min-iterations prevents premature completion, --max-iterations prevents runaway loops.

Agent Rotation

The --rotation flag cycles through different agent/model combinations across iterations. For example, alternating OpenCode and Claude Code leverages different model strengths—perhaps OpenCode for initial exploration, Claude Code for refinement. This is particularly useful for comparing agent performance or combining complementary capabilities.

Tasks Mode

Complex projects decompose into structured task lists with --tasks. Ralph focuses on one task per iteration, tracking progress in .ralph/ralph-tasks.md. Task minimum iterations (--task-min-iterations) ensure each task receives adequate attention before advancement, with automatic ledger fallback if agents forget completion signals.

Live Monitoring & Mid-Loop Intervention

The --status command from another terminal shows active iteration, elapsed time, recent history with tool usage counts, and "struggle indicators" (warnings for stuck agents). The --add-context flag injects hints without stopping the loop—critical for guiding agents past specific obstacles.

Codex/OMX Goal Mode

An opt-in --codex-goal mode delegates single-session task pushes to Codex's native /goal command or the OMX backend, while Ralph retains outer-loop control (retries, process restarts, promise detection). Goal-mode iterations write audit ledgers to .ralph/codex-goal-ledger.jsonl for cross-iteration progress tracking.

Use Cases

Automated Test-Driven Development

Set Ralph running with a prompt that includes "Run tests after each change. Output <promise>COMPLETE</promise> when all tests pass." The loop naturally handles the TDD cycle: write tests, implement code, see failures, fix failures. This is explicitly documented as a primary use case, with the agent seeing test output from previous iterations and self-correcting.

Long-Running Refactoring Projects

Large-scale refactors—extracting modules, updating APIs, migrating frameworks—exceed single-prompt context windows. Tasks Mode breaks these into sub-tasks ("Extract validation functions," "Update all call sites," "Verify tests pass"), with Ralph working through each systematically. The --max-iterations 50 safety bound prevents infinite loops while allowing substantial work.

Cross-Agent Benchmarking

Use --rotation to compare how Claude Code, Codex, and Copilot CLI handle identical prompts. This produces actionable data about which agent performs best for specific task types in your codebase—valuable for teams standardizing on AI tooling.

Headless CI/CD Integration

With --no-questions and --allow-all, Ralph runs fully non-interactively. Combined with sandboxed environments (the maintainer's sandboxed.sh is explicitly recommended), this enables automated code generation pipelines where human oversight happens at PR review, not during generation.

Greenfield Prototype Development

For well-scoped new projects with clear acceptance criteria, Ralph can work autonomously for extended periods. The JSON feature list format (documented in the README, based on Anthropic research) reduces agent deviation by providing structured, hard-to-inappropriately-modify success criteria.

Installation & Setup

Prerequisites:

• Bun runtime
• At least one AI coding agent CLI installed (Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code, or OpenCode)

Via npm (recommended):

npm install -g @th0rgal/ralph-wiggum

This installs the ralph command globally. The npm package name is scoped to @th0rgal/ralph-wiggum.

Via Bun:

bun add -g @th0rgal/ralph-wiggum

For Bun users who prefer the native package manager.

From source:

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

Windows users use install.ps1 instead. The source install is useful for development or when you need unreleased features.

Configuring Agent Binaries:

If agents are installed in non-standard locations, set environment variables:

export RALPH_CLAUDE_BINARY="/opt/homebrew/bin/claude"
export RALPH_CODEX_BINARY="/usr/local/bin/codex"
export RALPH_OPENCODE_BINARY="~/.local/bin/opencode"

Windows users: Ralph automatically resolves .cmd extensions for npm-installed CLIs. If "command not found" persists, use full paths via environment variables or PowerShell: $env:RALPH_OPENCODE_BINARY = "C:\path\to\opencode.cmd".

Verifying Installation:

ralph --help

This should display the full option list including --agent, --max-iterations, --tasks, and --status.

Real Code Examples

Example 1: Basic Loop with Iteration Limit

# Simple task with safety bound
ralph "Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete." \
  --max-iterations 5

This demonstrates the minimal viable usage: a clear prompt with explicit completion signal (<promise>DONE</promise>) and a hard iteration ceiling. The --max-iterations 5 prevents infinite loops if the agent fails to emit the completion promise. The default completion promise is COMPLETE, but you can override with --completion-promise or include a custom string directly in the prompt as shown here.

Example 2: Building with Claude Code

ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  --agent claude-code \
  --model claude-sonnet-4 \
  --max-iterations 5

This shows agent selection (--agent claude-code), model specification (--model claude-sonnet-4), and the standard completion pattern. The --model flag passes through to the underlying agent CLI—valid values are agent-specific. For Claude Code, claude-sonnet-4 refers to Anthropic's Claude Sonnet 4 model.

Example 3: Codex Goal Mode with OMX Backend

# Environment-variable form for goal mode
RALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx \
ralph "Complete the task described in .harness/goal.md. Run .harness/checks.sh. Output <promise>COMPLETE</promise> when everything passes." \
  --agent codex \
  --max-iterations 5

This advanced configuration enables Codex's native /goal mode through the OMX backend. Ralph handles the outer loop (retries, restarts, promise detection) while delegating single-iteration task execution to Codex goal mode. The .harness/goal.md and .harness/checks.sh files provide structured task definition and verification—this pattern is recommended for complex, verifiable tasks.

Example 4: Tasks Mode for Complex Projects

ralph "Build a full-stack web application with user auth and database" \
  --tasks \
  --max-iterations 50

Tasks Mode automatically creates .ralph/ralph-tasks.md and manages task progression. The agent focuses on one task per iteration, emitting <promise>READY_FOR_NEXT_TASK</promise> to advance. For large projects, this prevents context overflow and keeps the agent focused.

Advanced Usage & Best Practices

Prompt Engineering for Reliability

The README emphasizes concrete, verifiable prompts. Include explicit success criteria, not vague goals. The documented JSON feature list format (based on Anthropic's research on agent harnesses) reduces agent deviation by making test definitions harder to inappropriately modify than Markdown^{↗ Smart Converter}.

Monitoring and Intervention

Run ralph --status from a second terminal to check progress without disrupting the loop. If struggle indicators appear (repeated errors, no file changes), use ralph --add-context "specific hint" to guide the agent. This mid-loop intervention is a key differentiator from simpler retry scripts.

Git Hygiene

Ralph auto-commits after iterations by default (--no-commit to disable). This provides natural rollback points. For production codebases, consider requiring manual commit review or using Ralph in isolated branches.

Sandboxing

The README explicitly recommends sandboxed.sh for isolated Linux workspaces per task. This is particularly important when using --allow-all (default), which auto-approves all tool permissions. The combination of Ralph's persistence with sandboxed execution addresses the genuine risk of agents making unintended system changes.

Task Minimum Iterations

For Tasks Mode, --task-min-iterations N ensures each task receives adequate attention. This prevents agents from prematurely marking tasks complete. The separate per-task minimum from global --min-iterations allows fine-grained control.

Comparison with Alternatives

Trade-offs: Open Ralph Wiggum's strength is unified multi-agent orchestration with minimal abstraction—it's a thin control layer, not a full IDE integration. Aider offers deeper editor integration and pair-programming semantics but doesn't provide the same persistent autonomous loop. Raw agent CLIs require manual retry management. The Ralph Orchestrator (referenced in the README) appears to be a related project with potentially different scope, though its exact feature set isn't detailed in the source material.

For teams already using multiple AI agents and wanting to automate retry loops without replacing their tooling, Open Ralph Wiggum's approach is pragmatic. For developers wanting tight editor integration, Aider or native IDE features may fit better.

FAQ

What AI agents does Open Ralph Wiggum support?

Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, Qwen Code, and OpenCode. Switch with --agent.

Is Open Ralph Wiggum free?

Yes, MIT licensed. You still need subscriptions for proprietary agents (Claude Code, Copilot, Cursor).

Does it work on Windows?

Yes, with automatic .cmd resolution. Set full paths via environment variables if needed.

How do I stop a runaway loop?

Set --max-iterations or use --abort-promise for early termination conditions.

Can I use my own prompt template?

Yes, --prompt-template with variables like {{iteration}}, {{prompt}}, {{completion_promise}}.

What's the difference from just running a bash while loop?

Ralph adds completion detection, git state tracking, task management, status monitoring, and mid-loop context injection.

Does it modify my code without asking?

The underlying agent does; Ralph wraps it. Use --no-allow-all for interactive permission prompts, or sandbox with sandboxed.sh.

Conclusion

Open Ralph Wiggum fills a specific, valuable niche: making existing AI coding agents genuinely autonomous. For developers tired of babysitting Claude Code or Codex through multiple retry cycles, it provides the control layer that turns interactive tools into background workers.

The tool is best suited for: teams with clear success criteria (tests, linters, structured feature lists); developers already using multiple AI agents who want unified orchestration; and headless/automated workflows where manual intervention is undesirable. It's less suited for exploratory coding without clear completion definitions, or tasks requiring continuous human judgment.

With 1,841 stars, active maintenance, and a focused scope that complements rather than replaces agent ecosystems, Open Ralph Wiggum is worth evaluating if persistent, self-correcting AI coding loops fit your workflow. The MIT license and Bun-based TypeScript codebase make it hackable for custom needs.

Get started at https://github.com/Th0rgal/open-ralph-wiggum.

For related reading on isolating AI agent environments, see [INTERNAL_LINK: sandboxed-ai-workspaces].