Ralph - Autonomous AI Coding Agent Loop

ralph.sh

#!/bin/bash
# Ralph - Autonomous AI Coding Agent Loop
#
# This script runs an automated development loop using Claude CLI to work through
# tasks defined in a PRD (Product Requirements Document). Each iteration, Claude
# finds the highest-priority task, implements it, runs tests, updates documentation,
# and commits changes.
#
# Inspired by:
# - https://www.aihero.dev/getting-started-with-ralph
# - https://www.youtube.com/watch?v=yAE3ONleUas
#
# The loop continues until either the PRD is marked complete (Claude outputs
# <promise>COMPLETE</promise>) or the maximum number of iterations is reached.
#
# Usage: ./ralph.sh [MAX_ITERATIONS] [SLEEP_SECONDS]
#   MAX_ITERATIONS: Maximum loop iterations (default: 10)
#   SLEEP_SECONDS:  Delay between iterations (default: 2)
set -e

MAX=${1:-10}
SLEEP=${2:-2}
MULTILINE_MESSAGE="@PRD.md @progress.txt \
  1. Find the highest-priority task and implement it. \
  2. Run your tests and type checks. \
  3. Update the PRD with what was done. \
  4. Append your progress to progress.txt. \
  5. Commit your changes, don't bypass pre-commit hook requirements. \
  ONLY WORK ON A SINGLE TASK. \
  If the PRD is complete, output <promise>COMPLETE</promise>."

echo "Starting Ralph - Max $MAX iterations"
echo ""

# check if PRD.md exists
if [ ! -f PRD.md ]; then
  echo "Error: PRD.md not found!"
  exit 1
fi

# check if progress.txt exists, if not create it
if [ ! -f progress.txt ]; then
  echo "Creating progress.txt..."
  touch progress.txt
fi


for ((i=1; i<=$MAX; i++)); do
  result=$(claude --dangerously-skip-permissions -p "$MULTILINE_MESSAGE")

  echo "$result"

  if [[ "$result" == *"<promise>COMPLETE</promise>"* ]]; then
    echo "PRD complete after $i iterations."
    exit 0
  fi

  echo "----- End of iteration $i -----"
  echo "waiting for $SLEEP seconds before next iteration..."
  sleep $SLEEP
done

echo "Ralph - completed $MAX iterations"