Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/snarktank/ralph/llms.txt

Use this file to discover all available pages before exploring further.

​
How Ralph Works

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 spawns a fresh AI instance with clean context.

​
The Ralph Loop

1

Initialize

Ralph starts by reading the prd.json file and checking the current branch matches the PRD’s branchName.
2

Select Task

The agent picks the highest priority user story where passes: false.
3

Implement

The AI implements that single user story, making code changes across the necessary files.
4

Quality Checks

The agent runs quality checks configured for your project:
  • Type checking
  • Linting
  • Unit tests
  • Integration tests
5

Commit

If all checks pass, the agent commits ALL changes with the message:
feat: [Story ID] - [Story Title]
6

Update State

The agent updates prd.json to mark the story as passes: true and appends learnings to progress.txt.
7

Repeat or Complete

If all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and exits. Otherwise, the loop spawns a new fresh AI instance for the next iteration.

​
Execution Flow Diagram

​
The Bash Script

The ralph.sh script is the orchestrator that manages the loop: 
# Run with Amp (default)
./ralph.sh [max_iterations]

# Run with Claude Code
./ralph.sh --tool claude [max_iterations]
Default is 10 iterations. The script will exit early if all tasks complete before reaching the maximum.

​
What the Script Does

  1. Parses arguments - Determines which AI tool to use (Amp or Claude Code) and max iterations
  2. Archives previous runs - If the branch name changed, archives old prd.json and progress.txt
  3. Spawns AI instances - For each iteration:
    • Pipes the prompt template (prompt.md or CLAUDE.md) to the AI tool
    • Captures the output
    • Checks for the <promise>COMPLETE</promise> signal
    • Continues to next iteration if work remains

​
Key Script Features

# Each iteration spawns a fresh AI instance
if [[ "$TOOL" == "amp" ]]; then
  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1)
else
  OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1)
fi

# Check for completion
if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
  echo "Ralph completed all tasks!"
  exit 0
fi
The --dangerously-allow-all and --dangerously-skip-permissions flags allow the AI to perform file operations and run commands autonomously. Only use Ralph on projects with version control.

​
Prompt Templates

Ralph uses different prompt templates for each AI tool:
  • prompt.md - Instructions for Amp instances
  • CLAUDE.md - Instructions for Claude Code instances
These templates tell each fresh AI instance:
  • Where to find the PRD and progress log
  • How to select the next task
  • What quality checks to run
  • How to format progress reports
  • When to signal completion
Customize these templates for your project by adding:
  • Project-specific quality check commands
  • Codebase conventions
  • Common gotchas for your stack
  • Required environment variables

​
Archiving

When you start a new feature (different branchName in prd.json), Ralph automatically archives the previous run: 
archive/
  2025-03-11-user-authentication/
    prd.json
    progress.txt
  2025-03-12-dashboard-refactor/
    prd.json
    progress.txt
This preserves the history of each Ralph run while keeping your workspace clean.

​
Interactive Flowchart

For a visual, step-by-step walkthrough of how Ralph works, check out the interactive flowchart: The flowchart includes animations and click-through explanations of each step in the loop.

Build docs developers (and LLMs) love

Get started for freeTalk to us