Ralph Loop Setup

Generate scaffolding for running codex in an autonomous while loop.

Usage

When asked to set up a ralph loop, create a ralph/ subdirectory and the following 4 files inside it. Replace [SPEC_FILES] with the spec filenames provided by user (use path relative to project root). Configure MAX_ITERATIONS as requested.

ralph/run.sh

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
MAX_ITERATIONS=${1:-50}
STATUS_FILE="$SCRIPT_DIR/status.md"

for ((i = 1; i <= MAX_ITERATIONS; i++)); do
    echo "=== Iteration $i/$MAX_ITERATIONS ==="

    codex exec "$(cat "$SCRIPT_DIR/prompt.md")" --model gpt-5.2-codex --full-auto --config model_reasoning_effort="xhigh"

    if [[ -f "$SCRIPT_DIR/summary.md" ]]; then
        echo "--- Summary: $(cat "$SCRIPT_DIR/summary.md")"
    fi

    STATUS=$(head -1 "$STATUS_FILE" | grep -oE '(Done|Blocked|In Progress)')

    if [[ "$STATUS" == "Done" ]]; then
        echo "✅ Complete after $i iterations"
        exit 0
    elif [[ "$STATUS" == "Blocked" ]]; then
        echo "🚫 Blocked after $i iterations - manual intervention needed"
        exit 1
    fi

    echo "Status: $STATUS - continuing..."
done

echo "⚠️ Max iterations ($MAX_ITERATIONS) reached"
exit 1

Make executable with chmod +x ralph/run.sh.

ralph/prompt.md

Study [SPEC_FILES]
Study ralph/status.md for previous work and memory

Pick the most important incomplete task and work on it. Run the full quality gate (typecheck, lint, tests, format). If you learn something important for future work, add it to ralph/status.md. Commit when done.

Once finished, overwrite ralph/summary.md with a one-line summary.

If all tasks complete, set Status to 'Done'. If stuck on something impossible, set Status to 'Blocked'.

IMPORTANT:

- Follow any/all guidelines in AGENTS.md/CLAUDE.md
- author property-based tests or unit tests, whichever is better suited

ralph/status.md

Status: In Progress

## Memory

ralph/summary.md

Create empty.