Ralph Loop Dev Loop

Relevant source files

The following files were used as context for generating this wiki page:

• src/features/builtin-commands/templates/ralph-loop.ts
• src/agents/sisyphus.ts
• src/agents/hephaestus/gpt-5-4.ts
• src/agents/prometheus/gpt.ts
• src/hooks/keyword-detector/ultrawork/gpt.ts
• src/agents/momus.ts

The Ralph Loop is a self-referential development system designed to facilitate continuous, autonomous progress toward task completion. Within the OhMyOpenCode ecosystem, it functions as an execution framework where an agent (typically Sisyphus or Hephaestus) works iteratively on a complex goal until a specific "completion promise" is issued.

The system is engineered to handle multi-step software engineering tasks by maintaining session state and automatically re-injecting prompts if the agent fails to provide a termination signal. This ensures that the agent does not stop at partial implementation but persists through exploration, planning, execution, and verification phases.

Sources: src/features/builtin-commands/templates/ralph-loop.ts:3-10, src/agents/sisyphus.ts:60-75

Core Mechanism and Iteration Logic

The Ralph Loop operates on a "work-until-promised" logic. Unlike standard single-turn interactions, the loop maintains a stateful session where each iteration is expected to make meaningful progress.

Iteration Flow

1. Continuous Execution: The agent processes the task description and utilizes available tools (e.g., grep, read_file, task_create).
2. State Management: Progress is tracked via a loop state file.
3. Completion Signal: The agent must output a specific XML-tagged promise <promise>{{COMPLETION_PROMISE}}</promise> to exit the loop.
4. Automatic Re-injection: If the promise tag is absent, the system automatically triggers another iteration, providing continuity until the maximum iteration limit is reached.

The following diagram illustrates the lifecycle of a Ralph Loop execution:

A flowchart showing the iterative logic of the Ralph Loop, from initialization to completion promise detection.
Sources: src/features/builtin-commands/templates/ralph-loop.ts:3-16, src/agents/hephaestus/gpt-5-4.ts:47-65

Operational Variants

The loop system supports different modes depending on the intensity and accuracy required for the task.

Ralph Loop vs. ULTRAWORK Loop

Feature	Ralph Loop	ULTRAWORK Loop
Primary Goal	Task completion	Verified completion
Max Iterations	100 (Default)	500 (Ultrawork) / 100 (Normal)
Exit Condition	Completion Promise	Promise + Oracle Verification
Verification	Agent self-verification	System-enforced Oracle verification

Sources: src/features/builtin-commands/templates/ralph-loop.ts:3-56, src/hooks/keyword-detector/ultrawork/gpt.ts:5-15

ULTRAWORK Mode Integration

In ULTRAWORK mode, the loop adds a mandatory verification layer. The agent's "DONE" signal is treated as a tentative completion that must be validated by an oracle or momus agent.
Sources: src/features/builtin-commands/templates/ralph-loop.ts:40-48, src/agents/momus.ts:15-30

Configuration and Control

Users can control the behavior of the loop through specific command arguments and exit conditions.

Argument Parsing

The loop accepts several parameters to define its execution strategy:

• Task Description: The primary goal to be achieved.
• Completion Promise: Custom text string (default: "DONE") that signals the end.
• Max Iterations: The upper limit of execution turns (default: 100).
• Strategy: Determines if the loop should reset or continue from previous state.

Cancellation

The loop can be terminated manually using the /cancel-ralph command. This stops the automatic continuation, clears the state file, and allows the session to conclude.
Sources: src/features/builtin-commands/templates/ralph-loop.ts:25-30, src/features/builtin-commands/templates/ralph-loop.ts:58-65

Architectural Role of Agents in the Loop

The Ralph Loop relies on specialized agent identities to fulfill different phases of the development cycle.

Sisyphus: The Orchestrator

Sisyphus acts as the primary primary agent in the loop. Its role is to:

• Break down complex requests into atomic todo items.
• Delegate specialized domains (e.g., UI, Git) to subagents.
• Maintain the "boulder" (task progress) across iterations.
  Sources: src/agents/sisyphus.ts:65-85, src/agents/sisyphus/gpt-5-4.ts:100-115

Prometheus: The Strategic Planner

Before the loop begins intensive execution, Prometheus is often utilized to generate a "decision-complete" work plan. This plan serves as the roadmap for the Ralph Loop iterations.
Sources: src/agents/prometheus/gpt.ts:20-35, src/agents/prometheus/gpt.ts:155-170

Execution and Verification Sequence

The loop follows a strict execution pattern to ensure code quality:

A sequence diagram showing the interaction between the Loop Controller, the working Agent, and project tools during multiple iterations.
Sources: src/agents/hephaestus/gpt-5-4.ts:160-185, src/features/builtin-commands/templates/ralph-loop.ts:5-15

Conclusion

The Ralph Loop Dev Loop is a critical automation feature of OhMyOpenCode, enabling the system to transcend the limitations of single-turn AI responses. By combining stateful iteration, customizable exit promises, and tiered verification (Standard vs. Ultrawork), it provides a robust framework for autonomous software engineering tasks.