Vasyl’s Dev Notes

Ralph is a technique for running AI coding agents in a loop. You repeatedly run the same prompt, allowing the AI to pick tasks from a PRD (Product Requirements Document), implement features one by one, and commit changes automatically. Over time, this results in working code with minimal manual intervention.

This guide walks through setting up a basic Ralph loop using Claude Code and Docker.

1. Install Claude Code

Install using:

curl -fsSL https://claude.ai/install.sh | bash

If not found, add to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

source ~/.bashrc

Or via npm:

npm i -g @anthropic-ai/claude-code

2. Install Docker Desktop

Docker allows running Claude in an isolated sandbox where it can modify files and run commands safely.

Run:

docker sandbox run claude

3. Create Your Plan File

Create a PRD (PRD.md) describing tasks. Also create a progress tracker:

touch progress.txt

4. Create ralph-once.sh

Basic loop script:

#!/bin/bash
claude --permission-mode acceptEdits "@PRD.md @progress.txt 1. Read the PRD and progress file. 2. Find the next incomplete task and implement it. 3. Commit your changes. 4. Update progress.txt with what you did. ONLY DO ONE TASK AT A TIME."

Make executable:

chmod +x ralph-once.sh

5. Create afk-ralph.sh

Automated loop:

#!/bin/bash
set -e
for ((i=1; i<=$1; i++)); do
  result=$(docker sandbox run claude --permission-mode acceptEdits -p "@PRD.md @progress.txt   1. Find the highest-priority task and implement it.   2. Run tests.   3. Update PRD.   4. Update progress.txt.   5. Commit changes.   ONLY WORK ON A SINGLE TASK.   If complete, output <promise>COMPLETE</promise>.")
  echo "$result"
  if [[ "$result" == *"<promise>COMPLETE</promise>"* ]]; then
    echo "PRD complete."
    exit 0
  fi
done

6. Make It Your Own

Ralph is flexible. You can adapt it to different workflows:

– Pull tasks from GitHub or task managers

– Open PRs instead of committing directly

– Use it for test coverage, linting, or refactoring

Any workflow where the agent can analyze code, improve it, and commit changes can be automated with Ralph.