Ralph (snarktank) — Summary

Ralph by snarktank is the canonical reference implementation of the "Ralph pattern" — an autonomous AI agent loop that spawns a fresh AI coding tool (Amp or Claude Code) per iteration, each time picking the highest-priority incomplete story from prd.json, implementing it, running quality checks, and committing if checks pass. Memory across iterations persists only through git history, progress.txt (append-only learnings), and prd.json (task completion state). The framework ships two SKILL.md files (a PRD generator and a JSON converter), a bash loop script (ralph.sh), and a .claude-plugin manifest for Claude Code marketplace discovery. At 19,612 stars it is the most widely forked Ralph variant in the ecosystem. Compared to seeds, Ralph most closely resembles spec-driver's sequential execution model but is philosophically a pure execution loop rather than a specification framework: spec-driver manages the spec lifecycle, while Ralph assumes a prd.json already exists and focuses entirely on the iterate-commit-repeat loop with fresh-context isolation as its core mechanism.

Ralph (snarktank) — Overview

Origin

Ralph was created by snarktank (Ryan Carson, as referenced in the README: "Read my in-depth article on how I use Ralph"). The implementation credits "Geoffrey Huntley's Ralph pattern" (ghuntley.com/ralph/) and the character Ralph Wiggum from The Simpsons. The repository has 19,612 stars and 4 contributors. Last pushed 2026-02-02.

Philosophy

From the README:

"Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, progress.txt, and prd.json."

Critical Concepts (verbatim from README)

Each Iteration = Fresh Context:

"Each iteration spawns a new AI instance (Amp or Claude Code) 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."

AGENTS.md Updates Are Critical:

"After each iteration, Ralph updates the relevant AGENTS.md files with learnings. This is key because AI coding tools automatically read 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."

Design Opinions

• Context freshness is more valuable than context continuity for implementation tasks
• Task granularity is the primary success factor: stories too large produce poor code
• Git history is the right persistence mechanism for implementation work
• Learnings should be written to AGENTS.md files (not just progress.txt) so future AI tool invocations benefit automatically

Ralph (snarktank) — Architecture

Distribution & Install

• Distribution type: bash-script-bundle + skill-pack (Claude Code marketplace)
• Primary install: Copy ralph.sh to scripts/ralph/ in project
• Skill install: cp -r skills/ ~/.config/amp/skills/ or ~/.claude/skills/
• Marketplace install: /plugin marketplace add snarktank/ralph then /plugin install ralph-skills@ralph-marketplace
• License: MIT
• Required runtime: bash, jq, Amp CLI or Claude Code CLI

Directory Tree (repo)

ralph/
├── ralph.sh              # Main bash loop script
├── prompt.md             # Prompt template for Amp
├── CLAUDE.md             # Prompt template for Claude Code
├── prd.json.example      # Example PRD format
├── progress.txt          # (generated) Append-only learnings
├── skills/
│   ├── prd/
│   │   └── SKILL.md      # PRD generator skill
│   └── ralph/
│       └── SKILL.md      # PRD→JSON converter skill
├── .claude-plugin/       # Plugin manifest for Claude Code marketplace
├── flowchart/            # Interactive visualization (npm/React)
└── AGENTS.md             # Agent instructions

Loop Mechanics

ralph.sh [max_iterations]
  # Default: 10 iterations
  # --tool amp|claude  (AI tool selection)
  # Steps per iteration:
  # 1. Create/check out feature branch from PRD branchName
  # 2. Pick highest priority story where passes=false
  # 3. Spawn fresh AI instance with CLAUDE.md or prompt.md
  # 4. AI implements story
  # 5. Run quality checks (typecheck, lint, test)
  # 6. If checks pass: commit all changes
  # 7. Update prd.json: set passes=true for completed story
  # 8. Append learnings to progress.txt
  # 9. Repeat until all passes=true or max_iterations

PRD Format (prd.json)

{
  "project": "Project Name",
  "branchName": "ralph/feature-name",
  "description": "Feature description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Story title",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Target AI Tools

• Amp (default, via ampcode.com)
• Claude Code (via --tool claude)
• Amp autoHandoff is recommended for large stories (context fill management)

Claude Code Marketplace

.claude-plugin/ contains the marketplace manifest. Available skills after installation:

• /prd — Generate PRDs
• /ralph — Convert PRDs to prd.json format

Ralph (snarktank) — Components

Scripts

Skills (SKILL.md format)

Prompt Templates

Runtime Files (generated per project)

Claude Code Plugin

.claude-plugin/ — marketplace manifest for snarktank/ralph

Flowchart

flowchart/ — React/npm interactive visualization hosted at snarktank.github.io/ralph/

No Hooks, No Commands, No MCP

Ralph is a bash script that invokes AI tools as external processes. It does not use Claude Code hook events, slash commands, or MCP servers.

Ralph (snarktank) — Uniqueness & Positioning

Differs from Seeds

Ralph (snarktank) is closest to spec-driver in its sequential, story-by-story execution model — both drive an agent through a prioritized task list. However, Ralph's core mechanism is fresh-context isolation per iteration (a new AI process for every story), whereas spec-driver manages a persistent skill chain in a continuous session. Ralph has no spec lifecycle management — it assumes prd.json already exists and focuses entirely on the iterate-commit-repeat loop. Unlike any seed framework, Ralph explicitly supports two different AI tools (Amp and Claude Code) and is the only framework here designed primarily around Amp. The AGENTS.md update instruction — asking the agent to update per-directory pattern files after each commit so future AI tool invocations benefit — is a distinctive memory mechanism not present in any seed. Compared to claude-flow's elaborate SQLite/vector memory, Ralph's memory is deliberately minimal: three files, all human-readable, all in the git repo.

Positioning

Ralph (snarktank) is the reference implementation of the Geoffrey Huntley Ralph pattern and the most widely-starred variant. It is designed for simplicity and auditability: minimal dependencies (bash + jq), no installation, copy-paste deployment. The interactive flowchart visualization (snarktank.github.io/ralph/) is a distinctive community asset.

Observable Failure Modes

• No retry on quality check failure: If a story fails checks, Ralph ends the iteration and starts a fresh one. If the same story repeatedly fails, it simply consumes iterations without progress.
• max_iterations cap: Default 10 is very low for complex projects; users must increase it.
• Single-tool per run: Cannot route different stories to different AI tools within one ralph.sh invocation.
• No task decomposition: Stories that are too large silently produce poor code; the PRD skill's sizing guidance is advisory, not enforced.
• Amp-first: Uses Amp by default; Claude Code is secondary. Users on Claude Max must remember --tool claude.

Explicit Antipatterns (from skill files)

• Stories that span more than one context window
• Tasks described in more than 2-3 sentences (too big to implement in one iteration)
• Implementing features out of dependency order in prd.json