feat(loop): validate Claude Code CLI command at startup (#97)

CLAUDE.md

@@ -176,7 +176,7 @@ tmux attach -t <session-name>
 
 ### Running Tests
 ```bash
-# Run all tests (556 tests)
+# Run all tests (566 tests)
 npm test
 
 # Run specific test suites
@@ -216,12 +216,20 @@ Ralph uses modern Claude Code CLI flags for structured communication:
 
 **Configuration Variables:**
 ```bash
+CLAUDE_CODE_CMD="claude"              # Claude Code CLI command (configurable via .ralphrc, Issue #97)
 CLAUDE_OUTPUT_FORMAT="json"           # Output format: json (default) or text
 CLAUDE_ALLOWED_TOOLS="Write,Read,Edit,Bash(git add *),Bash(git commit *),...,Bash(npm *),Bash(pytest)"  # Allowed tool permissions (see File Protection)
 CLAUDE_USE_CONTINUE=true              # Enable session continuity
 CLAUDE_MIN_VERSION="2.0.76"           # Minimum Claude CLI version
 ```
 
+**Claude Code CLI Command (Issue #97):**
+- `CLAUDE_CODE_CMD` defaults to `"claude"` (global install)
+- Configurable via `.ralphrc` for alternative installations (e.g., `"npx @anthropic-ai/claude-code"`)
+- Auto-detected during `ralph-enable` and `ralph-setup` (prefers `claude` if available, falls back to npx)
+- Validated at startup with `validate_claude_command()` — displays clear error with installation instructions if not found
+- Environment variable `CLAUDE_CODE_CMD` takes precedence over `.ralphrc`
+
 **CLI Options:**
 - `--output-format json|text` - Set Claude output format (default: json). Note: `--live` mode requires JSON and will auto-switch from text to json.
 - `--allowed-tools "Write,Read,Bash(git *)"` - Restrict allowed tools
@@ -511,13 +519,13 @@ Ralph uses a multi-layered strategy to prevent Claude from accidentally deleting
 
 ## Test Suite
 
-### Test Files (556 tests total)
+### Test Files (566 tests total)
 
 | File | Tests | Description |
 |------|-------|-------------|
 | `test_circuit_breaker_recovery.bats` | 19 | Cooldown timer, auto-reset, parse_iso_to_epoch, CLI flag (Issue #160) |
 | `test_cli_parsing.bats` | 35 | CLI argument parsing for all flags + monitor parameter forwarding |
-| `test_cli_modern.bats` | 56 | Modern CLI commands (Phase 1.1) + build_claude_command fix + live mode text format fix (#164) + errexit pipeline guard (#175) + ALLOWED_TOOLS tightening (#149) + API limit false positive detection (#183) |
+| `test_cli_modern.bats` | 66 | Modern CLI commands (Phase 1.1) + build_claude_command fix + live mode text format fix (#164) + errexit pipeline guard (#175) + ALLOWED_TOOLS tightening (#149) + API limit false positive detection (#183) + Claude CLI command validation (#97) |
 | `test_json_parsing.bats` | 52 | JSON output format parsing + Claude CLI format + session management + array format |
 | `test_session_continuity.bats` | 44 | Session lifecycle management + expiration + circuit breaker integration + issue #91 fix |
 | `test_exit_detection.bats` | 53 | Exit signal detection + EXIT_SIGNAL-based completion indicators + progress detection |

README.md

@@ -18,7 +18,7 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
 
 **Version**: v0.11.5 - Active Development
 **Core Features**: Working and tested
-**Test Coverage**: 556 tests, 100% pass rate
+**Test Coverage**: 566 tests, 100% pass rate
 
 ### What's Working Now
 - Autonomous development loops with intelligent exit detection
@@ -47,7 +47,7 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
 - Three-layer API limit detection: timeout guard → structural JSON (`rate_limit_event`) → filtered text fallback
 - Unattended mode: API limit prompt now auto-waits on timeout instead of exiting
 - Fixed bash 3.x compatibility: `${,,}` lowercase substitution replaced with POSIX `tr` (#187)
-- Added 8 new tests for API limit detection (548 → 556 tests)
+- Added 8 new tests for API limit detection (548 → 566 tests)
 
 **v0.11.4 - Bug Fixes & Compatibility**
 - Fixed progress detection: Git commits within a loop now count as progress (#141)
@@ -400,6 +400,10 @@ Each Ralph project can have a `.ralphrc` configuration file:
 PROJECT_NAME="my-project"
 PROJECT_TYPE="typescript"
 
+# Claude Code CLI command (auto-detected, override if needed)
+CLAUDE_CODE_CMD="claude"
+# CLAUDE_CODE_CMD="npx @anthropic-ai/claude-code"  # Alternative: use npx
+
 # Loop settings
 MAX_CALLS_PER_HOUR=100
 CLAUDE_TIMEOUT_MINUTES=15
@@ -613,7 +617,7 @@ my-project/
 ## System Requirements
 
 - **Bash 4.0+** - For script execution
-- **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code`
+- **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code` (or use npx — set `CLAUDE_CODE_CMD` in `.ralphrc`)
 - **tmux** - Terminal multiplexer for integrated monitoring (recommended)
 - **jq** - JSON processing for status tracking
 - **Git** - Version control (projects are initialized as git repos)
@@ -632,7 +636,7 @@ If you want to run the test suite:
 # Install BATS testing framework
 npm install -g bats bats-support bats-assert
 
-# Run all tests (556 tests)
+# Run all tests (566 tests)
 npm test
 
 # Run specific test suites
@@ -658,7 +662,7 @@ bats tests/integration/test_installation.bats
 ```
 
 Current test status:
-- **556 tests** across 18 test files
+- **566 tests** across 18 test files
 - **100% pass rate** (556/556 passing)
 - Comprehensive unit and integration tests
 - Specialized tests for JSON parsing, CLI flags, circuit breaker, EXIT_SIGNAL behavior, enable wizard, and installation workflows
@@ -728,6 +732,7 @@ tail -f .ralph/logs/ralph.log
 
 ### Common Issues
 
+- **Ralph exits silently on first loop** - Claude Code CLI may not be installed or not in PATH. Ralph validates the command at startup and shows installation instructions. If using npx, add `CLAUDE_CODE_CMD="npx @anthropic-ai/claude-code"` to `.ralphrc`
 - **Rate Limits** - Ralph automatically waits and displays countdown
 - **5-Hour API Limit** - Ralph detects and prompts for user action (wait or exit)
 - **Stuck Loops** - Check `fix_plan.md` for unclear or conflicting tasks
@@ -765,7 +770,7 @@ cd ralph-claude-code
 
 # Install dependencies and run tests
 npm install
-npm test  # All 556 tests must pass
+npm test  # All 566 tests must pass
 ```
 
 ### Priority Contribution Areas

install.sh

@@ -81,8 +81,14 @@ check_dependencies() {
         fi
     fi
 
-    # Claude Code CLI will be downloaded automatically when first used
-    log "INFO" "Claude Code CLI (@anthropic-ai/claude-code) will be downloaded when first used."
+    # Check Claude Code CLI availability
+    if command -v claude &>/dev/null; then
+        log "INFO" "Claude Code CLI found: $(command -v claude)"
+    else
+        log "WARN" "Claude Code CLI ('claude') not found in PATH."
+        log "INFO" "  Install globally: npm install -g @anthropic-ai/claude-code"
+        log "INFO" "  Or use npx: set CLAUDE_CODE_CMD=\"npx @anthropic-ai/claude-code\" in .ralphrc"
+    fi
 
     # Check tmux (optional)
     if ! command -v tmux &> /dev/null; then

lib/enable_core.sh

@@ -681,6 +681,14 @@ generate_ralphrc() {
     local project_type="${2:-unknown}"
     local task_sources="${3:-local}"
 
+    # Auto-detect Claude Code CLI command
+    local claude_cmd="claude"
+    if ! command -v claude &>/dev/null; then
+        if command -v npx &>/dev/null; then
+            claude_cmd="npx @anthropic-ai/claude-code"
+        fi
+    fi
+
     cat << RALPHRCEOF
 # .ralphrc - Ralph project configuration
 # Generated by: ralph enable
@@ -690,6 +698,12 @@ generate_ralphrc() {
 PROJECT_NAME="${project_name}"
 PROJECT_TYPE="${project_type}"
 
+# Claude Code CLI command
+# If "claude" is not in your PATH, set to your installation:
+#   "npx @anthropic-ai/claude-code"  (uses npx, no global install needed)
+#   "/path/to/claude"                (custom path)
+CLAUDE_CODE_CMD="${claude_cmd}"
+
 # Loop settings
 MAX_CALLS_PER_HOUR=100
 CLAUDE_TIMEOUT_MINUTES=15

ralph_import.sh

@@ -6,6 +6,11 @@ set -e
 
 # Configuration
 CLAUDE_CODE_CMD="claude"
+# Load CLAUDE_CODE_CMD from .ralphrc if available
+if [[ -f ".ralphrc" ]]; then
+    _ralphrc_cmd=$(grep "^CLAUDE_CODE_CMD=" ".ralphrc" 2>/dev/null | cut -d= -f2- | tr -d '"' | tr -d "'")
+    [[ -n "$_ralphrc_cmd" ]] && CLAUDE_CODE_CMD="$_ralphrc_cmd"
+fi
 
 # Modern CLI Configuration (Phase 1.1)
 # These flags enable structured JSON output and controlled file operations

ralph_loop.sh

@@ -45,6 +45,7 @@ _env_CLAUDE_SESSION_EXPIRY_HOURS="${CLAUDE_SESSION_EXPIRY_HOURS:-}"
 _env_VERBOSE_PROGRESS="${VERBOSE_PROGRESS:-}"
 _env_CB_COOLDOWN_MINUTES="${CB_COOLDOWN_MINUTES:-}"
 _env_CB_AUTO_RESET="${CB_AUTO_RESET:-}"
+_env_CLAUDE_CODE_CMD="${CLAUDE_CODE_CMD:-}"
 
 # Now set defaults (only if not already set by environment)
 MAX_CALLS_PER_HOUR="${MAX_CALLS_PER_HOUR:-100}"
@@ -116,6 +117,7 @@ RALPHRC_LOADED=false
 #   - CB_SAME_ERROR_THRESHOLD
 #   - CB_OUTPUT_DECLINE_THRESHOLD
 #   - RALPH_VERBOSE
+#   - CLAUDE_CODE_CMD (path or command for Claude Code CLI)
 #
 load_ralphrc() {
     if [[ ! -f "$RALPHRC_FILE" ]]; then
@@ -152,11 +154,69 @@ load_ralphrc() {
     [[ -n "$_env_VERBOSE_PROGRESS" ]] && VERBOSE_PROGRESS="$_env_VERBOSE_PROGRESS"
     [[ -n "$_env_CB_COOLDOWN_MINUTES" ]] && CB_COOLDOWN_MINUTES="$_env_CB_COOLDOWN_MINUTES"
     [[ -n "$_env_CB_AUTO_RESET" ]] && CB_AUTO_RESET="$_env_CB_AUTO_RESET"
+    [[ -n "$_env_CLAUDE_CODE_CMD" ]] && CLAUDE_CODE_CMD="$_env_CLAUDE_CODE_CMD"
 
     RALPHRC_LOADED=true
     return 0
 }
 
+# validate_claude_command - Verify the Claude Code CLI is available
+#
+# Checks that CLAUDE_CODE_CMD resolves to an executable command.
+# For npx-based commands, validates that npx is available.
+# Returns 0 if valid, 1 if not found (with helpful error message).
+#
+validate_claude_command() {
+    local cmd="$CLAUDE_CODE_CMD"
+
+    # For npx-based commands, check that npx itself is available
+    if [[ "$cmd" == npx\ * ]] || [[ "$cmd" == "npx" ]]; then
+        if ! command -v npx &>/dev/null; then
+            echo ""
+            echo -e "${RED}╔════════════════════════════════════════════════════════════╗${NC}"
+            echo -e "${RED}║  NPX NOT FOUND                                            ║${NC}"
+            echo -e "${RED}╚════════════════════════════════════════════════════════════╝${NC}"
+            echo ""
+            echo -e "${YELLOW}CLAUDE_CODE_CMD is set to use npx, but npx is not installed.${NC}"
+            echo ""
+            echo -e "${YELLOW}To fix this:${NC}"
+            echo "  1. Install Node.js (includes npx): https://nodejs.org"
+            echo "  2. Or install Claude Code globally:"
+            echo "     npm install -g @anthropic-ai/claude-code"
+            echo "     Then set in .ralphrc: CLAUDE_CODE_CMD=\"claude\""
+            echo ""
+            return 1
+        fi
+        return 0
+    fi
+
+    # For direct commands, check that the command exists
+    if ! command -v "$cmd" &>/dev/null; then
+        echo ""
+        echo -e "${RED}╔════════════════════════════════════════════════════════════╗${NC}"
+        echo -e "${RED}║  CLAUDE CODE CLI NOT FOUND                                ║${NC}"
+        echo -e "${RED}╚════════════════════════════════════════════════════════════╝${NC}"
+        echo ""
+        echo -e "${YELLOW}The Claude Code CLI command '${cmd}' is not available.${NC}"
+        echo ""
+        echo -e "${YELLOW}Installation options:${NC}"
+        echo "  1. Install globally (recommended):"
+        echo "     npm install -g @anthropic-ai/claude-code"
+        echo ""
+        echo "  2. Use npx (no global install needed):"
+        echo "     Add to .ralphrc: CLAUDE_CODE_CMD=\"npx @anthropic-ai/claude-code\""
+        echo ""
+        echo -e "${YELLOW}Current configuration:${NC} CLAUDE_CODE_CMD=\"${cmd}\""
+        echo ""
+        echo -e "${YELLOW}After installation or configuration:${NC}"
+        echo "  ralph --monitor  # Restart Ralph"
+        echo ""
+        return 1
+    fi
+
+    return 0
+}
+
 # Colors for terminal output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -1256,6 +1316,35 @@ execute_claude_code() {
         local claude_pid=$!
         local progress_counter=0
 
+        # Early failure detection: if the command doesn't exist or fails immediately,
+        # the backgrounded process dies before the monitoring loop starts (Issue #97)
+        sleep 1
+        if ! kill -0 $claude_pid 2>/dev/null; then
+            wait $claude_pid 2>/dev/null
+            local early_exit=$?
+            local early_output=""
+            if [[ -f "$output_file" && -s "$output_file" ]]; then
+                early_output=$(tail -5 "$output_file" 2>/dev/null)
+            fi
+            log_status "ERROR" "❌ Claude Code process exited immediately (exit code: $early_exit)"
+            if [[ -n "$early_output" ]]; then
+                log_status "ERROR" "Output: $early_output"
+            fi
+            echo ""
+            echo -e "${RED}Claude Code failed to start.${NC}"
+            echo ""
+            echo -e "${YELLOW}Possible causes:${NC}"
+            echo "  - '${CLAUDE_CODE_CMD}' command not found or not executable"
+            echo "  - Claude Code CLI not installed"
+            echo "  - Authentication or configuration issue"
+            echo ""
+            echo -e "${YELLOW}To fix:${NC}"
+            echo "  1. Verify Claude Code works: ${CLAUDE_CODE_CMD} --version"
+            echo "  2. Or set a different command in .ralphrc: CLAUDE_CODE_CMD=\"npx @anthropic-ai/claude-code\""
+            echo ""
+            return 1
+        fi
+
         # Show progress while Claude Code is running
         while kill -0 $claude_pid 2>/dev/null; do
             progress_counter=$((progress_counter + 1))
@@ -1453,6 +1542,12 @@ main() {
         fi
     fi
 
+    # Validate Claude Code CLI is available before starting
+    if ! validate_claude_command; then
+        log_status "ERROR" "Claude Code CLI not found: $CLAUDE_CODE_CMD"
+        exit 1
+    fi
+
     log_status "SUCCESS" "🚀 Ralph loop starting with Claude Code"
     log_status "INFO" "Max calls per hour: $MAX_CALLS_PER_HOUR"
     log_status "INFO" "Logs: $LOG_DIR/ | Docs: $DOCS_DIR/ | Status: $STATUS_FILE"

setup.sh

@@ -62,6 +62,13 @@ if [[ -f "$LIB_DIR/enable_core.sh" ]]; then
     generate_ralphrc "$PROJECT_NAME" "generic" "local" | sed 's/Generated by: ralph enable/Generated by: ralph-setup/' > .ralphrc
 else
     # Fallback: create minimal .ralphrc inline (same content as generate_ralphrc)
+    # Auto-detect Claude Code CLI command
+    _claude_cmd="claude"
+    if ! command -v claude &>/dev/null; then
+        if command -v npx &>/dev/null; then
+            _claude_cmd="npx @anthropic-ai/claude-code"
+        fi
+    fi
     cat > .ralphrc << RALPHRCEOF
 # .ralphrc - Ralph project configuration
 # Generated by: ralph-setup
@@ -71,6 +78,12 @@ else
 PROJECT_NAME="${PROJECT_NAME}"
 PROJECT_TYPE="generic"
 
+# Claude Code CLI command
+# If "claude" is not in your PATH, set to your installation:
+#   "npx @anthropic-ai/claude-code"  (uses npx, no global install needed)
+#   "/path/to/claude"                (custom path)
+CLAUDE_CODE_CMD="${_claude_cmd}"
+
 # Loop settings
 MAX_CALLS_PER_HOUR=100
 CLAUDE_TIMEOUT_MINUTES=15