Ralph Loop (Ralph Wiggum Loop)

A robust, self-correcting workflow for AI agents.

Overview

The Ralph Loop implements a self-correcting mechanism that utilizes an AI agent's ability to observe its own outputs and errors across multiple runs to complete complex tasks. This pattern is particularly useful for tasks that require multiple iterations to achieve full compliance with success criteria.

Core Logic

1. Comprehensive Prompting: Use a PROMPT.md with explicit SUCCESS CRITERIA and a COMPLETION PROMISE.
2. Iterative Execution: The agent runs in a loop.
3. Self-Correction: If the agent exits without outputting the completion promise, it restarts and observes the current filesystem state, logs, and previous errors to continue.

Prompt Structure

To maximize effectiveness, your PROMPT.md should include:

• TASK: Detailed objective description.
• SUCCESS CRITERIA: Measurable conditions for completion.
• PROCESS: Recommended steps for the agent.
• COMPLETION PROMISE: A specific string (e.g., <promise>COMPLETE</promise>) that the agent MUST output only when all criteria are met.

Usage

Manual Helper Script

You can run a loop manually using the provided bash script:

/bin/bash scripts/ralph-loop.sh --prompt PROMPT.md --command "claude-code" --promise "COMPLETE" --max-iterations 20

Skill Integration

When deployed as a skill in Antigravity or Gemini CLI, the agent will automatically utilize this pattern when invoked.

Repository Structure

• SKILL.md: Metadata and skill definition.
• scripts/: Contains ralph-loop.sh implementation.
• examples/: Template prompts for reference.