Implementing Ralph loops

#!/usr/bin/env bash
# Minimal Ralph-style loop for Claude Code (workshop edition).
# Idea: fresh `claude -p` each iteration, specs on disk, grep for a done token.
# Heavier setups exist upstream; this script stays small on purpose.

set -o pipefail
set -u

usage() {
  cat <<'EOF'
Minimal Ralph-style loop: repeated `claude -p` passes over specs/ until DONE tokens appear.

Usage: ./scripts/ralph-loop.sh [max_iterations]

  max_iterations   Optional cap (e.g. 10). Omit for unlimited until ALL_DONE or Ctrl+C.

Environment:
  CLAUDE_CMD        Default: claude
  PERM_MODE         Default: auto  (Claude Code --permission-mode; see workshop Auto mode doc)
  RALPH_NO_PTY      Set to 1 to skip pseudo-tty wrapper (rare; only if `script` causes issues)
  RALPH_NO_STREAM   Set to 1 to disable stream-json streaming and fall back to plain `claude -p`
                    (only final answer is printed, at the end, mostly useful for debugging).

Streaming: by default Claude runs with `--verbose --output-format stream-json`, which emits one
  JSON event per line (tool_use, tool_result, assistant text, etc.) as work happens. Those events
  are pretty-printed to your terminal in real time and also written to logs/ralph_*.log. Without
  this, `claude -p` stays silent until the end of each pass.

EOF
}

[[ "${1:-}" == "-h" || "${1:-}" == "--help" ]] && { usage; exit 0; }

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
cd "$ROOT"

CLAUDE_CMD="${CLAUDE_CMD:-claude}"
PERM_MODE="${PERM_MODE:-auto}"

MAX_ITERATIONS=0
if [[ "${1:-}" =~ ^[0-9]+$ ]]; then
  MAX_ITERATIONS="$1"
fi

mkdir -p logs specs

if ! command -v stdbuf >/dev/null 2>&1 && ! command -v gstdbuf >/dev/null 2>&1; then
  echo "ralph-loop: GNU stdbuf/gstdbuf not on PATH (optional). If the console stays quiet until each pass finishes, try: brew install coreutils, then put gnubin ahead on PATH for gstdbuf." >&2
fi

if ! command -v "$CLAUDE_CMD" &>/dev/null; then
  echo "error: '$CLAUDE_CMD' not found on PATH" >&2
  exit 1
fi

# Line-buffer script's pipe output when libc supports it (macOS: brew install coreutils → gstdbuf).
script_lb() {
  if command -v stdbuf >/dev/null 2>&1; then
    stdbuf -oL -eL script "$@"
  elif command -v gstdbuf >/dev/null 2>&1; then
    gstdbuf -oL -eL script "$@"
  else
    script "$@"
  fi
}

# With stream-json, claude emits one JSON line per event as work happens (tool calls, assistant
# text, etc.), this is the ONLY way to see live progress; plain `-p` stays silent until done.
# Kept as a plain string so it survives `export` into the bash child spawned by `script`.
CLAUDE_STREAM_FLAGS=""
if [[ "${RALPH_NO_STREAM:-}" != "1" ]] && ! command -v python3 >/dev/null 2>&1; then
  echo "ralph-loop: python3 not found; disabling stream-json so final-result sentinels remain verifiable." >&2
  RALPH_NO_STREAM=1
  export RALPH_NO_STREAM
fi
if [[ "${RALPH_NO_STREAM:-}" != "1" ]]; then
  CLAUDE_STREAM_FLAGS="--verbose --output-format stream-json"
fi
export CLAUDE_STREAM_FLAGS

run_claude_from_prompt_file() {
  local pf="$1"
  # $CLAUDE_STREAM_FLAGS is intentionally unquoted so it word-splits into separate args.
  if command -v stdbuf >/dev/null 2>&1; then
    cat "$pf" | stdbuf -oL -eL "$CLAUDE_CMD" -p --permission-mode "$PERM_MODE" $CLAUDE_STREAM_FLAGS
  elif command -v gstdbuf >/dev/null 2>&1; then
    cat "$pf" | gstdbuf -oL -eL "$CLAUDE_CMD" -p --permission-mode "$PERM_MODE" $CLAUDE_STREAM_FLAGS
  else
    cat "$pf" | "$CLAUDE_CMD" -p --permission-mode "$PERM_MODE" $CLAUDE_STREAM_FLAGS
  fi
}
export -f run_claude_from_prompt_file
export CLAUDE_CMD PERM_MODE

invoke_claude_streaming() {
  local pf="$1"
  # Stream-json is already line-delimited and flushes per event, a pty wrapper only adds CRLF
  # noise that corrupts terminal rendering. Skip `script` whenever streaming is enabled.
  if [[ "${RALPH_NO_STREAM:-}" != "1" ]] || [[ "${RALPH_NO_PTY:-}" == "1" ]] || ! command -v script >/dev/null 2>&1; then
    run_claude_from_prompt_file "$pf"
    return
  fi
  if script -V 2>&1 | grep -qi util-linux; then
    local q
    q=$(printf '%q' "$pf")
    script_lb -qec "bash -c 'run_claude_from_prompt_file \"\$1\"' _ $q" /dev/null
    return
  fi
  script_lb -q /dev/null bash -c 'run_claude_from_prompt_file "$1"' _ "$pf"
}

# Pretty-print claude's stream-json events into readable lines. One JSON event per input line;
# each event becomes zero or more human-readable output lines. Passes through unrecognised lines
# verbatim. Only the final result event emits a completion marker.
format_stream() {
  if [[ "${RALPH_NO_STREAM:-}" == "1" ]] || ! command -v python3 >/dev/null 2>&1; then
    cat
    return
  fi
  python3 -u -c '
import sys, json
def trunc(s, n=240):
    s = str(s)
    return s if len(s) <= n else s[:n] + "..."
for raw in sys.stdin:
    # Strip both \n and \r, a pty wrapper upstream (e.g. macOS `script`) can inject \r
    # which would otherwise make each printed line overwrite the previous one.
    line = raw.strip("\r\n")
    if not line.strip():
        continue
    try:
        ev = json.loads(line)
    except Exception:
        print(line); continue
    t = ev.get("type")
    if t == "system":
        sub = ev.get("subtype", "")
        model = ev.get("model", "?")
        cwd = ev.get("cwd", "?")
        print("[system:%s] model=%s cwd=%s" % (sub, model, cwd))
    elif t == "assistant":
        for b in ev.get("message", {}).get("content", []) or []:
            bt = b.get("type")
            if bt == "text":
                txt = b.get("text", "").rstrip()
                if txt: print(txt)
            elif bt == "tool_use":
                name = b.get("name", "?")
                inp = trunc(json.dumps(b.get("input", {}), ensure_ascii=False))
                print("[tool:%s] %s" % (name, inp))
            elif bt == "thinking":
                th = b.get("thinking", "").strip().replace("\n", " ")
                if th: print("[thinking] %s" % trunc(th))
    elif t == "user":
        for b in ev.get("message", {}).get("content", []) or []:
            if b.get("type") == "tool_result":
                c = b.get("content", "")
                if isinstance(c, list):
                    c = " ".join(x.get("text", "") for x in c if isinstance(x, dict))
                print("[result] %s" % trunc(c))
    elif t == "result":
        print("[done] turns=%s cost=$%s duration=%sms" % (
            ev.get("num_turns", "?"),
            ev.get("total_cost_usd", "?"),
            ev.get("duration_ms", "?"),
        ))
        r = ev.get("result")
        if r:
            print(r)
            lines = r.splitlines()
            if "<promise>ALL_DONE</promise>" in lines:
                print("[ralph-final] ALL_DONE")
            elif "<promise>DONE</promise>" in lines:
                print("[ralph-final] DONE")
    else:
        print("[%s] %s" % (t, trunc(line)))
'
}

# Pipe claude → formatter → log + terminal. `tee` keeps output flowing live and on disk.
run_claude_with_live_log() {
  local log="$1"
  local pf="$2"
  if [[ -w /dev/tty ]] 2>/dev/null; then
    invoke_claude_streaming "$pf" 2>&1 | format_stream | tee "$log" /dev/tty >/dev/null
  else
    invoke_claude_streaming "$pf" 2>&1 | format_stream | tee "$log"
  fi
}

PROMPT_FILE="$ROOT/logs/.ralph-loop-prompt.txt"
cat <<'PROMPT' > "$PROMPT_FILE"
You are running **one pass** of a Ralph-style autonomous loop in this repository.

**Verification is mandatory.** The outer loop only stays honest if you **close the feedback loop** with real commands, not a story about what “should” work. You **must not** print `<promise>DONE</promise>` or `<promise>ALL_DONE</promise>` until **every** check in step 5 has **actually succeeded** (exit code zero). If checks fail, **fix and re-run**; never claim done on a red build or failing tests.

1. If **RALPH.md** exists at the repo root, read it first (it may name required checks for this repo).
2. Under **specs/**, treat a markdown file as **complete** only if it contains a line exactly: `## Status: COMPLETE`
3. Pick **one** incomplete spec (prefer lower numeric prefix in the filename, e.g. `001-foo.md` before `002-bar.md`).
4. Implement that spec. **Commit** with a clear message when the work belongs together, **local commits only**.
   - **Never `git push`** (no `push` to any remote, no `--force` pushes). Publishing is for a **human** after review.
   - If the spec uses markdown task lists under **Acceptance criteria** (`- [ ]` …), **check them off as you verify each one**: change every finished line to `- [x]` so the file matches reality before you mark the phase complete.
5. **Run verification before any done token** (use what the spec and stack require, examples below):
   - **Unit / integration tests:** e.g. `npm test`, `pnpm test`, `cargo test`, `dotnet test`, `pytest`, etc., whatever the repo already uses.
   - **Build / typecheck:** e.g. `npm run build`, `tsc --noEmit`, `dotnet build`, `cargo build`, so the tree compiles.
   - **E2E / UI behavior:** if the spec or project depends on browser flows, run the project’s e2e suite (e.g. **Playwright** via `npx playwright test` or equivalent), or use **Playwright MCP** (or another browser/testing MCP) if this workspace is wired for it, so “works in the UI” is **observed**, not guessed.
   - Obey **RALPH.md** / **AGENTS.md** / **CLAUDE.md** if they name extra gates (lint, audit, etc.).
   **All of the above that apply must pass.** If something is not applicable, say so briefly in your output, but never skip checks that the spec explicitly requires.
6. Only when acceptance criteria are **fully** met **and** every required verification command has **succeeded**: ensure **every** acceptance-criterion checkbox in that spec is `- [x]`, then add `## Status: COMPLETE`, then print `<promise>DONE</promise>` as an exact standalone line in your final result.
7. Only when **no** incomplete specs remain and you have **sanity-checked** that nothing is left: print `<promise>ALL_DONE</promise>` as an exact standalone line in your final result.

Do not print `<promise>DONE</promise>` or `<promise>ALL_DONE</promise>` until verification has truly passed.

**Git:** you may **commit**; you must **not push**, ever, in this loop.
PROMPT

iter=0
while true; do
  iter=$((iter + 1))
  if [[ "$MAX_ITERATIONS" -gt 0 && "$iter" -gt "$MAX_ITERATIONS" ]]; then
    echo "ralph-loop: stopped after $MAX_ITERATIONS iteration(s)."
    break
  fi

  LOG="$ROOT/logs/ralph_${iter}_$(date +%Y%m%d_%H%M%S).log"
  echo ""
  echo "ralph-loop: iteration $iter → $LOG"

  run_claude_with_live_log "$LOG" "$PROMPT_FILE"

  if [[ "${RALPH_NO_STREAM:-}" == "1" ]]; then
    all_done_pattern='<promise>ALL_DONE</promise>'
    done_pattern='<promise>DONE</promise>'
  else
    all_done_pattern='[ralph-final] ALL_DONE'
    done_pattern='[ralph-final] DONE'
  fi

  if grep -qxF "$all_done_pattern" "$LOG" 2>/dev/null; then
    echo "ralph-loop: ALL_DONE, no incomplete specs."
    break
  fi
  if grep -qxF "$done_pattern" "$LOG" 2>/dev/null; then
    echo "ralph-loop: DONE, next iteration (fresh context)."
    sleep 1
    continue
  fi

  echo "ralph-loop: no DONE/ALL_DONE in output, check $LOG (will retry)."
  sleep 2
done

echo "ralph-loop: exiting after $iter iteration(s)."