An open-source AI coding automation framework published by Ryan Carson (snarktank). You write a PRD (product requirements document) and convert it into structured JSON; from there, a bash script called ralph.sh repeatedly launches an AI coding tool such as Amp or Claude Code and has it implement one incomplete user story at a time. If type checks and tests pass, the change is committed, the learnings are recorded, and the next iteration begins — and this cycle runs automatically until every story is complete or the iteration limit is reached. It is a practical implementation of the “Ralph pattern” proposed by engineer Geoffrey Huntley, whose original form was the plain infinite loop while :; do cat PROMPT.md | claude-code; done. Licensed under MIT.
Key Features
- An autonomous loop driven by a PRD: You write your requirements as a PRD and use the bundled skill to convert it into
prd.json, a JSON file holding abranchNameand an array of user stories. Each story carries acceptance criteria and apassesflag, and the loop picks the highest-priority story wherepassesis stillfalse - A clean context on every launch: Each iteration starts the AI tool as a fresh process, so irrelevant context and misunderstandings accumulated in earlier attempts are not carried over. Only three things persist: Git history,
progress.txt(an append-only log of learnings), and the completion state inprd.json - Commits only when quality checks pass: After implementation, type checks and tests run, and a commit is made — and the story marked
passes: true— only if they succeed. The design keeps broken code from piling up across iterations - Learnings written back to AGENTS.md: Discovered conventions and pitfalls are appended to
AGENTS.md. Many AI coding tools read this file automatically, so it improves accuracy from the next iteration onward - Supports Amp and Claude Code: Amp CLI is the default; adding
--tool clauderuns the loop with Claude Code. For Claude Code, installation via the plugin marketplace (/plugin marketplace add snarktank/ralph) is also supported - Browser verification for front-end work: For UI stories, including browser-based verification in the acceptance criteria lets the loop catch visual breakage
Pricing
| Plan | Price | Highlights |
|---|---|---|
| Ralph itself (OSS) | $0 (MIT license) | ralph.sh, prompt templates, and the PRD generation skills |
| The AI tool you run it with | Follows that tool’s own pricing | Amp CLI or Claude Code usage is billed separately |
Pricing is as of August 2026. Please check the official repository for the latest information.
Ralph itself is a bash script and a set of prompts published on GitHub, so the framework carries no charge of its own. The real cost shows up as token consumption by the Amp or Claude Code sessions the loop invokes. Usage scales roughly with the number of iterations and the size of the codebase, so capping the maximum iteration count via the ralph.sh argument (10 by default) is the safe way to operate it.
Pros & Cons
✅ Pros
- Once requirements are split into stories, implementation, testing, and committing proceed without a person watching over each step
- Because every launch starts from a clean context, the context degradation and entrenched misunderstandings common in long conversations are less likely
- Only work that passes the quality checks is committed, so the Git history becomes a chain of working states that is easy to review or roll back
- The thin structure — just bash scripts and Markdown — makes it easy to read the internals and adapt it to your own project
- It builds on existing AI coding tools such as Amp and Claude Code, so you can adopt it without adding a new subscription
⚠️ Cons
- Each story must be broken down until it fits in a single context window; coarse requests like “build the whole dashboard” tend to fail
- In projects without feedback loops such as type checks, tests, and CI, mistakes go undetected and accumulate across iterations
- Ralph has no safety mechanism of its own — designing the quality gates is the user’s responsibility
- Human review of the generated code is assumed. It is not intended for shipping to production unattended
- The author of the Ralph pattern is skeptical about applying it to large existing legacy codebases, positioning it as a greenfield technique
- Getting started requires a Git repository,
jq, and an authenticated environment for a supported AI tool, which is a hurdle for those unfamiliar with the CLI
Comparison with Similar Services
| Criteria | Ralph | Claude Code (standalone) | OpenHands | Devin |
|---|---|---|---|---|
| Delivery | OSS (bash script) | CLI tool | OSS (agent platform) | Commercial SaaS |
| Unit of work | One PRD story at a time | Each instruction in a conversation | Per task | Per task |
| Autonomous loop | Yes (repeats until done) | Mostly conversational | Yes | Yes |
| Carried-over state | Git history, progress.txt, prd.json | Context within the session | Agent state management | Managed by the service |
| Execution environment | Your machine, your repository | Your machine | Local / container / cloud | Cloud |
| Price | Free (AI tool usage billed separately) | Follows Claude’s plans | Free (LLM API costs separate) | Paid (check for details) |
Who Is It For
- Developers who already break requirements into fine-grained user stories and want to automate the implementation that follows
- People whose projects already have type checks and tests in place, so AI output can be verified mechanically
- Solo developers and small teams who want to clear a batch of prototype work or self-contained feature additions
- Anyone who wants to move AI coding tools from “something you instruct in chat each time” to “a mechanism you can leave running”
- People who prefer to avoid black-box automation and want to read the script before relying on it
Summary
Ralph is a thin framework that gives an AI coding tool a single loop: implement one item, verify it, and commit if it passes. The machinery is only a few hundred lines of bash plus prompts, but restarting with a clean context and committing only after the quality gates makes it resilient during long autonomous runs. Whether it pays off depends on preparation on the project side — the granularity of your stories and the strength of your tests. A good starting point is to write a small feature addition as a PRD, cap the maximum iterations, and observe how it behaves.