open-ralph-wiggum

Overview

open-ralph-wiggum is an agent-agnostic CLI implementation of the ralph-loop pattern by Th0rgal, published as @th0rgal/ralph-wiggum on npm. Its premise is that the loop is harness-level infrastructure rather than a property of any one coding agent: ralph "Build a REST API" --agent claude-code --max-iterations 10 runs the same workflow across six different agents, switched by a single flag. The README credits Geoffrey Huntley’s Ralph Wiggum technique directly, making this a second-generation implementation rather than an independent invention.

Implications. Where snarktank-ralph is a bash script coupled to a specific PRD format, this is a portable runtime. The loop’s value therefore does not depend on which model or vendor sits behind it — a material detail for anyone deciding whether to build workflow on top of a pattern that could otherwise be locked to a single agent CLI.

Key Facts

• Stars: 1.9k (GitHub, snapshot of 2026-08-04)
• Forks: 142 | Commits: 103
• License: MIT
• Author: Th0rgal
• Runtime: Bun; written in TypeScript (ralph.ts, completion.ts)
• Install: npm install -g @th0rgal/ralph-wiggum, or bun add -g
• Supported agents: claude-code (--agent claude-code), OpenAI Codex, GitHub Copilot CLI, Cursor Agent, Alibaba Qwen Code, and OpenCode (the default)

Implications. The star count is a dated snapshot and will drift; it is recorded with its capture date so a later re-capture can be compared against it rather than silently overwriting it.

Operational Affordances

The CLI documents controls that the pattern’s conceptual descriptions do not:

• --max-iterations — a hard cap, present in every README example. This is the one guardrail that ASDLC lists as an anti-pattern when missing, shipped here as a first-class flag.
• --tasks — built-in task tracking for larger projects; this tool’s equivalent of prd.json.
• --status — live monitoring from a second terminal, including history and “struggle indicators” that surface when the loop is failing to converge.
• --add-context — injects a mid-loop hint without stopping the loop.
• Agent binaries are configurable through environment variables (RALPH_CLAUDE_BINARY, RALPH_CODEX_BINARY, and so on), so the harness assumes no particular install layout.

--add-context deserves the emphasis: an AFK pattern whose whole premise is removing the human from each iteration still ships a deliberate channel for putting the human back in, without discarding accumulated loop state.

Implications. The observability controls are what make an autonomous loop supervisable rather than merely unattended. Struggle indicators and mid-loop hints turn the choice between full autonomy and full babysitting into a dial — a more honest picture of how the pattern is used in practice than either extreme.

Stated Mechanism

The README’s own explanation of why the loop 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.” Memory therefore lives in files and git history rather than in conversation, and the loop terminates on an exact completion string (<promise>DONE</promise>) rather than on the agent’s self-assessment.

With RALPH_CODEX_GOAL=1 and RALPH_CODEX_BACKEND=omx, responsibility is split explicitly across two nested loops: Ralph owns cross-iteration retries, while Codex’s own goal mode owns a single iteration.

Implications. This is the inner/outer loop layering made concrete rather than theoretical — the same division ASDLC.io describes abstractly when it maps the ralph-loop onto OODA as a wrapper around a ReAct-style inner loop.

Limitations

• Every claim here comes from a single vendor-authored source, the project’s own README, captured 2026-08-04. No independent benchmark, adoption study, or third-party review was found, so confidence is medium rather than high.
• The README documents affordances, not outcomes: nothing in it establishes how often loops converge, at what cost, or on which class of task.
• Multi-agent support is asserted per-agent by flag; the snapshot offers no evidence about parity of behaviour across the six agents.

Implications. Treat this page as a description of a tool’s stated design, not as evidence about its effectiveness. Independent measurement would be needed before recommending it operationally.

Relationships

• “implements” ralph-loop — CLI implementation of the pattern, credited to Huntley in its own README
• “is-sibling-of” snarktank-ralph — the other widely used implementation; bash and PRD-coupled where this one is a portable multi-agent runtime
• “operates-with” claude-code — one of six supported agent backends, selected with --agent claude-code

Open Questions

• Does loop behaviour actually hold across all six agents, or does the harness effectively assume Claude-Code-like semantics for the completion promise?
• How do “struggle indicators” decide a loop is stuck — from the agent’s output, or from external verification results?

External Links

• https://github.com/Th0rgal/open-ralph-wiggum
• https://ghuntley.com/ralph/

Sources

• ralph-loop — the pattern this tool implements
• snarktank-ralph — sibling implementation
• claude-code — supported agent backend