awesome-copilot/cookbook/copilot-sdk/python/ralph-loop.md

RALPH-loop: Iterative Self-Referential AI Loops

Implement self-referential feedback loops where an AI agent iteratively improves work by reading its own previous output.

Runnable example: recipe/ralph_loop.py

cd python/recipe
pip install -r requirements.txt
python ralph_loop.py

What is RALPH-loop?

RALPH-loop is a development methodology for iterative AI-powered task completion. Named after the Ralph Wiggum technique, it embodies the philosophy of persistent iteration:

• One prompt, multiple iterations: The same prompt is processed repeatedly
• Self-referential feedback: The AI reads its own previous work (file changes, git history)
• Completion detection: Loop exits when a completion promise is detected in output
• Safety limits: Always include a maximum iteration count to prevent infinite loops

Example Scenario

You need to iteratively improve code until all tests pass. Instead of asking Claude to "write perfect code," you use RALPH-loop to:

1. Send the initial prompt with clear success criteria
2. Claude writes code and tests
3. Claude runs tests and sees failures
4. Loop automatically re-sends the prompt
5. Claude reads test output and previous code, fixes issues
6. Repeat until all tests pass and completion promise is output

Basic Implementation

import asyncio
from copilot import CopilotClient, MessageOptions, SessionConfig

class RalphLoop:
    """Iterative self-referential feedback loop using Copilot."""
    
    def __init__(self, max_iterations=10, completion_promise="COMPLETE"):
        self.client = CopilotClient()
        self.iteration = 0
        self.max_iterations = max_iterations
        self.completion_promise = completion_promise
        self.last_response = None

    async def run(self, initial_prompt):
        """Run the RALPH-loop until completion promise detected or max iterations reached."""
        await self.client.start()
        session = await self.client.create_session(
            SessionConfig(model="gpt-5.1-codex-mini")
        )

        try:
            while self.iteration < self.max_iterations:
                self.iteration += 1
                print(f"\n--- Iteration {self.iteration}/{self.max_iterations} ---")

                # Build prompt including previous response as context
                if self.iteration == 1:
                    prompt = initial_prompt
                else:
                    prompt = f"{initial_prompt}\n\nPrevious attempt:\n{self.last_response}\n\nContinue improving..."

                result = await session.send_and_wait(
                    MessageOptions(prompt=prompt), timeout=300
                )

                self.last_response = result.data.content if result else ""
                print(f"Response ({len(self.last_response)} chars)")

                # Check for completion promise
                if self.completion_promise in self.last_response:
                    print(f"✓ Completion promise detected: {self.completion_promise}")
                    return self.last_response

                print(f"Continuing to iteration {self.iteration + 1}...")

            raise RuntimeError(
                f"Max iterations ({self.max_iterations}) reached without completion promise"
            )
        finally:
            await session.destroy()
            await self.client.stop()

# Usage
async def main():
    loop = RalphLoop(5, "COMPLETE")
    result = await loop.run("Your task here")
    print(result)

asyncio.run(main())

With File Persistence

For tasks involving code generation, persist state to files so the AI can see changes:

import asyncio
from pathlib import Path
from copilot import CopilotClient, MessageOptions, SessionConfig

class PersistentRalphLoop:
    """RALPH-loop with file-based state persistence."""
    
    def __init__(self, work_dir, max_iterations=10):
        self.client = CopilotClient()
        self.work_dir = Path(work_dir)
        self.work_dir.mkdir(parents=True, exist_ok=True)
        self.iteration = 0
        self.max_iterations = max_iterations

    async def run(self, initial_prompt):
        """Run the loop with persistent state."""
        await self.client.start()
        session = await self.client.create_session(
            SessionConfig(model="gpt-5.1-codex-mini")
        )

        try:
            # Store initial prompt
            (self.work_dir / "prompt.md").write_text(initial_prompt)

            while self.iteration < self.max_iterations:
                self.iteration += 1
                print(f"\n--- Iteration {self.iteration} ---")

                # Build context from previous outputs
                context = initial_prompt
                prev_output = self.work_dir / f"output-{self.iteration - 1}.txt"
                if prev_output.exists():
                    context += f"\n\nPrevious iteration:\n{prev_output.read_text()}"

                result = await session.send_and_wait(
                    MessageOptions(prompt=context), timeout=300
                )
                response = result.data.content if result else ""

                # Persist output
                output_file = self.work_dir / f"output-{self.iteration}.txt"
                output_file.write_text(response)

                if "COMPLETE" in response:
                    return response

            raise RuntimeError("Max iterations reached")
        finally:
            await session.destroy()
            await self.client.stop()

Best Practices

1. Write clear completion criteria: Include exactly what "done" looks like
2. Use output markers: Include <promise>COMPLETE</promise> or similar in completion condition
3. Always set max iterations: Prevents infinite loops on impossible tasks
4. Persist state: Save files so AI can see what changed between iterations
5. Include context: Feed previous iteration output back as context
6. Monitor progress: Log each iteration to track what's happening

Example: Iterative Code Generation

prompt = """Write a function that:
1. Parses CSV data
2. Validates required fields
3. Returns parsed records or error
4. Has unit tests
5. Output <promise>COMPLETE</promise> when done"""

async def main():
    loop = RalphLoop(10, "COMPLETE")
    result = await loop.run(prompt)

asyncio.run(main())

Handling Failures

try:
    result = await loop.run(prompt)
    print("Task completed successfully!")
except RuntimeError as e:
    print(f"Task failed: {e}")
    if loop.last_response:
        print(f"\nLast attempt:\n{loop.last_response}")

When to Use RALPH-loop

Good for:

• Code generation with automatic verification (tests, linters)
• Tasks with clear success criteria
• Iterative refinement where each attempt learns from previous failures
• Unattended long-running improvements

Not good for:

• Tasks requiring human judgment or design input
• One-shot operations
• Tasks with vague success criteria
• Real-time interactive debugging