Ralph Wiggum Explanation, Example Code, and Demo
A tutorial by Matt Pocock. Featured in the OTF curated resource library.
The Ralph Architecture
Ralph follows a classic agent architecture: perceive → plan → act → verify → submit.
Perceive: Ralph reads the task description, referenced files, project structure, and configuration (ralph.yml + any AGENTS.md). It builds a mental model of the task and the codebase.
Plan: Before writing code, Ralph creates an execution plan: which files to modify, what tests to write, what the expected outcome should be. This plan is visible in the PR description.
Act: Ralph writes code following the plan. It uses the project's coding conventions, references existing patterns, and generates new code that fits the codebase style.
Verify: After making changes, Ralph runs the test suite, type checker, and linter. If anything fails, it iterates — fixing issues until all checks pass.
Submit: The final output is a PR with clean commits, a detailed description, test results, and an explanation of the approach taken.
How Ralph Thinks
The agent's decision-making process for a typical bug fix.
Read the issue
Ralph parses the issue title, description, labels, and any referenced files. It identifies: what's broken, where the bug likely lives, and what the expected behavior should be.
Explore the codebase
Ralph reads relevant files, traces the code path from the reported symptom to potential causes, and identifies the root cause. This mirrors how a human developer investigates a bug.
Plan the fix
Ralph outlines: what to change, why, what tests to add, and what could go wrong. This plan is recorded and included in the PR description.
Implement and verify
Ralph makes the changes, writes tests, runs the full test suite, and iterates if needed. Only when all checks pass does it submit the PR.
Example Configurations
Minimal configuration (small projects):
Just a ralph.yml with test commands and allowed paths. Ralph infers conventions from the existing codebase.
Standard configuration (team projects):
ralph.yml + AGENTS.md with coding conventions, component patterns, and explicit do's and don'ts. This produces consistent output that matches the team's style.
Enterprise configuration (large codebases):
ralph.yml + AGENTS.md + scoped configuration files in subdirectories. Different rules for frontend vs backend vs infrastructure. File boundary restrictions prevent cross-domain changes.
The configuration complexity should match your codebase complexity. Most teams start minimal and add rules as they identify patterns where Ralph needs guidance.
Live Demo Walkthrough
Here's what happens when Ralph processes a real task — a bug fix for a pagination issue:
0:00 — Issue labeled 'ralph': 'Pagination on the Explore page doesn't pass the page parameter to the API call.'
0:30 — Ralph reads the issue, identifies ExplorePage.tsx and api.ts as relevant files.
1:00 — Ralph reads both files, traces the data flow from the page component through the hook to the API call. Identifies that the page parameter exists in state but isn't passed to fetchDirectoryData().
2:00 — Ralph creates a plan: modify the API function to accept a page parameter, update the hook to pass it, add a test for pagination.
3:00 — Ralph implements the changes across both files, writes a test that verifies page parameter is passed correctly.
4:00 — Tests run and pass. Ralph creates a PR with: a descriptive title, explanation of the root cause, the fix approach, and test results.
Total time: ~4 minutes for a task that would take a human developer 15-30 minutes including context switching.
