Ralph Wiggum - Agentic Coding Loop

A simple PowerShell implementation of the Ralph Wiggum technique for autonomous AI coding agents.

What is Ralph Wiggum?

Named after the Simpsons character known for naive persistence, Ralph Wiggum runs AI coding agents in automated loops. Each iteration:

1. Starts with a fresh context (no accumulated confusion)
2. Reads a specification and picks the next task
3. Implements it and commits the code
4. Updates a progress file and exits

The next iteration reads the same spec, sees what's been done via git history and progress file, and continues.

The key insight: Progress persists in files and git history, not in the context window. This avoids "context rot" where LLM performance degrades as input length increases.

Prerequisites

• GitHub Copilot CLI - See GitHub CLI documentation
• PowerShell - Works cross-platform with PowerShell Core (Windows, macOS, Linux)
• Git - For version control and progress tracking

Quick Start

1. Copy the template to create a new scenario:

   Copy-Item -Recurse _template my-scenario

2. Edit your scenario files:

   • my-scenario/plan.json - Define your PRDs (tasks) with dependencies
   • my-scenario/prompt.txt - Customize instructions for the AI
   • my-scenario/progress.md - Progress tracking (auto-updated)

3. Run the loop:

.\run-ralph.ps1 -Scenario my-scenario

Scenario Structure

Each scenario lives in its own folder:

my-scenario/
├── plan.json      # PRDs with tasks, acceptance criteria, dependencies
├── prompt.txt     # Instructions for the AI agent
└── progress.md    # Progress tracking (updated by agent)

plan.json

Defines your implementation plan as PRDs (Product Requirements Documents):

{
  "scenario": "my-scenario",
  "description": "What this scenario accomplishes",
  "prds": [
    {
      "id": "PRD-001",
      "title": "First Task",
      "description": "What needs to be implemented",
      "status": "not-started",
      "acceptance_criteria": ["Criterion 1", "Criterion 2"],
      "dependencies": []
    },
    {
      "id": "PRD-002",
      "title": "Second Task",
      "status": "not-started",
      "dependencies": ["PRD-001"]
    }
  ]
}

The script respects dependencies—PRD-002 won't start until PRD-001 is complete.

Usage

# Basic usage
.\run-ralph.ps1 -Scenario my-scenario

# Limit iterations
.\run-ralph.ps1 -Scenario my-scenario -Iterations 10

# Use a different model
.\run-ralph.ps1 -Scenario my-scenario -Model "claude-opus-4.5"

# Yolo mode - allow all tools without prompting (dangerous ops still blocked)
.\run-ralph.ps1 -Scenario my-scenario -Yolo

Yolo Mode

The -Yolo flag enables --yolo which allows all tools to run without confirmation prompts. This is useful for:

• Sandboxed environments (Docker) where the agent is already isolated
• HITL mode where you're watching each iteration
• Trusted scenarios where permission prompts add friction

Safety: Even with -Yolo, dangerous operations are still blocked via the deny list (git push, rm, file deletion, etc.). To fully disable safety rails, edit the $DeniedTools array in the script.

Available Models

• claude-sonnet-4.5 (default), claude-haiku-4.5, claude-opus-4.5, claude-sonnet-4
• gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.2, gpt-5.1, gpt-5
• gpt-5.1-codex-mini, gpt-5-mini, gpt-4.1
• gemini-3-pro-preview

How It Works

1. Context Optimization: Only the next eligible PRD is loaded (not the entire plan), minimizing context size
2. Dependency Checking: PRDs are only worked on when their dependencies are complete
3. Completion Detection: The agent signals completion with <promise>COMPLETE</promise>
4. Safe Tool Permissions: File writes and safe git operations are allowed; dangerous operations (push, delete, reset --hard) are denied

Best Practices

1. Write clear PRDs with specific acceptance criteria
2. Keep tasks small - each PRD should be completable in one context window
3. Use dependencies to enforce ordering when tasks build on each other
4. Review commits after the loop completes
5. Start with fewer iterations (5-10) until you tune your prompts

Examples

See _examples/ for working scenarios you can copy and adapt.

Credits

The Ralph Wiggum technique was developed and documented by Geoffrey Huntley.

License

MIT License - See LICENSE