Skip to main content

​
Overview

The ralph.sh script is the core orchestrator 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.

​
Usage

./ralph.sh [--tool amp|claude] [max_iterations]

​
Basic Examples

./ralph.sh

​
Command-Line Options

​
--tool
string
default:"amp"
Selects which AI coding tool to use for iterations.Valid values:
  • amp - Uses the Amp CLI (default)
  • claude - Uses Claude Code
Syntax options:
  • --tool amp
  • --tool=amp
The script will exit with code 1 if an invalid tool name is provided.
​
max_iterations
integer
default:"10"
Maximum number of iterations Ralph will run before stopping.Specified as a positional numeric argument. If all tasks complete before reaching the maximum, Ralph exits early with code 0.
# Run up to 25 iterations
./ralph.sh 25

# With tool selection
./ralph.sh --tool claude 30

​
How It Works

​
Initialization

When ralph.sh starts, it:
  1. Parses command-line arguments to determine tool and max iterations
  2. Validates the tool choice (must be ‘amp’ or ‘claude’)
  3. Checks for branch changes and archives previous runs if needed
  4. Initializes progress tracking in progress.txt

​
Archive Management

Ralph automatically archives previous runs when the branch name changes: 
# Archives are saved to:
archive/YYYY-MM-DD-feature-name/
  ├── prd.json
  └── progress.txt
The branch name is read from prd.json and tracked in .last-branch. When a new branch is detected, the previous run’s files are copied to the archive directory before starting the new run.

​
Iteration Loop

Each iteration:
  1. Displays iteration number and selected tool
  2. Spawns a fresh AI instance:
    • Amp: Runs cat prompt.md | amp --dangerously-allow-all
    • Claude Code: Runs claude --dangerously-skip-permissions --print < CLAUDE.md
  3. Captures all output (stdout and stderr)
  4. Checks for completion signal (<promise>COMPLETE</promise>)
  5. Continues or exits based on completion status

​
Completion Detection

The script searches each iteration’s output for the completion signal: 
<promise>COMPLETE</promise>
When detected, Ralph exits with code 0 and reports which iteration completed the work.

​
Exit Codes

​
0
success
All tasks completed successfully before reaching max iterations.Ralph detected the <promise>COMPLETE</promise> signal in the output.
​
1
failure
One of the following occurred:
  • Invalid tool name provided (not ‘amp’ or ‘claude’)
  • Reached max iterations without completing all tasks
  • Check progress.txt for the current status

​
File Structure

Ralph interacts with several files in its script directory:
FilePurpose
prd.jsonTask list with user stories and completion status
progress.txtAppend-only log of learnings and context
prompt.mdPrompt template fed to Amp
CLAUDE.mdPrompt template fed to Claude Code
.last-branchTracks the last branch name for archive detection
archive/Directory containing archived runs

​
Environment Variables

The script uses these internal variables: 
SCRIPT_DIR      # Absolute path to the script directory
TOOL            # Selected AI tool (amp or claude)
MAX_ITERATIONS  # Maximum iteration count
PRD_FILE        # Path to prd.json
PROGRESS_FILE   # Path to progress.txt
ARCHIVE_DIR     # Path to archive directory
LAST_BRANCH_FILE # Path to .last-branch tracker
The script uses set -e to exit immediately if any command fails, ensuring errors don’t compound across iterations.

​
Dependencies

Required commands:
  • jq - For parsing JSON in prd.json
  • amp or claude - The selected AI coding tool
  • bash - Version 4.0+ recommended
  • git - For commit operations (used by AI tools)

​
Output Format

Ralph produces structured console output: 
Starting Ralph - Tool: amp - Max iterations: 10

===============================================================
  Ralph Iteration 1 of 10 (amp)
===============================================================
[AI tool output appears here]
Iteration 1 complete. Continuing...

===============================================================
  Ralph Iteration 2 of 10 (amp)
===============================================================
[...continues...]

​
Advanced Usage

​
Running in CI

#!/bin/bash
# Run Ralph in CI with error handling
set -e

./scripts/ralph/ralph.sh --tool amp 50

if [ $? -eq 0 ]; then
  echo "All tasks completed!"
  exit 0
else
  echo "Ralph did not complete all tasks"
  cat progress.txt
  exit 1
fi

​
Custom Tool Integration

To add support for a different AI tool, modify the iteration loop in ralph.sh: 
if [[ "$TOOL" == "amp" ]]; then
  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
elif [[ "$TOOL" == "claude" ]]; then
  OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true
elif [[ "$TOOL" == "yourTool" ]]; then
  OUTPUT=$(yourTool < "$SCRIPT_DIR/YOUR_PROMPT.md" 2>&1 | tee /dev/stderr) || true
fi

​
Troubleshooting

​
Script exits immediately with “Invalid tool”

Check that you’re using exactly amp or claude (lowercase) as the tool name: 
# Correct
./ralph.sh --tool amp

# Incorrect
./ralph.sh --tool AMP
./ralph.sh --tool ampcode

​
No output during iterations

Ensure the AI tool is installed and authenticated: 
# Test Amp
amp --version

# Test Claude Code
claude --version

​
Archive not created on branch change

Verify that:
  1. prd.json contains a valid branchName field
  2. The branch name actually changed between runs
  3. You have write permissions in the archive directory