Enhance Ralph hook with background task spawning

BREAKING CHANGE: Ralph now runs as background process (non-blocking) Changes: - Enhanced ralph-auto-trigger.sh to spawn Ralph in background - Hook immediately returns to Claude Code (NON-BLOCKING) - Ralph runs via nohup (survives terminal close) - Added PID tracking: ~/.claude/ralph.pid - Added lock file: ~/.claude/ralph.lock - Added log file: ~/.claude/ralph-output.log - Added trigger log: ~/.claude/ralph-trigger.log - Added RALPH_MAX_ITERATIONS environment variable (default: 50) Features: - Background execution: Claude Code continues immediately - Process tracking: PID saved for monitoring/stopping - Lock mechanism: Prevents duplicate Ralph instances - Real-time monitoring: tail -f ~/.claude/ralph-output.log - Graceful cleanup: Auto-cleanup of dead process locks Updated files: - MASTER-PROMPT.md: Enhanced hook script + usage instructions - interactive-install-claude.sh: Enhanced install_ralph() function - ~/.claude/hooks/ralph-auto-trigger.sh: Updated local installation Usage: - Ralph auto-starts in background when agents are requested - Monitor: tail -f ~/.claude/ralph-output.log - Stop: kill $(cat ~/.claude/ralph.pid) - Configure: export RALPH_AUTO_MODE=agents|always|off - Configure: export RALPH_MAX_ITERATIONS=100 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-16 10:03:31 +00:00
parent eca57c93c6
commit 99cb591bf7
2 changed files with 353 additions and 104 deletions
--- a/MASTER-PROMPT.md
+++ b/MASTER-PROMPT.md
@@ -504,80 +504,198 @@ ralph --version
 mkdir -p ~/.claude/hooks
 cat > ~/.claude/hooks/ralph-auto-trigger.sh << 'EOF'
 #!/bin/bash
-
-# Ralph Auto-Trigger Hook
-# Automatically starts Ralph loop when user requests something
-# Set RALPH_AUTO_MODE environment variable to control behavior:
-#   "always"    - Always start Ralph for every request
-#   "agents"    - Only start Ralph for agent requests (default)
+# Ralph Auto-Trigger Hook - Enhanced with Background Task Spawning
+# Automatically starts Ralph CLI in background when needed
+#
+# Modes (via RALPH_AUTO_MODE environment variable):
+#   "always"    - Start Ralph for every request
+#   "agents"    - Only for agent requests (default)
 #   "off"       - Disable auto-trigger
+#
+# Background Execution:
+#   - Ralph runs as background process (non-blocking)
+#   - Claude Code continues immediately
+#   - Ralph output logged to: ~/.claude/ralph-output.log
+#   - Ralph PID tracked in: ~/.claude/ralph.pid

 set -euo pipefail

+# Configuration
+CLAUDE_DIR="$HOME/.claude"
+RALPH_STATE_FILE="$CLAUDE_DIR/ralph-loop.local.md"
+RALPH_PID_FILE="$CLAUDE_DIR/ralph.pid"
+RALPH_LOG_FILE="$CLAUDE_DIR/ralph-output.log"
+RALPH_LOCK_FILE="$CLAUDE_DIR/ralph.lock"
+
 # Read hook input from stdin
 HOOK_INPUT=$(cat)
+USER_PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")

-# Get the user prompt from hook input
-USER_PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty')
+# Fallback: if no JSON input, use first argument
+if [[ -z "$USER_PROMPT" && $# -gt 0 ]]; then
+    USER_PROMPT="$1"
+fi

-# Check if auto-trigger is enabled (default: agents)
+# Get Ralph mode (default: agents)
 RALPH_AUTO_MODE="${RALPH_AUTO_MODE:-agents}"
+RALPH_MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"

 # Exit if auto-trigger is disabled
 if [[ "$RALPH_AUTO_MODE" == "off" ]]; then
    exit 0
 fi

-# Exit if Ralph is already active
-RALPH_STATE_FILE=".claude/ralph-loop.local.md"
-if [[ -f "$RALPH_STATE_FILE" ]]; then
+# Check if Ralph is already running (via lock file)
+if [[ -f "$RALPH_LOCK_FILE" ]]; then
+    # Check if process is still alive
+    LOCK_PID=$(cat "$RALPH_LOCK_FILE" 2>/dev/null || echo "")
+    if [[ -n "$LOCK_PID" ]] && kill -0 "$LOCK_PID" 2>/dev/null; then
+        # Ralph is already running, don't start another instance
        exit 0
+    else
+        # Lock file exists but process is dead, clean up
+        rm -f "$RALPH_LOCK_FILE" "$RALPH_PID_FILE"
+    fi
 fi

-# Check if this is an agent request (list of known agents)
-KNOWN_AGENTS="frontend-developer|backend-architect|mobile-app-builder|ai-engineer|devops-automator|rapid-prototyper|test-writer-fixer|studio-coach|studio-producer|sprint-prioritizer|experiment-tracker|whimsy-injector|joker|trend-researcher|tiktok-strategist|feedback-synthesizer|ui-ux-pro-max"
+# Agent detection list (lowercase for matching)
+AGENTS=(
+    "ai-engineer" "backend-architect" "devops-automator" "frontend-developer"
+    "mobile-app-builder" "rapid-prototyper" "test-writer-fixer"
+    "tiktok-strategist" "growth-hacker" "content-creator" "instagram-curator"
+    "reddit-builder" "twitter-engager" "app-store-optimizer"
+    "brand-guardian" "ui-designer" "ux-researcher" "visual-storyteller"
+    "whimsy-injector" "ui-ux-pro-max"
+    "feedback-synthesizer" "sprint-prioritizer" "trend-researcher"
+    "experiment-tracker" "project-shipper" "studio-producer" "studio-coach"
+    "analytics-reporter" "finance-tracker" "infrastructure-maintainer"
+    "legal-compliance-checker" "support-responder"
+    "api-tester" "performance-benchmarker" "test-results-analyzer"
+    "tool-evaluator" "workflow-optimizer"
+    "joker" "agent-updater"
+    "explore" "plan" "general-purpose"
+)
+
+# Detect agent request (case-insensitive)
+agent_detected=false
+detected_agent=""
+
+for agent in "${AGENTS[@]}"; do
+    if echo "$USER_PROMPT" | grep -iq "$agent"; then
+        agent_detected=true
+        detected_agent="$agent"
+        break
+    fi
+done

 # Determine if we should start Ralph
-START_RALPH=false
+should_trigger=false

 case "$RALPH_AUTO_MODE" in
    "always")
-    # Start Ralph for everything
-    START_RALPH=true
+        # Trigger on all prompts
+        should_trigger=true
        ;;
    "agents")
-    # Check if prompt mentions an agent or uses agent-like language
-    if echo "$USER_PROMPT" | grep -qiE "use (the |a )?($KNOWN_AGENTS) agent|launch ($KNOWN_AGENTS)|agent:|delegate to|run (the |a )?($KNOWN_AGENTS)" || \
-       echo "$USER_PROMPT" | grep -qiE "build|create|implement|develop|fix|add|refactor|optimize"; then
-      START_RALPH=true
+        # Only trigger on agent requests OR development keywords
+        if [[ "$agent_detected" == true ]]; then
+            should_trigger=true
+        elif echo "$USER_PROMPT" | grep -qiE "build|create|implement|develop|fix|add|refactor|optimize|write|generate|delegate|autonomous"; then
+            should_trigger=true
+            detected_agent="general-development"
        fi
        ;;
 esac

-if [[ "$START_RALPH" == "true" ]]; then
-  # Create Ralph state file with default settings
-  mkdir -p .claude
+if [[ "$should_trigger" == true ]]; then
+    # Create Ralph state file
+    mkdir -p "$CLAUDE_DIR"

    cat > "$RALPH_STATE_FILE" << EOF
---
-active: true
-iteration: 1
-max_iterations: 0
-completion_promise: null
-started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-auto_triggered: true
---
+# Ralph Loop State - Auto-Triggered
+# Generated: $(date -u +"%Y-%m-%d %H:%M:%S UTC")

+**User Request:**
 $USER_PROMPT
+
+**Detected Agent:** $detected_agent
+**Mode:** $RALPH_AUTO_MODE
+**Max Iterations:** $RALPH_MAX_ITERATIONS
+**Timestamp:** $(date -Iseconds)
+
+## Context
+
+This state file was automatically generated by the Ralph auto-trigger hook.
+Ralph CLI will read this file and autonomously execute the request.
+
+## Auto-Trigger Details
+
+- Triggered by: Claude Code UserPromptSubmit hook
+- Trigger mode: $RALPH_AUTO_MODE
+- Background execution: Yes (non-blocking)
+- Log file: $RALPH_LOG_FILE
+
+## Usage
+
+Ralph is running autonomously in the background. Monitor progress:
+
+bash
+# View Ralph output in real-time
+tail -f ~/.claude/ralph-output.log
+
+# Check if Ralph is still running
+ps aux | grep ralph
+
+# Stop Ralph manually
+kill $(cat ~/.claude/ralph.pid)
+rm ~/.claude/ralph.lock
+
+
 EOF

-  # Notify that Ralph was auto-triggered
-  echo "🔄 Ralph auto-triggered!" >&2
-  echo "   Mode: $RALPH_AUTO_MODE" >&2
-  echo "   Ralph will loop this request indefinitely." >&2
-  echo "   Set RALPH_AUTO_MODE=off to disable, or use /cancel-ralph to stop." >&2
+    # Spawn Ralph in background (NON-BLOCKING)
+    if command -v ralph &> /dev/null; then
+        # Create log file
+        touch "$RALPH_LOG_FILE"
+
+        # Start Ralph in background with nohup (survives terminal close)
+        echo "[$(date -u +"%Y-%m-%d %H:%M:%S UTC")] Starting Ralph in background..." >> "$RALPH_LOG_FILE"
+        echo "Mode: $RALPH_AUTO_MODE" >> "$RALPH_LOG_FILE"
+        echo "Agent: $detected_agent" >> "$RALPH_LOG_FILE"
+        echo "Max iterations: $RALPH_MAX_ITERATIONS" >> "$RALPH_LOG_FILE"
+        echo "---" >> "$RALPH_LOG_FILE"
+
+        # Start Ralph in background
+        nohup ralph build "$RALPH_MAX_ITERATIONS" >> "$RALPH_LOG_FILE" 2>&1 &
+        RALPH_PID=$!
+
+        # Save PID for tracking
+        echo "$RALPH_PID" > "$RALPH_PID_FILE"
+        echo "$RALPH_PID" > "$RALPH_LOCK_FILE"
+
+        # Log the trigger
+        {
+            echo "[$(date -u +"%Y-%m-%d %H:%M:%S UTC")] Ralph auto-triggered"
+            echo "  Mode: $RALPH_AUTO_MODE"
+            echo "  Agent: $detected_agent"
+            echo "  PID: $RALPH_PID"
+            echo "  Log: $RALPH_LOG_FILE"
+        } >> "$CLAUDE_DIR/ralph-trigger.log" 2>/dev/null || true
+
+        # Notify user via stderr (visible in Claude Code)
+        echo "🔄 Ralph CLI auto-started in background" >&2
+        echo "   PID: $RALPH_PID" >&2
+        echo "   Agent: $detected_agent" >&2
+        echo "   Monitor: tail -f ~/.claude/ralph-output.log" >&2
+        echo "   Stop: kill \$(cat ~/.claude/ralph.pid)" >&2
+    else
+        # Ralph not installed, just create state file
+        echo "⚠️  Ralph CLI not installed. State file created for manual use." >&2
+        echo "   Install: npm install -g @iannuttall/ralph" >&2
+    fi
 fi

+# Exit immediately (NON-BLOCKING - Claude Code continues)
 exit 0
 EOF

@@ -609,8 +727,11 @@ Note: Replace "/home/uroma" with your actual home directory if different.

 ### What This Provides:

-**Autonomous Looping:**
- Ralph keeps iterating until task completion
+**Background Autonomous Looping:**
+- Ralph runs as background process (NON-BLOCKING)
+- Claude Code continues immediately
+- Ralph output logged to: ~/.claude/ralph-output.log
+- Ralph PID tracked in: ~/.claude/ralph.pid
 - State preserved in `.claude/ralph-loop.local.md`
 - Can handle complex multi-step workflows

@@ -625,46 +746,70 @@ export RALPH_AUTO_MODE="always"
 # Mode 3: Disable auto-loop
 export RALPH_AUTO_MODE="off"

-### How It Works:
+# Set max iterations (default: 50)
+export RALPH_MAX_ITERATIONS="100"

-1. You request: "Build a TikTok app in 2 weeks"
+### How It Works (Background Execution):
+
+1. You request in Claude Code: "Build a TikTok app in 2 weeks"
 2. Hook detects agent language
-3. Ralph creates state file and starts loop
-4. Ralph iterates through agents:
+3. Hook spawns Ralph in BACKGROUND (non-blocking)
+4. Claude Code immediately continues (you can keep working!)
+5. Ralph autonomously iterates in background:
   - Iteration 1: rapid-prototyper builds MVP
   - Iteration 2: tiktok-strategist plans viral features
   - Iteration 3: frontend-developer builds UI
-   - Continues until Ralph is satisfied
-5. Ralph updates `.claude/ralph-loop.local.md` each iteration
-6. Stop with: /cancel-ralph command or delete state file
+   - Continues until Ralph completes max iterations
+6. Monitor Ralph: tail -f ~/.claude/ralph-output.log
+7. Stop Ralph anytime: kill $(cat ~/.claude/ralph.pid)
+
+### Monitoring Ralph:
+
+# View Ralph output in real-time
+tail -f ~/.claude/ralph-output.log
+
+# Check if Ralph is still running
+ps aux | grep ralph
+# Or check the PID file
+cat ~/.claude/ralph.pid
+
+# View Ralph trigger log
+cat ~/.claude/ralph-trigger.log

 ### Canceling Ralph:

-If Ralph is looping and you want to stop:
+If Ralph is running in background and you want to stop:

-# Method 1: Use cancel command
-/cancel-ralph
+# Method 1: Kill by PID (recommended)
+kill $(cat ~/.claude/ralph.pid)
+rm ~/.claude/ralph.lock

-# Method 2: Delete state file
-rm .claude/ralph-loop.local.md
+# Method 2: Kill by process name
+pkill -f "ralph build"

-# Method 3: Disable auto-mode
+# Method 3: Disable auto-mode (prevents future triggers)
 export RALPH_AUTO_MODE="off"

+# Method 4: Delete state file (Ralph will stop on next iteration)
+rm ~/.claude/ralph-loop.local.md
+
 ### Ralph vs PROACTIVELY Agents:

-| Feature | Ralph CLI | PROACTIVELY Agents |
-|---------|-----------|-------------------|
-| **Execution** | Multi-loop iterations | Single interaction |
-| **State** | Persisted in file | Context only |
-| **Control** | Manual stop required | Automatic |
+| Feature | Ralph CLI (Background) | PROACTIVELY Agents |
+|---------|------------------------|-------------------|
+| **Execution** | Multi-loop, background process | Single interaction |
+| **Blocking** | NON-BLOCKING (runs in bg) | Blocking (waits for response) |
+| **State** | Persisted in file + log | Context only |
+| **Control** | Manual stop via PID | Automatic completion |
 | **Complexity** | Handles complex workflows | Quick coordination |
 | **Setup** | Requires hook + script | Built-in to agents |
+| **Best For** | Large projects, overnight coding | Quick tasks, human collaboration |

 **You can use BOTH together:**
- Use Ralph for complex, multi-step projects
- Use PROACTIVELY agents for quick tasks
+- Use Ralph for complex, multi-step projects (autonomous)
+- Use PROACTIVELY agents for quick tasks (interactive)
 - Set RALPH_AUTO_MODE="agents" for hybrid approach
+- Ralph runs in background while you continue working in Claude Code

 ---

--- a/interactive-install-claude.sh
+++ b/interactive-install-claude.sh
@@ -1151,15 +1151,63 @@ install_ralph() {
    # Create hooks directory
    mkdir -p "$CLAUDE_DIR/hooks"

-    # Create ralph-auto-trigger.sh script
-    log_info "Creating Ralph auto-trigger hook..."
+    # Create ralph-auto-trigger.sh script (Enhanced with Background Spawning)
+    log_info "Creating Ralph auto-trigger hook with background spawning..."
    cat > "$CLAUDE_DIR/hooks/ralph-auto-trigger.sh" << 'RALPH_HOOK_EOF'
 #!/bin/bash
-# Ralph Auto-Trigger Hook
-# Detects agent requests and manages Ralph state for autonomous looping
+# Ralph Auto-Trigger Hook - Enhanced with Background Task Spawning
+# Automatically starts Ralph CLI in background when needed
+#
+# Modes (via RALPH_AUTO_MODE environment variable):
+#   "always"    - Start Ralph for every request
+#   "agents"    - Only for agent requests (default)
+#   "off"       - Disable auto-trigger
+#
+# Background Execution:
+#   - Ralph runs as background process (non-blocking)
+#   - Claude Code continues immediately
+#   - Ralph output logged to: ~/.claude/ralph-output.log
+#   - Ralph PID tracked in: ~/.claude/ralph.pid

-STATE_FILE="$HOME/.claude/ralph-loop.local.md"
-RALPH_MODE="${RALPH_AUTO_MODE:-agents}"  # Options: always, agents, off
+set -euo pipefail
+
+# Configuration
+CLAUDE_DIR="$HOME/.claude"
+RALPH_STATE_FILE="$CLAUDE_DIR/ralph-loop.local.md"
+RALPH_PID_FILE="$CLAUDE_DIR/ralph.pid"
+RALPH_LOG_FILE="$CLAUDE_DIR/ralph-output.log"
+RALPH_LOCK_FILE="$CLAUDE_DIR/ralph.lock"
+
+# Read hook input from stdin
+HOOK_INPUT=$(cat)
+USER_PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")
+
+# Fallback: if no JSON input, use first argument
+if [[ -z "$USER_PROMPT" && $# -gt 0 ]]; then
+    USER_PROMPT="$1"
+fi
+
+# Get Ralph mode (default: agents)
+RALPH_AUTO_MODE="${RALPH_AUTO_MODE:-agents}"
+RALPH_MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"
+
+# Exit if auto-trigger is disabled
+if [[ "$RALPH_AUTO_MODE" == "off" ]]; then
+    exit 0
+fi
+
+# Check if Ralph is already running (via lock file)
+if [[ -f "$RALPH_LOCK_FILE" ]]; then
+    # Check if process is still alive
+    LOCK_PID=$(cat "$RALPH_LOCK_FILE" 2>/dev/null || echo "")
+    if [[ -n "$LOCK_PID" ]] && kill -0 "$LOCK_PID" 2>/dev/null; then
+        # Ralph is already running, don't start another instance
+        exit 0
+    else
+        # Lock file exists but process is dead, clean up
+        rm -f "$RALPH_LOCK_FILE" "$RALPH_PID_FILE"
+    fi
+fi

 # Agent detection list (lowercase for matching)
 AGENTS=(
@@ -1176,16 +1224,9 @@ AGENTS=(
    "api-tester" "performance-benchmarker" "test-results-analyzer"
    "tool-evaluator" "workflow-optimizer"
    "joker" "agent-updater"
+    "explore" "plan" "general-purpose"
 )

-# Check if mode is off
-if [ "$RALPH_MODE" = "off" ]; then
-    exit 0
-fi
-
-# Read the user prompt
-USER_PROMPT="$1"
-
 # Detect agent request (case-insensitive)
 agent_detected=false
 detected_agent=""
@@ -1198,51 +1239,114 @@ for agent in "${AGENTS[@]}"; do
    fi
 done

-# Check if we should trigger
+# Determine if we should start Ralph
 should_trigger=false

-if [ "$RALPH_MODE" = "always" ]; then
+case "$RALPH_AUTO_MODE" in
+    "always")
        # Trigger on all prompts
        should_trigger=true
-elif [ "$RALPH_MODE" = "agents" ]; then
-    # Only trigger on agent requests
-    if [ "$agent_detected" = true ]; then
+        ;;
+    "agents")
+        # Only trigger on agent requests OR development keywords
+        if [[ "$agent_detected" == true ]]; then
            should_trigger=true
+        elif echo "$USER_PROMPT" | grep -qiE "build|create|implement|develop|fix|add|refactor|optimize|write|generate|delegate|autonomous"; then
+            should_trigger=true
+            detected_agent="general-development"
        fi
-fi
+        ;;
+esac

-if [ "$should_trigger" = true ]; then
-    # Create/update state file
-    cat > "$STATE_FILE" << EOF
-# Ralph Loop State
-# Generated: $(date)
+if [[ "$should_trigger" == true ]]; then
+    # Create Ralph state file
+    mkdir -p "$CLAUDE_DIR"
+
+    cat > "$RALPH_STATE_FILE" << EOF
+# Ralph Loop State - Auto-Triggered
+# Generated: $(date -u +"%Y-%m-%d %H:%M:%S UTC")

 **User Request:**
 $USER_PROMPT

 **Detected Agent:** $detected_agent
-**Mode:** $RALPH_MODE
+**Mode:** $RALPH_AUTO_MODE
+**Max Iterations:** $RALPH_MAX_ITERATIONS
 **Timestamp:** $(date -Iseconds)

 ## Context

 This state file was automatically generated by the Ralph auto-trigger hook.
-Ralph CLI can read this file to continue autonomous looping based on the user's request.
+Ralph CLI will read this file and autonomously execute the request.
+
+## Auto-Trigger Details
+
+- Triggered by: Claude Code UserPromptSubmit hook
+- Trigger mode: $RALPH_AUTO_MODE
+- Background execution: Yes (non-blocking)
+- Log file: $RALPH_LOG_FILE

 ## Usage

-To run Ralph autonomously:
-\`\`\`bash
-ralph build 50  # Run 50 iterations
-\`\`\`
+Ralph is running autonomously in the background. Monitor progress:
+
+bash
+# View Ralph output in real-time
+tail -f ~/.claude/ralph-output.log
+
+# Check if Ralph is still running
+ps aux | grep ralph
+
+# Stop Ralph manually
+kill $(cat ~/.claude/ralph.pid)
+rm ~/.claude/ralph.lock
+

-Ralph will read this state file and continue working until the task is complete.
 EOF

-    # Log the trigger (silent, no output)
-    echo "[$(date '+%Y-%m-%d %H:%M:%S')] Ralph auto-triggered: mode=$RALPH_MODE, agent=$detected_agent" >> "$HOME/.claude/ralph-trigger.log" 2>/dev/null || true
+    # Spawn Ralph in background (NON-BLOCKING)
+    if command -v ralph &> /dev/null; then
+        # Create log file
+        touch "$RALPH_LOG_FILE"
+
+        # Start Ralph in background with nohup (survives terminal close)
+        echo "[$(date -u +"%Y-%m-%d %H:%M:%S UTC")] Starting Ralph in background..." >> "$RALPH_LOG_FILE"
+        echo "Mode: $RALPH_AUTO_MODE" >> "$RALPH_LOG_FILE"
+        echo "Agent: $detected_agent" >> "$RALPH_LOG_FILE"
+        echo "Max iterations: $RALPH_MAX_ITERATIONS" >> "$RALPH_LOG_FILE"
+        echo "---" >> "$RALPH_LOG_FILE"
+
+        # Start Ralph in background
+        nohup ralph build "$RALPH_MAX_ITERATIONS" >> "$RALPH_LOG_FILE" 2>&1 &
+        RALPH_PID=$!
+
+        # Save PID for tracking
+        echo "$RALPH_PID" > "$RALPH_PID_FILE"
+        echo "$RALPH_PID" > "$RALPH_LOCK_FILE"
+
+        # Log the trigger
+        {
+            echo "[$(date -u +"%Y-%m-%d %H:%M:%S UTC")] Ralph auto-triggered"
+            echo "  Mode: $RALPH_AUTO_MODE"
+            echo "  Agent: $detected_agent"
+            echo "  PID: $RALPH_PID"
+            echo "  Log: $RALPH_LOG_FILE"
+        } >> "$CLAUDE_DIR/ralph-trigger.log" 2>/dev/null || true
+
+        # Notify user via stderr (visible in Claude Code)
+        echo "🔄 Ralph CLI auto-started in background" >&2
+        echo "   PID: $RALPH_PID" >&2
+        echo "   Agent: $detected_agent" >&2
+        echo "   Monitor: tail -f ~/.claude/ralph-output.log" >&2
+        echo "   Stop: kill \$(cat ~/.claude/ralph.pid)" >&2
+    else
+        # Ralph not installed, just create state file
+        echo "⚠️  Ralph CLI not installed. State file created for manual use." >&2
+        echo "   Install: npm install -g @iannuttall/ralph" >&2
+    fi
 fi

+# Exit immediately (NON-BLOCKING - Claude Code continues)
 exit 0
 RALPH_HOOK_EOF