Ralph TUI Pre-Flight Check

Fast verification that everything is configured correctly before starting a Ralph loop. Run this after creating a PRD with /prd to validate and launch.

When to Use

• After running /prd to create a prd.json
• Before starting any Ralph loop
• When troubleshooting Ralph loop issues
• To verify template and config are in sync

Pre-Flight Phases

Execute these checks in order. Stop and report if critical issues are found.

---

Phase 1: Environment Check

1.1 Global CLAUDE.md Conflict Detection (CRITICAL)

Ralph loops can have global ~/.claude/CLAUDE.md override local project CLAUDE.md. Check and warn:

# Check if global CLAUDE.md exists
if [ -f ~/.claude/CLAUDE.md ]; then
  echo "WARNING: Global CLAUDE.md exists at ~/.claude/CLAUDE.md"
  echo "This may override your local CLAUDE.md during Ralph loops"
  wc -l ~/.claude/CLAUDE.md
else
  echo "OK: No global CLAUDE.md found"
fi

If global CLAUDE.md exists:

• Show its contents (first 20 lines)
• Ask user if they want to:
  • A. Remove it temporarily (rename to CLAUDE.md.bak)
  • B. Keep it (may cause issues)
  • C. View full contents first

1.2 Ralph TUI Installation

which ralph-tui && ralph-tui --version

1.3 Required Tools

# Check tmux (required for persistent sessions)
which tmux && tmux -V

# Check git (required for worktrees)
git --version

1.4 Existing Ralph State Detection (CRITICAL)

Check if .ralph-tui/ has data from a previous run that could interfere:

# Check for existing state
if [ -d .ralph-tui ]; then
  echo "Found existing .ralph-tui/ directory"

  # Check for progress file with content
  if [ -f .ralph-tui/progress.md ] && [ -s .ralph-tui/progress.md ]; then
    echo "⚠ progress.md exists with content ($(wc -l < .ralph-tui/progress.md) lines)"
  fi

  # Check for iteration logs
  if [ -d .ralph-tui/iterations ] && [ "$(ls -A .ralph-tui/iterations 2>/dev/null)" ]; then
    echo "⚠ iterations/ has $(ls .ralph-tui/iterations | wc -l) log files"
  fi

  # Check for session state
  if [ -f .ralph-tui/state.json ]; then
    echo "⚠ state.json exists (previous session state)"
  fi

  # Check for lock file (Ralph might be running)
  if [ -f .ralph-tui.lock ]; then
    echo "⚠ .ralph-tui.lock exists - Ralph may be running!"
  fi
else
  echo "OK: No existing .ralph-tui/ state"
fi

If existing state is found, determine the situation:

AskUserQuestion: "Found existing Ralph state from a previous run. What's the situation?"
├── "Previous run is complete, clean up for new PRD"
│   → Clean .ralph-tui/iterations/, progress.md, state.json
│   → Keep config.toml and templates
├── "Previous run is still active (different PRD)"
│   → Create new worktree for this PRD
│   → Keep current directory untouched
├── "Save progress to branch first, then clean"
│   → Commit current progress
│   → Clean for new PRD
└── "Let me check the progress first"
│   → Show progress.md contents
│   → Show iteration count
│   → Re-ask after review

Cleanup commands (if user chooses to clean):

# Remove iteration logs
rm -rf .ralph-tui/iterations/*

# Clear progress file (keep file, clear content)
echo "" > .ralph-tui/progress.md

# Remove session state
rm -f .ralph-tui/state.json
rm -f .ralph-tui.lock
rm -f .ralph-tui-session.json

# Verify cleanup
ls -la .ralph-tui/
echo "Cleaned. Ready for new Ralph loop."

If previous run is still active:

# Check current branch
CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"

# Suggest worktree for new PRD
REPO_NAME=$(basename $(git rev-parse --show-toplevel))
echo "Suggested worktree: ../${REPO_NAME}-[new-prd-name]"

Then proceed to Phase 7 for worktree setup.

---

Phase 2: Configuration Validation

2.1 Locate .ralph-tui/config.toml

# Check project config exists
if [ -f .ralph-tui/config.toml ]; then
  echo "OK: Config found at .ralph-tui/config.toml"
else
  echo "ERROR: No .ralph-tui/config.toml found"
  echo "Run: ralph-tui setup"
fi

2.2 Validate Config Settings

Read config.toml and verify critical settings:

2.3 Show Template Source

ralph-tui template show | head -5

Verify it's loading from expected location (not default).

---

Phase 3: Template Validation

3.1 Locate prompt.hbs

Get template path from config.toml prompt_template setting and verify file exists:

# Extract template path from config
grep "prompt_template" .ralph-tui/config.toml
# Verify file exists
ls -la [extracted-path]

3.2 Template Variable Check

Read the prompt.hbs and veri

...