ralph README

The project's README from github.com/snarktank/ralph. As one markdown file: README.md.

Ralph

Ralph

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.

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

Prerequisites

Setup

Option 1: Copy to your project

Copy the ralph files into your project:

# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# Copy the prompt template for your AI tool of choice:
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # For Amp
# OR
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # For Claude Code

chmod +x scripts/ralph/ralph.sh

Option 2: Install skills globally (Amp)

Copy the skills to your Amp or Claude config for use across all projects:

For AMP

cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

For Claude Code (manual)

cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

Option 3: Use as Claude Code Marketplace

Add the Ralph marketplace to Claude Code:

/plugin marketplace add snarktank/ralph

Then install the skills:

/plugin install ralph-skills@ralph-marketplace

Available skills after installation:

Skills are automatically invoked when you ask Claude to:

Add to ~/.config/amp/settings.json:

{
  "amp.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 the PRD skill to generate a detailed requirements document:

Load the prd skill and create a PRD for [your feature description]

Answer the clarifying questions. The skill saves output to tasks/prd-[feature-name].md.

2. Convert PRD to Ralph format

Use the Ralph skill to convert the markdown PRD to JSON:

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

This creates prd.json with user stories structured for autonomous execution.

3. Run Ralph

# Using Amp (default)
./scripts/ralph/ralph.sh [max_iterations]

# Using Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

Default is 10 iterations. Use --tool amp or --tool claude to select your AI coding tool.

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 AI instances (supports --tool amp or --tool claude)
prompt.md Prompt template for Amp
CLAUDE.md Prompt template for Claude Code
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
skills/prd/ Skill for generating PRDs (works with Amp and Claude Code)
skills/ralph/ Skill for converting PRDs to JSON (works with Amp and Claude Code)
.claude-plugin/ Plugin manifest for Claude Code marketplace discovery
flowchart/ Interactive visualization of how Ralph works

Flowchart

Ralph Flowchart

View Interactive Flowchart - Click through to see each step with animations.

The flowchart/ directory contains the source code. To run locally:

cd flowchart
npm install
npm run dev

Critical Concepts

Each Iteration = Fresh Context

Each iteration spawns a new AI instance (Amp or Claude Code) with clean context. The only memory between iterations is:

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:

Too big (split these):

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.

Examples of what to add to AGENTS.md:

Feedback Loops

Ralph only works if there are feedback loops:

Browser Verification for UI Stories

Frontend stories must include "Verify in browser using dev-browser skill" in acceptance criteria. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

Stop Condition

When all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and the loop exits.

Debugging

Check current state:

# 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

Customizing the Prompt

After copying prompt.md (for Amp) or CLAUDE.md (for Claude Code) to your project, customize it for your project:

Archiving

Ralph automatically archives previous runs when you start a new feature (different branchName). Archives are saved to archive/YYYY-MM-DD-feature-name/.

References

ralph (snarktank/ralph)

Searching Database…

22K ·GitHub
Ralph
Что это такое?Ralph — это автономный цикл ИИ-агента, который снова и снова запускает инструменты для программирования с ИИ (Amp или Claude Code), пока не будут выполнены все пункты вашего PRD. Каждая итерация начинает с чистого листа — с новым экземпляром и пустым контекстом.
Это приложение, которое я устанавливаю, или оно живёт внутри моего проекта?Ни то, ни другое — это просто набор файлов: bash-цикл (ralph.sh), шаблоны промптов и скиллы, которые вы копируете в свой проект, устанавливаете глобально или добавляете через маркетплейс Claude Code.
Как мне применить его к новой фиче?Сгенерируйте PRD с помощью скилла /prd, преобразуйте его в prd.json с помощью скилла /ralph, затем запустите Ralph — по умолчанию 10 итераций, а бэкенд выбирается флагом --tool amp или --tool claude.
Что должно быть установлено, чтобы я мог его запустить?Аутентифицированный Amp CLI (по умолчанию) или Claude Code, установленный jq (brew install jq на macOS) и git-репозиторий для вашего проекта. Вот и весь список.
Могу ли я просто скормить ему большую фичу целиком?Нет — каждый пункт PRD должен быть достаточно маленьким, чтобы уложиться в одно контекстное окно; эпики вроде «добавить аутентификацию» или «сделать весь дашборд» слишком велики, и их нужно разбивать на части.
Как он справляется с задачами по фронтенду?В критериях приёмки фронтенд-задач обязательно должно быть указано «Verify in browser using dev-browser skill». Тогда Ralph использует скилл dev-browser, чтобы открыть страницу, поработать с интерфейсом и убедиться, что изменение действительно работает.
Зачем нужна настройка автоматической передачи (auto-handoff) в Amp?Добавление настройки в ~/.config/amp/settings.json включает автоматическую передачу управления при заполнении контекста, так что Ralph может продолжать работу над большими задачами, которые не помещаются в одно контекстное окно.
Что произойдёт с моим предыдущим запуском, когда я начну новую фичу?Ralph автоматически архивирует предыдущие запуски, когда вы начинаете фичу с другим branchName, сохраняя их в archive/YYYY-MM-DD-feature-name/.
Откуда взялся этот подход?Он основан на паттерне Ralph от Geoffrey Huntley, а автор репозитория написал подробную статью о том, как он сам использует Ralph в своей работе.
What are similar projects?planning-with-files, operator-memory, hyperfide, autoresearch, orca, pstack-claude, ordewell, deer-flow
Which topics is it in?context-management, agentic-workflow, agentic-coding, bash, autonomous-agents, coding-agents, claude-skills, agent-memory, workflow-automation, prompt-engineering, git, shell
Creator
snarktank
Size
4.6 MB
Stars
22K
Updated
CommitFeb 02
Age
9mo
Commits · 90 Days