agentic-loop 3.13.0 → 3.14.2

package/ralph/hooks/warn-empty-catch.sh

@@ -1,63 +1,47 @@
 #!/usr/bin/env bash
+# shellcheck shell=bash
 # warn-empty-catch.sh - Warn about empty catch blocks that silently swallow errors
 # Hook: PostToolUse matcher: "Edit|Write"
 
-set -euo pipefail
+source "$(dirname "$0")/common.sh"
 
-INPUT=$(cat)
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+parse_hook_input
 
 # Only check code files
-case "$FILE_PATH" in
-  *.ts|*.tsx|*.js|*.jsx|*.py)
-    ;;
-  *)
-    echo '{"continue": true}'
-    exit 0
-    ;;
-esac
-
-# Get the content that was written
-NEW_CONTENT=""
-if [[ "$TOOL_NAME" == "Write" ]]; then
-  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
-elif [[ "$TOOL_NAME" == "Edit" ]]; then
-  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""')
+if ! is_code_file "ts,tsx,js,jsx,py"; then
+  hook_allow
+  exit 0
 fi
 
 WARNINGS=""
 
 # JavaScript/TypeScript: catch (e) { } or catch { }
-if echo "$NEW_CONTENT" | grep -qE 'catch\s*\([^)]*\)\s*\{\s*\}'; then
+if echo "$NEW_CONTENT" | grep -qE 'catch[[:space:]]*\([^)]*\)[[:space:]]*\{[[:space:]]*\}'; then
   WARNINGS="⚠️  Empty catch block detected. Handle the error or add a comment explaining why it's ignored."
 fi
 
 # Also check for catch with only a comment (no actual handling)
-if echo "$NEW_CONTENT" | grep -qE 'catch\s*\([^)]*\)\s*\{\s*(//[^\n]*)?\s*\}'; then
+if echo "$NEW_CONTENT" | grep -qE 'catch[[:space:]]*\([^)]*\)[[:space:]]*\{[[:space:]]*(//[^}]*)?\}'; then
   if [[ -z "$WARNINGS" ]]; then
     WARNINGS="⚠️  Catch block with no error handling. Consider logging or rethrowing the error."
   fi
 fi
 
 # Python: except: pass or except Exception: pass
-if echo "$NEW_CONTENT" | grep -qE 'except.*:\s*pass\s*$'; then
+if echo "$NEW_CONTENT" | grep -qE 'except.*:[[:space:]]*pass[[:space:]]*$'; then
   WARNINGS="⚠️  Empty except block (pass). Handle the exception or add logging."
 fi
 
 # Python: bare except with just pass on next line
-if echo "$NEW_CONTENT" | grep -qE 'except.*:\s*$' && echo "$NEW_CONTENT" | grep -qE '^\s*pass\s*$'; then
+if echo "$NEW_CONTENT" | grep -qE 'except.*:[[:space:]]*$' && echo "$NEW_CONTENT" | grep -qE '^[[:space:]]*pass[[:space:]]*$'; then
   if [[ -z "$WARNINGS" ]]; then
     WARNINGS="⚠️  Except block with only 'pass'. Consider logging or reraising the exception."
   fi
 fi
 
-# Block if empty catch detected
+# Block if empty catch detected (this hook blocks, doesn't just warn)
 if [[ -n "$WARNINGS" ]]; then
-  jq -n --arg warn "$WARNINGS" '{
-    "continue": false,
-    "message": $warn
-  }'
+  hook_block "$WARNINGS"
 else
-  echo '{"continue": true}'
+  hook_allow
 fi

package/ralph/hooks/warn-secrets.sh

@@ -1,31 +1,18 @@
 #!/usr/bin/env bash
+# shellcheck shell=bash
 # warn-secrets.sh - Warn about potential secrets in written code
 # Hook: PostToolUse matcher: "Edit|Write"
 #
 # Mirrors the pre-commit check-secrets patterns for consistency
 
-set -euo pipefail
+source "$(dirname "$0")/common.sh"
 
-INPUT=$(cat)
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+parse_hook_input
 
 # Only check code files
-case "$FILE_PATH" in
-  *.ts|*.tsx|*.js|*.jsx|*.py|*.json|*.yaml|*.yml|*.env*)
-    ;;
-  *)
-    echo '{"continue": true}'
-    exit 0
-    ;;
-esac
-
-# Get the content that was written
-NEW_CONTENT=""
-if [[ "$TOOL_NAME" == "Write" ]]; then
-  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
-elif [[ "$TOOL_NAME" == "Edit" ]]; then
-  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""')
+if ! is_code_file "ts,tsx,js,jsx,py,json,yaml,yml,env,env.local,env.development,env.production"; then
+  hook_allow
+  exit 0
 fi
 
 WARNINGS=""
@@ -37,53 +24,48 @@ fi
 
 # Stripe keys (sk_live_* or sk_test_*)
 if echo "$NEW_CONTENT" | grep -qE 'sk_(live|test)_[0-9a-zA-Z]{24,}'; then
-  WARNINGS="${WARNINGS}\n🚨 SECURITY: Stripe API key detected! Use environment variables."
+  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Stripe API key detected! Use environment variables."
 fi
 
 # GitHub tokens (ghp_, gho_, ghu_, ghs_, ghr_)
 if echo "$NEW_CONTENT" | grep -qE 'gh[pousr]_[A-Za-z0-9_]{36,}'; then
-  WARNINGS="${WARNINGS}\n🚨 SECURITY: GitHub token detected! Use environment variables."
+  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: GitHub token detected! Use environment variables."
 fi
 
 # Slack tokens (xoxb-, xoxp-, xoxa-, xoxr-, xoxs-)
 if echo "$NEW_CONTENT" | grep -qE 'xox[baprs]-[0-9]{10,}-[0-9a-zA-Z]{24,}'; then
-  WARNINGS="${WARNINGS}\n🚨 SECURITY: Slack token detected! Use environment variables."
+  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Slack token detected! Use environment variables."
 fi
 
 # SendGrid keys (SG.*)
 if echo "$NEW_CONTENT" | grep -qE 'SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}'; then
-  WARNINGS="${WARNINGS}\n🚨 SECURITY: SendGrid API key detected! Use environment variables."
+  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: SendGrid API key detected! Use environment variables."
 fi
 
 # Private keys
-if echo "$NEW_CONTENT" | grep -qE '-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----'; then
-  WARNINGS="${WARNINGS}\n🚨 SECURITY: Private key detected! Never commit private keys."
+if echo "$NEW_CONTENT" | grep -q -- '-----BEGIN.*PRIVATE KEY-----'; then
+  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Private key detected! Never commit private keys."
 fi
 
 # Generic API key patterns (api_key = "...", apikey: "...", etc.)
-if echo "$NEW_CONTENT" | grep -qiE '(api[_-]?key|api[_-]?secret)\s*[:=]\s*['"'"'"][a-zA-Z0-9_\-]{20,}['"'"'"]'; then
+if echo "$NEW_CONTENT" | grep -qiE '(api[_-]?key|api[_-]?secret)[[:space:]]*[:=][[:space:]]*['"'"'"][a-zA-Z0-9_-]{20,}['"'"'"]'; then
   # Check it's not a placeholder
   if ! echo "$NEW_CONTENT" | grep -qiE '(example|placeholder|your[_-]?key|xxx|test|dummy|fake|sample|demo)'; then
-    WARNINGS="${WARNINGS}\n⚠️  Possible hardcoded API key - use environment variables."
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Possible hardcoded API key - use environment variables."
   fi
 fi
 
 # Generic secrets (password = "...", token = "...", etc.)
-if echo "$NEW_CONTENT" | grep -qiE '(password|passwd|pwd|secret|token)\s*[:=]\s*['"'"'"][^'"'"'"]{8,}['"'"'"]'; then
+if echo "$NEW_CONTENT" | grep -qiE '(password|passwd|pwd|secret|token)[[:space:]]*[:=][[:space:]]*['"'"'"][^'"'"'"]{8,}['"'"'"]'; then
   # Check it's not a placeholder or type annotation
   if ! echo "$NEW_CONTENT" | grep -qiE '(example|placeholder|xxx|test|dummy|type|interface|password:)'; then
-    WARNINGS="${WARNINGS}\n⚠️  Possible hardcoded secret - use environment variables."
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Possible hardcoded secret - use environment variables."
   fi
 fi
 
-# Output warning as additional context (non-blocking)
+# Output warning or allow
 if [[ -n "$WARNINGS" ]]; then
-  jq -n --arg warn "$WARNINGS" '{
-    "continue": true,
-    "hookSpecificOutput": {
-      "additionalContext": $warn
-    }
-  }'
+  hook_warn "$WARNINGS"
 else
-  echo '{"continue": true}'
+  hook_allow
 fi

package/ralph/hooks/warn-urls.sh

@@ -1,35 +1,24 @@
 #!/usr/bin/env bash
+# shellcheck shell=bash
 # warn-urls.sh - Warn about hardcoded URLs in written code
 # Hook: PostToolUse matcher: "Edit|Write"
 #
 # Mirrors the pre-commit check-hardcoded-urls patterns for consistency
 
-set -euo pipefail
+source "$(dirname "$0")/common.sh"
 
-INPUT=$(cat)
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+parse_hook_input
 
-# Only check code files (skip test files)
-case "$FILE_PATH" in
-  *.test.*|*.spec.*|*/__tests__/*|*/test/*|*/fixtures/*)
-    echo '{"continue": true}'
-    exit 0
-    ;;
-  *.ts|*.tsx|*.js|*.jsx|*.py)
-    ;;
-  *)
-    echo '{"continue": true}'
-    exit 0
-    ;;
-esac
+# Skip test files
+if is_test_file; then
+  hook_allow
+  exit 0
+fi
 
-# Get the content that was written
-NEW_CONTENT=""
-if [[ "$TOOL_NAME" == "Write" ]]; then
-  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
-elif [[ "$TOOL_NAME" == "Edit" ]]; then
-  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""')
+# Only check code files
+if ! is_code_file "ts,tsx,js,jsx,py"; then
+  hook_allow
+  exit 0
 fi
 
 WARNINGS=""
@@ -45,7 +34,7 @@ fi
 # Check for 127.0.0.1 URLs
 if echo "$NEW_CONTENT" | grep -qE 'https?://127\.0\.0\.1(:[0-9]+)?'; then
   if ! echo "$NEW_CONTENT" | grep -qE '(\|\||\?\?|default|fallback).*127\.0\.0\.1'; then
-    WARNINGS="${WARNINGS}\n⚠️  Hardcoded 127.0.0.1 URL detected - use environment variable"
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Hardcoded 127.0.0.1 URL detected - use environment variable"
   fi
 fi
 
@@ -60,18 +49,13 @@ if [[ -n "$PROD_URLS" ]]; then
   PROD_URLS=$(echo "$PROD_URLS" | grep -v -E '(example|placeholder|test|mock)' || true)
   if [[ -n "$PROD_URLS" ]]; then
     FIRST_URL=$(echo "$PROD_URLS" | head -1)
-    WARNINGS="${WARNINGS}\n⚠️  Hardcoded URL ($FIRST_URL) - consider using environment variable"
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Hardcoded URL ($FIRST_URL) - consider using environment variable"
   fi
 fi
 
-# Output warning as additional context (non-blocking)
+# Output warning or allow
 if [[ -n "$WARNINGS" ]]; then
-  jq -n --arg warn "$WARNINGS" '{
-    "continue": true,
-    "hookSpecificOutput": {
-      "additionalContext": $warn
-    }
-  }'
+  hook_warn "$WARNINGS"
 else
-  echo '{"continue": true}'
+  hook_allow
 fi

package/ralph/loop.sh

@@ -478,10 +478,13 @@ run_loop() {
       rm -f "$RALPH_DIR/last_failure.txt"
       rm -f "$RALPH_DIR/last_verification.log"
 
+      # Get story title for commit message and completion display
+      local title
+      title=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .title' "$RALPH_DIR/prd.json")
+
       # Auto-commit if git is available
       if command -v git &>/dev/null && [[ -d ".git" ]]; then
-        local title commit_log commit_success
-        title=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .title' "$RALPH_DIR/prd.json")
+        local commit_log commit_success
         commit_log=$(mktemp)
         commit_success=false
 

package/ralph/prd-check.sh

@@ -282,7 +282,7 @@ _validate_and_fix_stories() {
 
   # Issue counters (bash 3.2 compatible - no associative arrays)
   local cnt_no_tests=0 cnt_backend_curl=0 cnt_backend_contract=0
-  local cnt_frontend_tsc=0 cnt_frontend_url=0 cnt_frontend_context=0
+  local cnt_frontend_tsc=0 cnt_frontend_url=0 cnt_frontend_context=0 cnt_frontend_mcp=0
   local cnt_auth_security=0 cnt_list_pagination=0 cnt_prose_steps=0
   local cnt_migration_prereq=0 cnt_naming_convention=0 cnt_bare_pytest=0
 
@@ -355,7 +355,7 @@ _validate_and_fix_stories() {
       fi
     fi
 
-    # Check 3: Frontend needs testUrl and contextFiles
+    # Check 3: Frontend needs testUrl, contextFiles, and mcp
     if [[ "$story_type" == "frontend" ]]; then
       local has_url
       has_url=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testUrl // empty' "$prd_file")
@@ -370,6 +370,14 @@ _validate_and_fix_stories() {
         story_issues+="missing contextFiles, "
         cnt_frontend_context=$((cnt_frontend_context + 1))
       fi
+
+      # Frontend must have mcp tools for browser verification
+      local mcp_tools
+      mcp_tools=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
+      if [[ "$mcp_tools" == "0" ]]; then
+        story_issues+="missing mcp (browser tools), "
+        cnt_frontend_mcp=$((cnt_frontend_mcp + 1))
+      fi
     fi
 
     # Check 4: Auth stories need security criteria
@@ -442,6 +450,7 @@ _validate_and_fix_stories() {
     [[ $cnt_frontend_tsc -gt 0 ]] && echo "    ${cnt_frontend_tsc}x frontend: add tsc/playwright"
     [[ $cnt_frontend_url -gt 0 ]] && echo "    ${cnt_frontend_url}x frontend: add testUrl"
     [[ $cnt_frontend_context -gt 0 ]] && echo "    ${cnt_frontend_context}x frontend: add contextFiles"
+    [[ $cnt_frontend_mcp -gt 0 ]] && echo "    ${cnt_frontend_mcp}x frontend: add mcp browser tools"
     [[ $cnt_auth_security -gt 0 ]] && echo "    ${cnt_auth_security}x auth: add security criteria"
     [[ $cnt_list_pagination -gt 0 ]] && echo "    ${cnt_list_pagination}x list: add pagination"
     [[ $cnt_migration_prereq -gt 0 ]] && echo "    ${cnt_migration_prereq}x migration: add prerequisites (DB reset)"
@@ -467,27 +476,41 @@ _fix_stories_with_claude() {
   local prd_file="$1"
   local issues="$2"
 
+  # Read config values for context
+  local config_file="$RALPH_DIR/config.json"
+  local backend_url="" frontend_url=""
+  if [[ -f "$config_file" ]]; then
+    backend_url=$(jq -r '.urls.backend // .api.baseUrl // "http://localhost:8000"' "$config_file" 2>/dev/null)
+    frontend_url=$(jq -r '.urls.frontend // .playwright.baseUrl // "http://localhost:3000"' "$config_file" 2>/dev/null)
+  fi
+
   local fix_prompt="Enhance test coverage for these stories. Output the COMPLETE updated prd.json.
 
 STORIES TO OPTIMIZE:
 $issues
 
+CONFIG VALUES (use these):
+- Backend URL: $backend_url (use as {config.urls.backend} in testSteps)
+- Frontend URL: $frontend_url (use as {config.urls.frontend} in testUrl)
+
 RULES:
 1. Backend stories MUST have testSteps with curl commands that hit real endpoints
    Example: curl -s -X POST {config.urls.backend}/api/users -d '...' | jq -e '.id'
 2. Backend stories MUST have apiContract with endpoint, request, response
-3. Frontend stories MUST have testUrl set to {config.urls.frontend}/page
+3. Frontend stories MUST have testUrl set to {config.urls.frontend}/[page-path]
+   - Derive page path from story title (e.g., 'login form' → '/login', 'dashboard' → '/dashboard')
 4. Frontend stories MUST have contextFiles array (include idea file path from originalContext)
-5. Auth stories MUST have security acceptanceCriteria:
+5. Frontend stories MUST have mcp array with browser tools: [\"playwright\", \"devtools\"]
+6. Auth stories MUST have security acceptanceCriteria:
    - Passwords hashed with bcrypt (cost 10+)
    - Passwords NEVER in API responses
    - Rate limiting on login attempts
-6. List endpoints MUST have pagination acceptanceCriteria:
+7. List endpoints MUST have pagination acceptanceCriteria:
    - Returns paginated results (max 100 per page)
    - Accepts ?page=N&limit=N query params
-7. Migration stories (creating alembic/versions, migrations/, or modifying models) MUST have prerequisites:
+8. Migration stories (creating alembic/versions, migrations/, or modifying models) MUST have prerequisites:
    Example: \"prerequisites\": [{\"name\": \"Reset test DB\", \"command\": \"npm run db:reset:test\", \"when\": \"schema changes\"}]
-8. Frontend/general stories that consume APIs MUST have notes about naming conventions:
+9. Frontend/general stories that consume APIs MUST have notes about naming conventions:
    Example: \"notes\": \"Transform API responses from snake_case to camelCase. Create typed interfaces with camelCase properties and map: const user = { userName: data.user_name }\"
 
 CURRENT PRD:
@@ -591,7 +614,7 @@ validate_stories_quick() {
       fi
     fi
 
-    # Check 3: Frontend needs testUrl and contextFiles
+    # Check 3: Frontend needs testUrl, contextFiles, and mcp
     if [[ "$story_type" == "frontend" ]]; then
       local has_url
       has_url=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testUrl // empty' "$prd_file")
@@ -600,6 +623,10 @@ validate_stories_quick() {
       local context_files
       context_files=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .contextFiles // [] | length' "$prd_file")
       [[ "$context_files" == "0" ]] && issues+="$story_id: missing contextFiles, "
+
+      local mcp_tools
+      mcp_tools=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
+      [[ "$mcp_tools" == "0" ]] && issues+="$story_id: missing mcp, "
     fi
 
     # Check 4: Auth stories need security criteria

package/ralph/setup/quick-setup.sh

@@ -202,20 +202,33 @@ configure_mcp() {
   # Create claude.json if it doesn't exist
   [[ ! -f "$claude_json" ]] && echo '{}' > "$claude_json"
 
-  # Check if chrome-devtools is already configured
-  if jq -e '.mcpServers["chrome-devtools"]' "$claude_json" > /dev/null 2>&1; then
-    echo -e "    ${DIM}Skipped: Chrome DevTools MCP already configured${NC}"
-    return
-  fi
+  local added_any=false
 
-  # Add Chrome DevTools MCP
-  local tmp=$(mktemp)
-  jq '.mcpServers["chrome-devtools"] = {
-    "command": "npx",
-    "args": ["-y", "@anthropic-ai/mcp-server-chrome-devtools@0.0.5"]
-  }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
+  # Add Playwright MCP if not configured (uses chromium + headless to avoid Chrome conflicts)
+  if ! jq -e '.mcpServers["playwright"]' "$claude_json" > /dev/null 2>&1; then
+    local tmp=$(mktemp)
+    jq '.mcpServers["playwright"] = {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless"]
+    }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
+    echo -e "    ${GREEN}${EMOJI_CHECK}${NC} Playwright MCP configured"
+    added_any=true
+  else
+    echo -e "    ${DIM}Skipped: Playwright MCP already configured${NC}"
+  fi
 
-  echo -e "    ${GREEN}${EMOJI_CHECK}${NC} Chrome DevTools MCP configured"
+  # Add Chrome DevTools MCP if not configured
+  if ! jq -e '.mcpServers["chrome-devtools"]' "$claude_json" > /dev/null 2>&1; then
+    local tmp=$(mktemp)
+    jq '.mcpServers["chrome-devtools"] = {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-chrome-devtools@0.0.5"]
+    }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
+    echo -e "    ${GREEN}${EMOJI_CHECK}${NC} Chrome DevTools MCP configured"
+    added_any=true
+  else
+    echo -e "    ${DIM}Skipped: Chrome DevTools MCP already configured${NC}"
+  fi
 }
 
 show_completion() {

package/ralph/setup/ui.sh

@@ -37,33 +37,6 @@ EOF
   echo ""
 }
 
-show_welcome() {
-  echo -e "  ${BOLD}Welcome!${NC} How would you like to get started?"
-  echo ""
-  echo -e "  ${GREEN}[1]${NC} ${EMOJI_ROCKET} ${BOLD}Quick Setup${NC}"
-  echo -e "      ${DIM}I know what I'm doing, just configure my project${NC}"
-  echo ""
-  echo -e "  ${GREEN}[2]${NC} ${EMOJI_MOVIE} ${BOLD}Feature Tour${NC}"
-  echo -e "      ${DIM}Show me what agentic-loop can do (auto-demo)${NC}"
-  echo ""
-  echo -e "  ${GREEN}[3]${NC} ${EMOJI_BOOK} ${BOLD}New to Claude Code${NC}"
-  echo -e "      ${DIM}Teach me the basics (interactive tutorial)${NC}"
-  echo ""
-}
-
-prompt_menu() {
-  local choice
-  while true; do
-    echo -ne "  Press ${GREEN}1${NC}, ${GREEN}2${NC}, or ${GREEN}3${NC} (or ${DIM}q${NC} to quit): "
-    read -r -n 1 choice
-    echo ""
-    case "$choice" in
-      1|2|3|q|Q) echo "$choice"; return ;;
-      *) echo -e "  ${RED}Invalid choice${NC}" ;;
-    esac
-  done
-}
-
 # Typewriter effect for demos
 typewrite() {
   local text="$1" delay="${2:-0.02}"
@@ -111,21 +84,6 @@ print_info() {
   echo -e "  ${CYAN}→${NC} $1"
 }
 
-# Spinner for long operations
-spin() {
-  local pid=$1
-  local delay=0.1
-  local spinstr='|/-\'
-  while [ "$(ps a | awk '{print $1}' | grep $pid)" ]; do
-    local temp=${spinstr#?}
-    printf "  [%c]  " "$spinstr"
-    local spinstr=$temp${spinstr%"$temp"}
-    sleep $delay
-    printf "\b\b\b\b\b\b"
-  done
-  printf "      \b\b\b\b\b\b"
-}
-
 # Confirmation prompt
 confirm() {
   local prompt="${1:-Proceed?}"

package/ralph/setup.sh

@@ -285,6 +285,7 @@ setup_claude_hooks() {
   local settings_file=".claude/settings.json"
   local src_hooks_dir="$pkg_root/ralph/hooks"
   local project_hooks_dir=".ralph/hooks"
+  local global_hooks_dir="$HOME/.config/ralph/hooks"
 
   echo "Installing Claude Code hooks..."
 
@@ -307,6 +308,11 @@ setup_claude_hooks() {
   chmod +x "$project_hooks_dir"/*.sh 2>/dev/null || true
   echo "  Copied hooks to $project_hooks_dir/"
 
+  # Note if global hooks exist
+  if [[ -d "$global_hooks_dir" ]] && ls -1 "$global_hooks_dir"/*.sh &>/dev/null; then
+    echo "  Found global hooks in $global_hooks_dir/"
+  fi
+
   # Get absolute path to project hooks
   local hooks_dir
   hooks_dir="$(cd "$project_hooks_dir" && pwd)"
@@ -317,52 +323,70 @@ setup_claude_hooks() {
   # Create settings file if it doesn't exist
   [[ ! -f "$settings_file" ]] && echo '{}' > "$settings_file"
 
-  # Build hooks config with absolute paths to project hooks
+  # Helper to resolve hook path (project takes priority over global)
+  _resolve_hook() {
+    local hook_name="$1"
+    if [[ -f "$project_hooks_dir/$hook_name" ]]; then
+      echo "$hooks_dir/$hook_name"
+    elif [[ -f "$global_hooks_dir/$hook_name" ]]; then
+      echo "$global_hooks_dir/$hook_name"
+    fi
+  }
+
+  # Resolve each hook path (project hooks take priority over global)
+  local protect_prd warn_debug warn_secrets warn_urls warn_empty_catch log_tools inject_context save_learnings
+  protect_prd=$(_resolve_hook "protect-prd.sh")
+  warn_debug=$(_resolve_hook "warn-debug.sh")
+  warn_secrets=$(_resolve_hook "warn-secrets.sh")
+  warn_urls=$(_resolve_hook "warn-urls.sh")
+  warn_empty_catch=$(_resolve_hook "warn-empty-catch.sh")
+  log_tools=$(_resolve_hook "log-tools.sh")
+  inject_context=$(_resolve_hook "inject-context.sh")
+  save_learnings=$(_resolve_hook "save-learnings.sh")
+
+  # Build hooks arrays using jq for proper JSON
+  local pre_tool_hooks post_edit_hooks post_all_hooks session_start_hooks stop_hooks
+
+  # PreToolUse: protect-prd on Edit|Write
+  pre_tool_hooks="[]"
+  [[ -n "$protect_prd" ]] && pre_tool_hooks=$(jq -n --arg cmd "$protect_prd" '[{"type": "command", "command": $cmd, "timeout": 5}]')
+
+  # PostToolUse: warn-* hooks on Edit|Write
+  post_edit_hooks="[]"
+  for hook_path in "$warn_debug" "$warn_secrets" "$warn_urls" "$warn_empty_catch"; do
+    [[ -n "$hook_path" ]] && post_edit_hooks=$(echo "$post_edit_hooks" | jq --arg cmd "$hook_path" '. + [{"type": "command", "command": $cmd, "timeout": 5}]')
+  done
+
+  # PostToolUse: log-tools on all
+  post_all_hooks="[]"
+  [[ -n "$log_tools" ]] && post_all_hooks=$(jq -n --arg cmd "$log_tools" '[{"type": "command", "command": $cmd, "timeout": 3}]')
+
+  # SessionStart: inject-context
+  session_start_hooks="[]"
+  [[ -n "$inject_context" ]] && session_start_hooks=$(jq -n --arg cmd "$inject_context" '[{"type": "command", "command": $cmd, "timeout": 5}]')
+
+  # Stop: save-learnings
+  stop_hooks="[]"
+  [[ -n "$save_learnings" ]] && stop_hooks=$(jq -n --arg cmd "$save_learnings" '[{"type": "command", "command": $cmd, "timeout": 10}]')
+
+  # Build the complete hooks config
   local hooks_config
-  hooks_config=$(cat <<EOF
-{
-  "PreToolUse": [
-    {
-      "matcher": "Edit|Write",
-      "hooks": [
-        {"type": "command", "command": "$hooks_dir/protect-prd.sh", "timeout": 5}
-      ]
-    }
-  ],
-  "PostToolUse": [
-    {
-      "matcher": "Edit|Write",
-      "hooks": [
-        {"type": "command", "command": "$hooks_dir/warn-debug.sh", "timeout": 5},
-        {"type": "command", "command": "$hooks_dir/warn-secrets.sh", "timeout": 5},
-        {"type": "command", "command": "$hooks_dir/warn-urls.sh", "timeout": 5},
-        {"type": "command", "command": "$hooks_dir/warn-empty-catch.sh", "timeout": 5}
-      ]
-    },
-    {
-      "matcher": "*",
-      "hooks": [
-        {"type": "command", "command": "$hooks_dir/log-tools.sh", "timeout": 3}
-      ]
-    }
-  ],
-  "SessionStart": [
-    {
-      "hooks": [
-        {"type": "command", "command": "$hooks_dir/inject-context.sh", "timeout": 5}
-      ]
-    }
-  ],
-  "Stop": [
-    {
-      "hooks": [
-        {"type": "command", "command": "$hooks_dir/save-learnings.sh", "timeout": 10}
-      ]
-    }
-  ]
-}
-EOF
-)
+  hooks_config=$(jq -n \
+    --argjson pre_tool "$pre_tool_hooks" \
+    --argjson post_edit "$post_edit_hooks" \
+    --argjson post_all "$post_all_hooks" \
+    --argjson session_start "$session_start_hooks" \
+    --argjson stop "$stop_hooks" \
+    '{
+      "PreToolUse": [{"matcher": "Edit|Write", "hooks": $pre_tool}],
+      "PostToolUse": [
+        {"matcher": "Edit|Write", "hooks": $post_edit},
+        {"matcher": "*", "hooks": $post_all}
+      ],
+      "SessionStart": [{"hooks": $session_start}],
+      "Stop": [{"hooks": $stop}]
+    }'
+  )
 
   # Merge hooks into settings
   local tmp
@@ -562,13 +586,14 @@ setup_mcp() {
   local added_any=false
 
   # Add Playwright MCP if not configured
+  # Uses chromium + headless to avoid conflicts with user's Chrome session
   if ! jq -e '.mcpServers["playwright"]' "$claude_json" > /dev/null 2>&1; then
     echo "Configuring MCP servers..."
     local tmp
     tmp=$(mktemp)
     jq '.mcpServers["playwright"] = {
       "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest"]
+      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless"]
     }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
     echo "  Added playwright MCP server (browser automation & testing)"
     added_any=true