awesome-copilot/cookbook/copilot-sdk/go/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.go

cd go
go run recipe/ralph-loop.go

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 Copilot to "write perfect code," you use RALPH-loop to:

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

Basic Implementation

package main

import (
	"context"
	"fmt"
	"log"
	"strings"

	copilot "github.com/github/copilot-sdk/go"
)

type RalphLoop struct {
	client            *copilot.Client
	iteration         int
	maxIterations     int
	completionPromise string
	LastResponse      string
}

func NewRalphLoop(maxIterations int, completionPromise string) *RalphLoop {
	return &RalphLoop{
		client:            copilot.NewClient(nil),
		maxIterations:     maxIterations,
		completionPromise: completionPromise,
	}
}

func (r *RalphLoop) Run(ctx context.Context, initialPrompt string) (string, error) {
	if err := r.client.Start(ctx); err != nil {
		return "", err
	}
	defer r.client.Stop()

	session, err := r.client.CreateSession(ctx, &copilot.SessionConfig{
		Model: "gpt-5.1-codex-mini",
	})
	if err != nil {
		return "", err
	}
	defer session.Destroy()

	for r.iteration < r.maxIterations {
		r.iteration++
		fmt.Printf("\n--- Iteration %d/%d ---\n", r.iteration, r.maxIterations)

		prompt := r.buildIterationPrompt(initialPrompt)

		result, err := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: prompt})
		if err != nil {
			return "", err
		}

		if result != nil && result.Data.Content != nil {
			r.LastResponse = *result.Data.Content
		}

		if strings.Contains(r.LastResponse, r.completionPromise) {
			fmt.Printf("✓ Completion promise detected: %s\n", r.completionPromise)
			return r.LastResponse, nil
		}
	}

	return "", fmt.Errorf("max iterations (%d) reached without completion promise",
		r.maxIterations)
}

// Usage
func main() {
	ctx := context.Background()
	loop := NewRalphLoop(5, "COMPLETE")
	result, err := loop.Run(ctx, "Your task here")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result)
}

With File Persistence

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

package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"
	"strings"

	copilot "github.com/github/copilot-sdk/go"
)

type PersistentRalphLoop struct {
	client        *copilot.Client
	workDir       string
	iteration     int
	maxIterations int
}

func NewPersistentRalphLoop(workDir string, maxIterations int) *PersistentRalphLoop {
	os.MkdirAll(workDir, 0755)
	return &PersistentRalphLoop{
		client:        copilot.NewClient(nil),
		workDir:       workDir,
		maxIterations: maxIterations,
	}
}

func (p *PersistentRalphLoop) Run(ctx context.Context, initialPrompt string) (string, error) {
	if err := p.client.Start(ctx); err != nil {
		return "", err
	}
	defer p.client.Stop()

	os.WriteFile(filepath.Join(p.workDir, "prompt.md"), []byte(initialPrompt), 0644)

	session, err := p.client.CreateSession(ctx, &copilot.SessionConfig{
		Model: "gpt-5.1-codex-mini",
	})
	if err != nil {
		return "", err
	}
	defer session.Destroy()

	for p.iteration < p.maxIterations {
		p.iteration++

		prompt := initialPrompt
		prevFile := filepath.Join(p.workDir, fmt.Sprintf("output-%d.txt", p.iteration-1))
		if data, err := os.ReadFile(prevFile); err == nil {
			prompt = fmt.Sprintf("%s\n\nPrevious iteration:\n%s", initialPrompt, string(data))
		}

		result, err := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: prompt})
		if err != nil {
			return "", err
		}

		response := ""
		if result != nil && result.Data.Content != nil {
			response = *result.Data.Content
		}

		os.WriteFile(filepath.Join(p.workDir, fmt.Sprintf("output-%d.txt", p.iteration)),
			[]byte(response), 0644)

		if strings.Contains(response, "COMPLETE") {
			return response, nil
		}
	}

	return "", fmt.Errorf("max iterations reached")
}

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`

loop := NewRalphLoop(10, "COMPLETE")
result, err := loop.Run(context.Background(), prompt)

Handling Failures

ctx := context.Background()
loop := NewRalphLoop(5, "COMPLETE")
result, err := loop.Run(ctx, prompt)
if err != nil {
	log.Printf("Task failed: %v", err)
	log.Printf("Last attempt: %s", loop.LastResponse)
}

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