Using Ralph: AFK Codex loop + PRD/progress workflow

README.md

Using Ralph (AFK loop)

This gist contains:

• ralph-loop.sh: runs Codex in an autonomous loop that repeatedly:
  1. picks the highest-priority task from PRD.md + progress.txt
  2. implements only that task
  3. runs tests/typechecks
  4. updates PRD.md and appends to progress.txt
  5. commits
  6. stops when a “promise” file is created

Prereqs

• codex CLI installed + authenticated
• A git repo with:
  • PRD.md (task list + acceptance criteria)
  • progress.txt (append-only log)

Quick start

1. Put ralph-loop.sh in your repo root
2. chmod +x ralph-loop.sh
3. Create PRD.md and progress.txt (tips below)
4. Run: ./ralph-loop.sh 10
5. Review the commits it produced

Writing a good PRD.md (clarify first, then co-author)

Step 1: Ask a few clarifying questions (before coding)

From “ask-questions-if-underspecified”: ask the minimum set of questions needed to avoid wrong work. Aim for 1–5.

Good defaults:

• Objective: what should change vs stay the same?
• “Done”: acceptance criteria + examples/edge cases?
• Scope: what’s in/out?
• Constraints: compatibility, performance, style, deps, time?
• Environment: runtime versions + test commands?

Step 2: Co-author the doc (structure + iterate)

From “doc-coauthoring”: do (1) context gathering, (2) draft/refine section-by-section, then (3) reader testing.

Reader testing is especially useful: paste PRD.md into a fresh chat and ask:

• “What are the top 3 risks/unknowns?”
• “What’s the smallest first milestone?”
• “What would you do first, and why?” If it misunderstands anything, fix the PRD.

Minimal PRD.md skeleton

# <Project / Feature>

## Goal
<one paragraph>

## Non-goals
- ...

## Requirements (ordered)
- [ ] R1: ... (acceptance criteria)
- [ ] R2: ...

## Open Questions
- Q1: ...

Keeping progress.txt useful

Append after each loop:

• date/time + iteration
• what changed (1–5 bullets)
• commands/tests run
• next task(s) / blockers

Example:

2026-01-12 iter 3
- Done: ...
- Tests: ...
- Next: ...

Safety notes

ralph-loop.sh uses codex --dangerously-bypass-approvals-and-sandbox exec. Run it only in a safe repo/branch, start with a small iteration count, and review commits before merging.

References / further reading

• https://www.humanlayer.dev/blog/brief-history-of-ralph
• https://www.aihero.dev/tips-for-ai-coding-with-ralph-wiggum
• Clarifying questions: https://github.com/prateek/dotfiles/blob/master/.codex/skills/ask-questions-if-underspecified/SKILL.md
• Doc co-authoring workflow: https://github.com/anthropics/skills/blob/main/skills/doc-coauthoring/SKILL.md

ralph-loop.sh

#!/bin/bash
set -e

if [[ $# -lt 1 ]]; then
  echo "Usage: $0 <iterations>"
  exit 1
fi

if ! [[ "$1" =~ ^[0-9]+$ ]] || [[ "$1" -lt 1 ]]; then
  echo "Iterations must be a positive integer"
  exit 1
fi

PROMISE_FILE="I_PROMISE_ALL_TASKS_IN_THE_PRD_ARE_DONE_I_AM_NOT_LYING_I_SWEAR"

mkdir -p .logs
rm -f "$PROMISE_FILE"

for ((i = 1; i <= $1; i++)); do
  codex --dangerously-bypass-approvals-and-sandbox exec <<'EOF' 2>&1 | tee -a ".logs/iterations.log"
1. Find the highest-priority task based on PRD.md and progress.txt, 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.
ONLY WORK ON A SINGLE TASK.

If the PRD is complete, and there are NO tasks left, then and only then touch a file named I_PROMISE_ALL_TASKS_IN_THE_PRD_ARE_DONE_I_AM_NOT_LYING_I_SWEAR. Otherwise respond with a brief summary of changes/progress.
EOF

  if [[ -f "$PROMISE_FILE" ]]; then
    echo "PRD complete after $i iterations."
    exit 0
  fi
done

echo "PRD not complete after $1 iterations."
exit 1