Overview
snarktank/ralph is the most-starred implementation of the ralph-loop pattern, with 21,235 GitHub stars as of August 2026 (RonanCodes docs cited 15,861 in an earlier count, indicating rapid growth). Created by Ryan Carson (Snarktank), it runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration spawns a fresh AI instance with clean context. Memory persists via git history, progress.txt, and prd.json [S01][S04].
Key Facts
- Stars: 21,235+ (GitHub, August 2026)
- Forks: 2,056
- License: MIT
- Authors: Ryan Carson (Snarktank)
- Key files:
ralph.sh(main loop script),prd.json(user stories),progress.txt(learnings),prompt.md(system prompt) - Parallel execution: Ryan Carson runs 3 parallel instances
- Architecture: Agent reads PRD -> implements one feature -> verifies -> commits -> updates PRD -> repeats
Key Contributions
Each Iteration = Fresh Context
Each iteration spawns a new AI instance with clean context. The only memory between iterations is: git history (commits from previous iterations), progress.txt (learnings and context), and prd.json (which stories are done) [S01]. This design enables handling projects that would exceed any single context window.
Small Tasks and Backpressure
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 [S01]. Ralph only works if there are feedback loops: typecheck catches type errors, tests verify behavior, CI must stay green [S01].
AGENTS.md as Inter-Iteration Memory
After each iteration, Ralph updates relevant AGENTS.md files with learnings. This is critical because AI coding tools automatically read these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions [S01].
Limitations
Context Window Burn
While each iteration gets fresh context, cumulative token cost across many iterations (often 15-50 for complex tasks) can become significant. Matt Pocock’s analysis estimates 50-100 without [S01].
Quality Depends on Criteria
If completion criteria are vague (“tests pass”), the agent may write trivial tests (assert True). Criteria must specify both quantity and quality metrics to prevent gaming [S15].
Relationship to This Vault
The vault’s orphaned ralph-converter skill was designed to bridge markdown PRDs to the snarktank/ralph prd.json format. RonanCodes/llm-wiki ronancodes-llm-wiki documentation explicitly states their LLM Wiki implementation was built using this pattern.
Implications
This vault is structurally identical to the RonanCodes implementation (Claude Code + Obsidian + markdown + raw sources + AGENTS.md schema). The snarktank/ralph approach provides a proven model for running the agent-loop pattern with external verification and fresh contexts. For llm-wiki operations specifically, the pattern enables per-source ingest with machine-verifiable lint passes.
External Links
- https://github.com/snarktank/ralph
- https://ronancodes.github.io/llm-wiki/docs/research/ralph-loop
- https://blakecrosley.com/blog/ralph-agent-architecture
Sources
- agent-loop — abstract pattern specialized by this implementation
- llm-wiki — parallel application to knowledge compilation
- ralph-loop — full technique documentation
- claude-code — the agent tool most commonly used