ralph-loop

Ralph Loop

Start an autonomous iteration loop for the given task.

Setup

# Parse arguments and create state file
ARGS="$ARGUMENTS"
PROMPT_PARTS=()
MAX_ITERATIONS=10
COMPLETION_PROMISE="null"
VERIFY_CMD="null"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --max-iterations)
      MAX_ITERATIONS="$2"; shift 2 ;;
    --completion-promise)
      COMPLETION_PROMISE="$2"; shift 2 ;;
    --verify-cmd)
      VERIFY_CMD="$2"; shift 2 ;;
    *)
      PROMPT_PARTS+=("$1"); shift ;;
  esac
done
PROMPT="${PROMPT_PARTS[*]}"

if [[ -z "$PROMPT" ]]; then
  echo "❌ No prompt provided. Usage: /ralph-loop \"Your task\" --max-iterations 10"
  exit 1
fi

mkdir -p "$CLAUDE_PROJECT_DIR/.claude"

if [[ "$COMPLETION_PROMISE" != "null" ]]; then
  CP_YAML="\"$COMPLETION_PROMISE\""
else
  CP_YAML="null"
fi

if [[ "$VERIFY_CMD" != "null" ]]; then
  VC_YAML="\"$VERIFY_CMD\""
else
  VC_YAML="null"
fi

cat > "$CLAUDE_PROJECT_DIR/.claude/ralph-loop.local.md" <<EOF
---
active: true
iteration: 1
max_iterations: $MAX_ITERATIONS
completion_promise: $CP_YAML
verify_cmd: $VC_YAML
started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
---

$PROMPT
EOF

# Progress state file (separate from the hook-managed loop file — survives loop end).
# If one already exists, KEEP it: a re-run after a crash/cancel resumes from prior progress.
RALPH_STATE="$CLAUDE_PROJECT_DIR/.claude/ralph-state.local.md"
if [[ -f "$RALPH_STATE" ]]; then
  echo "📄 Existing ralph-state.local.md found — resuming with prior progress/escalations."
  echo "   (Starting an unrelated task? Delete it first: rm .claude/ralph-state.local.md)"
else
  cat > "$RALPH_STATE" <<EOF
# Ralph loop state

## Last run
$(date -u +%Y-%m-%dT%H:%M:%SZ) · iteration 1 · loop started

## In progress
- (nothing yet)

## Completed
- (nothing yet)

## Escalated to humans (do NOT retry)
- (none)

## Lessons learned (durable discoveries — write here, not in chat)
- (none)

## Attempt counts
- (sub-task: N failed attempts)
EOF
fi

echo ""
echo "🔄 Ralph loop activated!"
echo "   Iteration:   1 of $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo '∞ (unlimited)'; fi)"
if [[ "$COMPLETION_PROMISE" != "null" ]]; then
  echo "   Promise:     $COMPLETION_PROMISE"
  if [[ "$VERIFY_CMD" != "null" ]]; then
    echo "   Verifier:    $VERIFY_CMD  (must exit 0 — the promise alone will NOT end the loop)"
  fi
  echo ""
  echo "═══════════════════════════════════════════════"
  echo "  To exit: output <promise>$COMPLETION_PROMISE</promise>"
  echo "  ONLY when the statement is GENUINELY TRUE."
  if [[ "$VERIFY_CMD" != "null" ]]; then
    echo "  The loop then runs:  $VERIFY_CMD"
    echo "  Exit happens ONLY if that command returns exit 0."
  fi
  echo "  Do NOT output a false promise to escape."
  echo "═══════════════════════════════════════════════"
fi
echo ""
echo "  Monitor:  head -5 .claude/ralph-loop.local.md"
echo "  Cancel:   /cancel-ralph"
echo ""