____ _____ __  __ ___ _   _ ___    ____ _     ___   _____ _____ __  __ ____  _      _  _____ _____ ____
 / ___| ____|  \/  |_ _| \ | |_ _|  / ___| |   |_ _| |_   _| ____|  \/  |  _ \| |    / \|_   _| ____/ ___|
| |  _|  _| | |\/| || ||  \| || |  | |   | |    | |    | | |  _| | |\/| | |_) | |   / _ \ | | |  _| \___ \
| |_| | |___| |  | || || |\  || |  | |___| |___ | |    | | | |___| |  | |  __/| |__/ ___ \| | | |___ ___) |
 \____|_____|_|  |_|___|_| \_|___|   \____|_____|___|   |_| |_____|_|  |_|_|   |_____/_/   \_\_||_____|____/
Ralph Wiggum Pattern
Home GitHub

Ralph Wiggum Pattern

⎿ Implementation of the iterative, self-referential AI development loop

# What is Ralph?
"I'm doing agentic engineering!" - Ralph
Ralph Wiggum Agent Loop

Figure 1: The Autonomous Feedback Loop

Ralph is an autonomous AI agent loop that runs Gemini CLI repeatedly until all PRD items are complete. Each iteration is a fresh Gemini instance with clean context. Memory persists via git history, progress.txt, and prd.json.

Based on Geoffrey Huntley's Ralph pattern.

# Prerequisites
  • • Gemini CLI installed and authenticated
  • • jq installed (brew install jq on macOS)
  • • A git repository for your project
# Setup

Option 1: Install as a Skill

Install the skill directly into your project or globally using the Gemini Templates CLI.

$ npx gemini-cli-templates --skill development/ralph-wiggum

Option 2: Manual Setup

Copy the ralph files into your project:

# From your project root
mkdir -p scripts/ralph
cp -r cli-tool/components/skills/development/ralph-wiggum/scripts/* scripts/ralph/
chmod +x scripts/ralph/ralph.sh

Configure Auto-Handoff (Recommended)

Add to ~/.gemini/settings.json:

{
  "gemini.experimental.autoHandoff": { "context": 90 }
}

This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.

# Workflow
1

Create a PRD

Use a PRD skill or manually create a detailed requirements document. Save it to tasks/prd-[feature-name].md.

2

Convert PRD to Ralph Format

You need a prd.json file with user stories structured for autonomous execution.

{
  "feature": "My Feature",
  "branchName": "feat/my-feature",
  "userStories": [
    {
      "id": "1",
      "title": "Setup project structure",
      "passes": false
    }
  ]
}
3

Run Ralph

$ ./scripts/ralph/ralph.sh 10
Ralph will:
  1. Create a feature branch (from PRD branchName)
  2. Pick the highest priority story where passes: false
  3. Implement that single story
  4. Run quality checks (typecheck, tests)
  5. Commit if checks pass
  6. Update prd.json to mark story as passes: true
  7. Append learnings to progress.txt
  8. Repeat until all stories pass or max iterations reached
# Key Files
File Purpose
ralph.sh The bash loop that spawns fresh Gemini instances
prompt.md Instructions given to each Gemini instance
prd.json User stories with passes status (the task list)
prd.json.example Example PRD format for reference
progress.txt Append-only learnings for future iterations
# Critical Concepts

Each Iteration = Fresh Context

Each iteration spawns a new Gemini instance with clean context. The only memory between iterations is:

  • Git history (commits from previous iterations)
  • progress.txt (learnings and context)
  • prd.json (which stories are done)

Small Tasks

Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.

✅ Right-sized stories:
  • Add a database column and migration
  • Add a UI component to an existing page
  • Update a server action with new logic
  • Add a filter dropdown to a list
❌ Too big (split these):
  • "Build the entire dashboard"
  • "Add authentication"
  • "Refactor the API"

AGENTS.md Updates Are Critical

After each iteration, Ralph updates the relevant AGENTS.md files with learnings. This is key because Gemini automatically reads these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions.

Feedback Loops

Ralph only works if there are feedback loops:

  • Typecheck catches type errors
  • Tests verify behavior
  • CI must stay green (broken code compounds across iterations)
# Debugging
# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# See learnings from previous iterations
cat progress.txt

# Check git history
git log --oneline -10
# Learn More

Original technique: https://ghuntley.com/ralph/
Upstream Repository: https://github.com/snarktank/ralph