1→#!/bin/bash 2→# Ralph - Autonomous AI Development Loop 3→# Usage: ralph [plan|build] [max-iterations] 4→# 5→# Examples: 6→# ralph ./my-feature-plan.md # Build mode (default), runs until RALPH_DONE 7→# ralph ./my-feature-plan.md plan # Plan mode, generates implementation tasks 8→# ralph ./my-feature-plan.md build 20 # Build mode, max 20 iterations 9→# 10→# Exit conditions: 11→# - Plan mode: Exits after 1 iteration (planning complete) 12→# - Build mode: "RALPH_DONE" appears in progress file 13→# - Max iterations reached (if specified) 14→# - Ctrl+C 15→# 16→# Progress is tracked in: _PROGRESS.md (in current directory) 17→ 18→set -euo pipefail 19→ 20→RALPH_DIR="$(cd "$(dirname "$0")" && pwd)" 21→ 22→# Load constants 23→if [ -f "$RALPH_DIR/lib/constants.sh" ]; then 24→ source "$RALPH_DIR/lib/constants.sh" 25→fi 26→ 27→# Load platform utilities for cross-platform support 28→if [ -f "$RALPH_DIR/lib/platform-utils.sh" ]; then 29→ source "$RALPH_DIR/lib/platform-utils.sh" 30→fi 31→ 32→# Colors (defined early for use in validation messages) 33→RED='\033[0;31m' 34→GREEN='\033[0;32m' 35→YELLOW='\033[1;33m' 36→BLUE='\033[0;34m' 37→NC='\033[0m' # No Color 38→ 39→# Log directory for errors (use platform-appropriate paths) 40→if command -v get_home_dir &>/dev/null && command -v get_temp_dir &>/dev/null; then 41→ USER_HOME=$(get_home_dir) 42→ TEMP_DIR=$(get_temp_dir) 43→else 44→ USER_HOME="${HOME}" 45→ TEMP_DIR="${TMPDIR:-/tmp}" 46→fi 47→ 48→LOG_DIR="${USER_HOME}/.portableralph/logs" 49→if ! mkdir -p "$LOG_DIR" 2>/dev/null; then 50→ echo "Warning: Could not create log directory: $LOG_DIR" >&2 51→ LOG_DIR="${TEMP_DIR}/ralph_logs" 52→ mkdir -p "$LOG_DIR" 2>/dev/null || LOG_DIR="" 53→fi 54→ 55→# Error logging function 56→log_error() { 57→ local timestamp=$(date '+%Y-%m-%d %H:%M:%S') 58→ local message="$1" 59→ local logfile="${LOG_DIR}/ralph_$(date '+%Y%m%d').log" 60→ 61→ # Log to file if LOG_DIR is available 62→ if [ -n "$LOG_DIR" ] && [ -d "$LOG_DIR" ]; then 63→ if ! echo "[$timestamp] ERROR: $message" >> "$logfile" 2>/dev/null; then 64→ # If logging to file fails, at least note it on stderr 65→ echo "[$timestamp] WARNING: Failed to write to log file: $logfile" >&2 66→ fi 67→ fi 68→ 69→ # Always log to stderr 70→ echo -e "${RED}Error: $message${NC}" >&2 71→} 72→ 73→# Source shared validation library 74→source "${RALPH_DIR}/lib/validation.sh" 75→ 76→# The following validation functions are now loaded from lib/validation.sh: 77→# - validate_webhook_url() / validate_url() 78→# - validate_numeric() 79→# - validate_email() 80→# - validate_file_path() / validate_path() 81→# - json_escape() 82→# - mask_token() 83→ 84→# Just use the library's validate_path function 85→# Users should be able to use whatever plan files they want 86→validate_file_path() { 87→ validate_path "$@" 88→} 89→ 90→# Validate config file syntax before sourcing 91→validate_config() { 92→ local config_file="$1" 93→ 94→ # Check if file exists 95→ if [ ! -f "$config_file" ]; then 96→ return 0 # File doesn't exist, nothing to validate 97→ fi 98→ 99→ # Just check basic bash syntax 100→ if ! bash -n "$config_file" 2>/dev/null; then 101→ echo -e "${YELLOW}Warning: Syntax error in $config_file${NC}" >&2 102→ echo -e "${YELLOW}Run: bash -n $config_file to see details${NC}" >&2 103→ return 1 104→ fi 105→ 106→ return 0 107→} 108→ 109→# Load configuration (use platform-appropriate config location) 110→RALPH_CONFIG_FILE="${USER_HOME}/.ralph.env" 111→if [ -f "$RALPH_CONFIG_FILE" ] && validate_config "$RALPH_CONFIG_FILE"; then 112→ source "$RALPH_CONFIG_FILE" 113→ 114→ # Decrypt encrypted environment variables BEFORE validation 115→ if [ -f "$RALPH_DIR/decrypt-env.sh" ]; then 116→ source "$RALPH_DIR/decrypt-env.sh" 117→ # Call decrypt_ralph_env directly to allow variable updates 118→ # Capture any errors but don't pipe the output (which would run in a subshell) 119→ if ! decrypt_ralph_env; then 120→ echo -e "${YELLOW}Warning: Failed to decrypt some environment variables${NC}" >&2 121→ echo "Some notification platforms may not work correctly" >&2 122→ fi 123→ fi 124→ 125→ # Validate loaded configuration values (now with decrypted values) 126→ if [ -n "${RALPH_SLACK_WEBHOOK_URL:-}" ]; then 127→ if ! validate_webhook_url "$RALPH_SLACK_WEBHOOK_URL" "RALPH_SLACK_WEBHOOK_URL"; then 128→ echo -e "${YELLOW}Warning: Invalid RALPH_SLACK_WEBHOOK_URL, disabling Slack notifications${NC}" >&2 129→ unset RALPH_SLACK_WEBHOOK_URL 130→ fi 131→ fi 132→ 133→ if [ -n "${RALPH_DISCORD_WEBHOOK_URL:-}" ]; then 134→ if ! validate_webhook_url "$RALPH_DISCORD_WEBHOOK_URL" "RALPH_DISCORD_WEBHOOK_URL"; then 135→ echo -e "${YELLOW}Warning: Invalid RALPH_DISCORD_WEBHOOK_URL, disabling Discord notifications${NC}" >&2 136→ unset RALPH_DISCORD_WEBHOOK_URL 137→ fi 138→ fi 139→ 140→ if [ -n "${RALPH_EMAIL_TO:-}" ]; then 141→ if ! validate_email "$RALPH_EMAIL_TO" "RALPH_EMAIL_TO"; then 142→ echo -e "${YELLOW}Warning: Invalid RALPH_EMAIL_TO, disabling email notifications${NC}" >&2 143→ unset RALPH_EMAIL_TO 144→ fi 145→ fi 146→ 147→ if [ -n "${RALPH_EMAIL_FROM:-}" ]; then 148→ if ! validate_email "$RALPH_EMAIL_FROM" "RALPH_EMAIL_FROM"; then 149→ echo -e "${YELLOW}Warning: Invalid RALPH_EMAIL_FROM, disabling email notifications${NC}" >&2 150→ unset RALPH_EMAIL_FROM 151→ fi 152→ fi 153→ 154→ if [ -n "${RALPH_NOTIFY_FREQUENCY:-}" ]; then 155→ # Note: Not using 'local' here since we're at top level, not in a function 156→ _notify_min="${NOTIFY_FREQUENCY_MIN:-1}" 157→ _notify_max="${NOTIFY_FREQUENCY_MAX:-100}" 158→ _notify_default="${NOTIFY_FREQUENCY_DEFAULT:-5}" 159→ if ! validate_numeric "$RALPH_NOTIFY_FREQUENCY" "RALPH_NOTIFY_FREQUENCY" "$_notify_min" "$_notify_max"; then 160→ echo -e "${YELLOW}Warning: Invalid RALPH_NOTIFY_FREQUENCY, using default: ${_notify_default}${NC}" >&2 161→ export RALPH_NOTIFY_FREQUENCY="$_notify_default" 162→ fi 163→ unset _notify_min _notify_max _notify_default 164→ fi 165→fi 166→ 167→VERSION="1.7.0" 168→ 169→# Auto-commit setting (default: true) 170→# Can be disabled via: ralph config commit off 171→# Or by adding DO_NOT_COMMIT on its own line in the plan file 172→RALPH_AUTO_COMMIT="${RALPH_AUTO_COMMIT:-true}" 173→ 174→# Check if plan file contains DO_NOT_COMMIT directive 175→# Skips content inside ``` code blocks to avoid false positives 176→should_skip_commit_from_plan() { 177→ local plan_file="$1" 178→ [ ! -f "$plan_file" ] && return 1 179→ 180→ # Use awk to skip code blocks and find DO_NOT_COMMIT on its own line 181→ # Handles whitespace before/after the directive 182→ awk ' 183→ /^```/ { in_code = !in_code; next } 184→ !in_code && /^[[:space:]]*DO_NOT_COMMIT[[:space:]]*$/ { found=1; exit } 185→ END { exit !found } 186→ ' "$plan_file" 187→} 188→ 189→# Notification helper with retry logic and error logging 190→notify() { 191→ local message="$1" 192→ local emoji="${2:-}" 193→ local max_retries="${NOTIFY_MAX_RETRIES:-3}" 194→ local retry_delay="${NOTIFY_RETRY_DELAY:-2}" 195→ local attempt=1 196→ local notification_log="${LOG_DIR}/ralph_notifications_$(date '+%Y%m%d').log" 197→ 198→ # Skip if LOG_DIR is not available (use platform-appropriate null device) 199→ if [ -z "$LOG_DIR" ] || [ ! -d "$LOG_DIR" ]; then 200→ if command -v get_null_device &>/dev/null; then 201→ notification_log="$(get_null_device)" 202→ else 203→ notification_log="/dev/null" 204→ fi 205→ fi 206→ 207→ while [ $attempt -le $max_retries ]; do 208→ local notify_output 209→ local notify_exit=0 210→ 211→ # Capture output and exit code 212→ notify_output=$("$RALPH_DIR/notify.sh" "$message" "$emoji" 2>&1) || notify_exit=$? 213→ 214→ # Log the output with proper error handling (check for null device) 215→ local null_dev="/dev/null" 216→ if command -v get_null_device &>/dev/null; then 217→ null_dev="$(get_null_device)" 218→ fi 219→ if [ "$notification_log" != "$null_dev" ] && [ "$notification_log" != "NUL" ]; then 220→ if ! echo "[$(date '+%Y-%m-%d %H:%M:%S')] Attempt $attempt: $notify_output" >> "$notification_log" 2>/dev/null; then 221→ # If logging fails, report to stderr but don't fail the notification 222→ echo "Warning: Failed to write to notification log: $notification_log" >&2 223→ fi 224→ fi 225→ 226→ if [ $notify_exit -eq 0 ]; then 227→ return 0 228→ fi 229→ 230→ if [ $attempt -lt $max_retries ]; then 231→ log_error "Notification attempt $attempt/$max_retries failed (exit $notify_exit), retrying in ${retry_delay}s..." 232→ sleep $retry_delay 233→ # Exponential backoff 234→ retry_delay=$((retry_delay * 2)) 235→ else 236→ local msg_truncate="${MESSAGE_TRUNCATE_LENGTH:-100}" 237→ log_error "Notification failed after $max_retries attempts (exit $notify_exit): ${message:0:$msg_truncate}..." 238→ fi 239→ 240→ attempt=$((attempt + 1)) 241→ done 242→ 243→ return 1 # Failed after all retries 244→} 245→ 246→# Check if any notification platform is configured 247→notifications_enabled() { 248→ [ -n "${RALPH_SLACK_WEBHOOK_URL:-}" ] || \ 249→ [ -n "${RALPH_DISCORD_WEBHOOK_URL:-}" ] || \ 250→ ([ -n "${RALPH_TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${RALPH_TELEGRAM_CHAT_ID:-}" ]) || \ 251→ [ -n "${RALPH_CUSTOM_NOTIFY_SCRIPT:-}" ] 252→} 253→ 254→usage() { 255→ echo -e "${GREEN}PortableRalph${NC} v${VERSION} - Autonomous AI Development Loop" 256→ echo "" 257→ echo -e "${YELLOW}Usage:${NC}" 258→ echo " ralph [mode] [max-iterations]" 259→ echo " ralph update [--check|--list|]" 260→ echo " ralph rollback" 261→ echo " ralph config " 262→ echo " ralph notify " 263→ echo " ralph --help | -h" 264→ echo " ralph --version | -v" 265→ echo "" 266→ echo -e "${YELLOW}Full path:${NC} ~/ralph/ralph.sh (alias: ralph)" 267→ echo "" 268→ echo -e "${YELLOW}Arguments:${NC}" 269→ echo " plan-file Path to your plan/spec file (required)" 270→ echo " mode 'plan' or 'build' (default: build)" 271→ echo " max-iterations Maximum loop iterations (default: unlimited)" 272→ echo "" 273→ echo -e "${YELLOW}Modes:${NC}" 274→ echo " plan Analyze codebase, create task list (runs once, then exits)" 275→ echo " build Implement tasks one at a time until RALPH_DONE" 276→ echo "" 277→ echo -e "${YELLOW}Examples:${NC}" 278→ echo " ralph ./feature.md # Build until done" 279→ echo " ralph ./feature.md plan # Plan only (creates task list, exits)" 280→ echo " ralph ./feature.md build 20 # Build, max 20 iterations" 281→ echo "" 282→ echo -e "${YELLOW}Exit Conditions:${NC}" 283→ echo " - Plan mode: Exits after 1 iteration when task list is created" 284→ echo " - Build mode: RALPH_DONE appears in _PROGRESS.md" 285→ echo " - Max iterations reached (if specified)" 286→ echo " - Ctrl+C" 287→ echo "" 288→ echo -e "${YELLOW}Progress File:${NC}" 289→ echo " Created as _PROGRESS.md in current directory" 290→ echo " This is the only artifact left in your repo" 291→ echo "" 292→ echo -e "${YELLOW}Updates:${NC}" 293→ echo " ralph update Update to latest version" 294→ echo " ralph update --check Check for updates without installing" 295→ echo " ralph update --list List all available versions" 296→ echo " ralph update Install specific version (e.g., 1.4.0)" 297→ echo " ralph rollback Rollback to previous version" 298→ echo "" 299→ echo -e "${YELLOW}Configuration:${NC}" 300→ echo " ralph config commit on Enable auto-commit (default)" 301→ echo " ralph config commit off Disable auto-commit" 302→ echo " ralph config commit status Show current setting" 303→ echo "" 304→ echo -e "${YELLOW}Plan File Directives:${NC}" 305→ echo " Add DO_NOT_COMMIT on its own line to disable commits for that plan" 306→ echo "" 307→ echo -e "${YELLOW}Notifications (optional):${NC}" 308→ echo " Supports Slack, Discord, Telegram, and custom scripts" 309→ echo " ralph notify setup Configure notification platforms" 310→ echo " ralph notify test Send a test notification" 311→ echo "" 312→ echo "More info: https://github.com/aaron777collins/portableralph" 313→ exit 0 314→} 315→ 316→version() { 317→ echo "PortableRalph v${VERSION}" 318→ exit 0 319→} 320→ 321→# Parse arguments 322→if [ $# -lt 1 ]; then 323→ usage 324→fi 325→ 326→# Handle help and version flags 327→if [ "$1" = "--help" ] || [ "$1" = "-h" ] || [ "$1" = "help" ]; then 328→ usage 329→fi 330→ 331→if [ "$1" = "--version" ] || [ "$1" = "-v" ]; then 332→ version 333→fi 334→ 335→if [ "$1" = "--test-notify" ] || [ "$1" = "--test-notifications" ]; then 336→ "$RALPH_DIR/notify.sh" --test 337→ exit 0 338→fi 339→ 340→# Handle update subcommand 341→if [ "$1" = "update" ]; then 342→ exec "$RALPH_DIR/update.sh" "${@:2}" 343→fi 344→ 345→# Handle rollback subcommand 346→if [ "$1" = "rollback" ]; then 347→ exec "$RALPH_DIR/update.sh" --rollback 348→fi 349→ 350→# Handle notify subcommand 351→if [ "$1" = "notify" ]; then 352→ case "${2:-}" in 353→ setup) 354→ exec "$RALPH_DIR/setup-notifications.sh" 355→ ;; 356→ test) 357→ exec "$RALPH_DIR/notify.sh" --test 358→ ;; 359→ "") 360→ echo -e "${YELLOW}Usage:${NC} ralph notify " 361→ echo "" 362→ echo -e "${YELLOW}Commands:${NC}" 363→ echo " setup Configure Slack, Discord, Telegram, or custom notifications" 364→ echo " test Send a test notification to all configured platforms" 365→ exit 1 366→ ;; 367→ *) 368→ echo -e "${RED}Unknown notify command: $2${NC}" 369→ echo "Run 'ralph notify' for available commands." 370→ exit 1 371→ ;; 372→ esac 373→fi 374→ 375→# Handle config subcommand 376→if [ "$1" = "config" ]; then 377→ CONFIG_FILE="$RALPH_CONFIG_FILE" 378→ 379→ # Helper to set a config value (handles both export and non-export patterns) 380→ set_config_value() { 381→ local key="$1" 382→ local value="$2" 383→ 384→ # Security: Escape special characters in value for safe sed usage 385→ # This prevents sed injection by escaping: / \ & newlines and special chars 386→ local escaped_value 387→ escaped_value=$(printf '%s\n' "$value" | sed -e 's/[\/&]/\\&/g' -e 's/$/\\/' | tr -d '\n' | sed 's/\\$//') 388→ 389→ if [ -f "$CONFIG_FILE" ]; then 390→ # Check if key exists (with or without export) 391→ if grep -qE "^(export )?${key}=" "$CONFIG_FILE" 2>/dev/null; then 392→ # Update existing (handle both patterns) 393→ # Use a temporary file for atomic operation 394→ local temp_file 395→ temp_file=$(mktemp) || { 396→ log_error "Failed to create temp file for config update" 397→ return 1 398→ } 399→ chmod 600 "$temp_file" 400→ trap 'rm -f "$temp_file" 2>/dev/null' RETURN 401→ 402→ # Process the file line by line to avoid sed injection 403→ while IFS= read -r line || [ -n "$line" ]; do 404→ if [[ "$line" =~ ^export\ ${key}= ]] || [[ "$line" =~ ^${key}= ]]; then 405→ echo "export ${key}=\"${escaped_value}\"" 406→ else 407→ echo "$line" 408→ fi 409→ done < "$CONFIG_FILE" > "$temp_file" 410→ 411→ mv "$temp_file" "$CONFIG_FILE" 412→ else 413→ # Append to existing file (preserve content) 414→ echo "" >> "$CONFIG_FILE" 415→ echo "# Auto-commit setting" >> "$CONFIG_FILE" 416→ echo "export ${key}=\"${escaped_value}\"" >> "$CONFIG_FILE" 417→ fi 418→ else 419→ # Create new file 420→ echo '# PortableRalph Configuration' > "$CONFIG_FILE" 421→ echo "# Generated on $(date)" >> "$CONFIG_FILE" 422→ echo "" >> "$CONFIG_FILE" 423→ echo "export ${key}=\"${escaped_value}\"" >> "$CONFIG_FILE" 424→ chmod 600 "$CONFIG_FILE" 425→ fi 426→ } 427→ 428→ case "${2:-}" in 429→ commit) 430→ case "${3:-}" in 431→ on|true|yes|1) 432→ set_config_value "RALPH_AUTO_COMMIT" "true" 433→ echo -e "${GREEN}Auto-commit enabled${NC}" 434→ echo "Ralph will commit after each iteration." 435→ ;; 436→ off|false|no|0) 437→ set_config_value "RALPH_AUTO_COMMIT" "false" 438→ echo -e "${YELLOW}Auto-commit disabled${NC}" 439→ echo "Ralph will NOT commit after each iteration." 440→ echo "You can also add DO_NOT_COMMIT on its own line in your plan file." 441→ ;; 442→ status|"") 443→ echo -e "${YELLOW}Auto-commit setting:${NC}" 444→ if [ "$RALPH_AUTO_COMMIT" = "true" ]; then 445→ echo -e " Current: ${GREEN}enabled${NC} (commits after each iteration)" 446→ else 447→ echo -e " Current: ${YELLOW}disabled${NC} (no automatic commits)" 448→ fi 449→ echo "" 450→ echo -e "${YELLOW}Usage:${NC}" 451→ echo " ralph config commit on Enable auto-commit (default)" 452→ echo " ralph config commit off Disable auto-commit" 453→ echo "" 454→ echo -e "${YELLOW}Plan file override:${NC}" 455→ echo " Add DO_NOT_COMMIT on its own line to disable commits for that plan" 456→ ;; 457→ *) 458→ echo -e "${RED}Unknown option: $3${NC}" 459→ echo "Usage: ralph config commit " 460→ exit 1 461→ ;; 462→ esac 463→ exit 0 464→ ;; 465→ "") 466→ echo -e "${YELLOW}Usage:${NC} ralph config " 467→ echo "" 468→ echo -e "${YELLOW}Settings:${NC}" 469→ echo " commit Configure auto-commit behavior" 470→ exit 1 471→ ;; 472→ *) 473→ echo -e "${RED}Unknown config setting: $2${NC}" 474→ echo "Run 'ralph config' for available settings." 475→ exit 1 476→ ;; 477→ esac 478→fi 479→ 480→PLAN_FILE="$1" 481→MODE="${2:-build}" 482→MAX_ITERATIONS="${3:-${MAX_ITERATIONS_DEFAULT:-0}}" 483→ 484→# Validate plan file path and existence 485→if ! validate_file_path "$PLAN_FILE" "Plan file"; then 486→ exit 1 487→fi 488→ 489→if [ ! -f "$PLAN_FILE" ]; then 490→ log_error "Plan file not found: $PLAN_FILE" 491→ exit 1 492→fi 493→ 494→# Validate mode 495→if [ "$MODE" != "plan" ] && [ "$MODE" != "build" ]; then 496→ log_error "Mode must be 'plan' or 'build', got: $MODE" 497→ echo "Run 'ralph --help' for usage information." 498→ exit 1 499→fi 500→ 501→# Validate max iterations 502→if [ "$MAX_ITERATIONS" != "0" ]; then 503→ max_iter_min="${MAX_ITERATIONS_MIN:-1}" 504→ max_iter_max="${MAX_ITERATIONS_MAX:-10000}" 505→ if ! validate_numeric "$MAX_ITERATIONS" "Max iterations" "$max_iter_min" "$max_iter_max"; then 506→ exit 1 507→ fi 508→fi 509→ 510→# Derive progress file name from plan file 511→PLAN_BASENAME=$(basename "$PLAN_FILE" .md) 512→PROGRESS_FILE="${PLAN_BASENAME}_PROGRESS.md" 513→PLAN_FILE_ABS=$(realpath "$PLAN_FILE") 514→ 515→# Select prompt template 516→if [ "$MODE" = "plan" ]; then 517→ PROMPT_TEMPLATE="$RALPH_DIR/PROMPT_plan.md" 518→else 519→ PROMPT_TEMPLATE="$RALPH_DIR/PROMPT_build.md" 520→fi 521→ 522→# Verify prompt template exists 523→if [ ! -f "$PROMPT_TEMPLATE" ]; then 524→ echo -e "${RED}Error: Prompt template not found: $PROMPT_TEMPLATE${NC}" 525→ echo "Run the setup script or create the template manually." 526→ exit 1 527→fi 528→ 529→# Compute commit setting (check env var and plan file) 530→# DO_NOT_COMMIT in plan file takes precedence for that specific plan 531→SHOULD_COMMIT="true" 532→COMMIT_DISABLED_REASON="" 533→if [ "$RALPH_AUTO_COMMIT" != "true" ]; then 534→ SHOULD_COMMIT="false" 535→ COMMIT_DISABLED_REASON="(disabled via config)" 536→elif should_skip_commit_from_plan "$PLAN_FILE"; then 537→ SHOULD_COMMIT="false" 538→ COMMIT_DISABLED_REASON="(DO_NOT_COMMIT in plan)" 539→fi 540→ 541→# Print banner 542→echo "" 543→echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 544→echo -e "${GREEN} RALPH - Autonomous AI Development Loop${NC}" 545→echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 546→echo -e " Plan: ${YELLOW}$PLAN_FILE${NC}" 547→echo -e " Mode: ${YELLOW}$MODE${NC}" 548→echo -e " Progress: ${YELLOW}$PROGRESS_FILE${NC}" 549→[ "$MAX_ITERATIONS" -gt 0 ] && echo -e " Max Iter: ${YELLOW}$MAX_ITERATIONS${NC}" 550→if [ "$SHOULD_COMMIT" = "true" ]; then 551→ echo -e " Commit: ${GREEN}enabled${NC}" 552→else 553→ echo -e " Commit: ${YELLOW}disabled${NC} ${COMMIT_DISABLED_REASON}" 554→fi 555→if notifications_enabled; then 556→ PLATFORMS="" 557→ [ -n "${RALPH_SLACK_WEBHOOK_URL:-}" ] && PLATFORMS="${PLATFORMS}Slack " 558→ [ -n "${RALPH_DISCORD_WEBHOOK_URL:-}" ] && PLATFORMS="${PLATFORMS}Discord " 559→ [ -n "${RALPH_TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${RALPH_TELEGRAM_CHAT_ID:-}" ] && PLATFORMS="${PLATFORMS}Telegram " 560→ [ -n "${RALPH_CUSTOM_NOTIFY_SCRIPT:-}" ] && PLATFORMS="${PLATFORMS}Custom " 561→ echo -e " Notify: ${GREEN}${PLATFORMS}${NC}" 562→else 563→ echo -e " Notify: ${YELLOW}disabled${NC} (run 'ralph notify setup')" 564→fi 565→echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 566→echo "" 567→echo -e "${YELLOW}Exit conditions:${NC}" 568→if [ "$MODE" = "plan" ]; then 569→ echo " - Planning completes when task list is created (Status: IN_PROGRESS)" 570→ echo " - Plan mode runs once then exits automatically" 571→else 572→ echo " - RALPH_DONE in $PROGRESS_FILE signals all tasks complete (set by AI)" 573→fi 574→echo " - Press Ctrl+C to stop manually" 575→echo "" 576→ 577→# Send start notification to Slack 578→REPO_NAME=$(basename "$(pwd)") 579→notify ":rocket: *Ralph Started*\n\`\`\`Plan: $PLAN_BASENAME\nMode: $MODE\nRepo: $REPO_NAME\`\`\`" ":rocket:" 580→ 581→# Initialize progress file if it doesn't exist 582→if [ ! -f "$PROGRESS_FILE" ]; then 583→ echo "# Progress: $PLAN_BASENAME" > "$PROGRESS_FILE" 584→ echo "" >> "$PROGRESS_FILE" 585→ echo "Started: $(date)" >> "$PROGRESS_FILE" 586→ echo "" >> "$PROGRESS_FILE" 587→ echo "## Status" >> "$PROGRESS_FILE" 588→ echo "" >> "$PROGRESS_FILE" 589→ echo "IN_PROGRESS" >> "$PROGRESS_FILE" 590→ echo "" >> "$PROGRESS_FILE" 591→ echo "## Tasks Completed" >> "$PROGRESS_FILE" 592→ echo "" >> "$PROGRESS_FILE" 593→fi 594→ 595→ITERATION=0 596→ 597→# Check for completion 598→# Uses -x to match whole lines only, preventing false positives from 599→# instructional text like "DO NOT set RALPH_DONE" in the progress file 600→is_done() { 601→ if [ -f "$PROGRESS_FILE" ]; then 602→ grep -qx "RALPH_DONE" "$PROGRESS_FILE" 2>/dev/null && return 0 603→ fi 604→ return 1 605→} 606→ 607→# ============================================================================ 608→# CONCURRENCY PROTECTION (Fix for GitHub Issue #1) 609→# ============================================================================ 610→# Prevent multiple Ralph instances from running on the same plan file 611→# This fixes API Error 400 due to tool use race conditions 612→ 613→# Generate lock file path based on plan file (unique per plan) 614→PLAN_HASH=$(echo "$PLAN_FILE_ABS" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "$PLAN_BASENAME") 615→LOCK_FILE="${TEMP_DIR:-/tmp}/ralph_${PLAN_HASH}.lock" 616→ 617→# Cleanup function for graceful exit 618→cleanup_lock() { 619→ if [ -n "${LOCK_FILE:-}" ]; then 620→ release_lock "$LOCK_FILE" 2>/dev/null || true 621→ fi 622→} 623→ 624→# Set up trap to release lock on exit (normal or error) 625→trap cleanup_lock EXIT INT TERM 626→ 627→# Acquire lock before starting the main loop 628→if ! acquire_lock "$LOCK_FILE"; then 629→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 630→ echo -e "${RED} ERROR: Another Ralph instance is already running this plan${NC}" 631→ echo -e "${RED} Plan: $PLAN_FILE${NC}" 632→ echo -e "${RED} Lock: $LOCK_FILE${NC}" 633→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 634→ echo "" 635→ echo -e "${YELLOW}To force a new instance, remove the lock file:${NC}" 636→ echo -e " rm -f $LOCK_FILE" 637→ exit 1 638→fi 639→ 640→echo -e "${GREEN}Lock acquired: $LOCK_FILE${NC}" 641→ 642→# Main loop 643→while true; do 644→ # Check exit conditions 645→ if is_done; then 646→ echo "" 647→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 648→ echo -e "${GREEN} RALPH_DONE - Work complete!${NC}" 649→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 650→ notify ":white_check_mark: *Ralph Complete!*\n\`\`\`Plan: $PLAN_BASENAME\nIterations: $ITERATION\nRepo: $REPO_NAME\`\`\`" ":white_check_mark:" 651→ break 652→ fi 653→ 654→ if [ "$MAX_ITERATIONS" -gt 0 ] && [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then 655→ echo "" 656→ echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 657→ echo -e "${YELLOW} Max iterations reached: $MAX_ITERATIONS${NC}" 658→ echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 659→ notify ":warning: *Ralph Stopped*\n\`\`\`Plan: $PLAN_BASENAME\nReason: Max iterations reached ($MAX_ITERATIONS)\nRepo: $REPO_NAME\`\`\`" ":warning:" 660→ break 661→ fi 662→ 663→ ITERATION=$((ITERATION + 1)) 664→ echo "" 665→ echo -e "${BLUE}══════════════════ ITERATION $ITERATION ══════════════════${NC}" 666→ echo "" 667→ 668→ # Build the prompt with substitutions (safely escape for sed to prevent injection) 669→ # Escape special sed characters: & \ / newlines 670→ escape_sed() { 671→ local str="$1" 672→ # Escape backslashes first, then forward slashes, then ampersands 673→ str="${str//\\/\\\\}" 674→ str="${str//\//\\/}" 675→ str="${str//&/\\&}" 676→ printf '%s' "$str" 677→ } 678→ 679→ # Variables for sed escaping (not using local since we're in main loop, not a function) 680→ safe_plan_file=$(escape_sed "$PLAN_FILE_ABS") 681→ safe_progress_file=$(escape_sed "$PROGRESS_FILE") 682→ safe_plan_name=$(escape_sed "$PLAN_BASENAME") 683→ safe_should_commit=$(escape_sed "$SHOULD_COMMIT") 684→ 685→ PROMPT=$(cat "$PROMPT_TEMPLATE" | \ 686→ sed "s|\${PLAN_FILE}|$safe_plan_file|g" | \ 687→ sed "s|\${PROGRESS_FILE}|$safe_progress_file|g" | \ 688→ sed "s|\${PLAN_NAME}|$safe_plan_name|g" | \ 689→ sed "s|\${AUTO_COMMIT}|$safe_should_commit|g") 690→ 691→ # Run Claude with retry logic (configurable attempts with exponential backoff) 692→ max_claude_retries="${CLAUDE_MAX_RETRIES:-3}" 693→ claude_retry_delay="${CLAUDE_RETRY_DELAY:-5}" 694→ claude_attempt=1 695→ claude_success=false 696→ claude_exit_code=0 697→ claude_errors="" 698→ error_detected=false 699→ error_type="unknown" 700→ 701→ while [ $claude_attempt -le $max_claude_retries ]; do 702→ if [ $claude_attempt -gt 1 ]; then 703→ echo -e "${YELLOW}Retrying Claude CLI (attempt $claude_attempt/$max_claude_retries) in ${claude_retry_delay}s...${NC}" 704→ sleep $claude_retry_delay 705→ fi 706→ 707→ # Reset for this attempt 708→ claude_exit_code=0 709→ error_detected=false 710→ error_type="unknown" 711→ claude_output_file=$(mktemp) || { 712→ log_error "Failed to create temp file for Claude output" 713→ exit 1 714→ } 715→ claude_error_file=$(mktemp) || { 716→ rm -f "$claude_output_file" 717→ log_error "Failed to create temp file for Claude errors" 718→ exit 1 719→ } 720→ chmod 600 "$claude_output_file" "$claude_error_file" 721→ 722→ # Run Claude 723→ echo "$PROMPT" | claude -p \ 724→ --dangerously-skip-permissions \ 725→ --model sonnet \ 726→ --verbose > "$claude_output_file" 2>"$claude_error_file" || claude_exit_code=$? 727→ 728→ # Display output on first attempt or final retry 729→ if [ $claude_attempt -eq 1 ] || [ $claude_attempt -eq $max_claude_retries ]; then 730→ if [ -f "$claude_output_file" ]; then 731→ cat "$claude_output_file" 732→ fi 733→ fi 734→ 735→ # Capture any error output 736→ claude_errors="" 737→ if [ -f "$claude_error_file" ]; then 738→ claude_errors=$(cat "$claude_error_file" 2>/dev/null || echo "") 739→ fi 740→ 741→ # Check for known error patterns even if exit code is 0 742→ if [ $claude_exit_code -ne 0 ]; then 743→ error_detected=true 744→ case $claude_exit_code in 745→ 1) error_type="general error" ;; 746→ 2) error_type="CLI usage error" ;; 747→ 130) error_type="interrupted by user (Ctrl+C)" ;; 748→ *) error_type="exit code $claude_exit_code" ;; 749→ esac 750→ fi 751→ 752→ # Check error output for known patterns 753→ if [ -n "$claude_errors" ]; then 754→ if echo "$claude_errors" | grep -qi "authentication\|unauthorized\|api.*key"; then 755→ error_detected=true 756→ error_type="authentication failure" 757→ elif echo "$claude_errors" | grep -qi "rate.*limit\|too.*many.*requests"; then 758→ error_detected=true 759→ error_type="rate limit exceeded" 760→ elif echo "$claude_errors" | grep -qi "network\|connection\|timeout"; then 761→ error_detected=true 762→ error_type="network error" 763→ elif echo "$claude_errors" | grep -qi "not.*found\|command.*not.*found"; then 764→ error_detected=true 765→ error_type="Claude CLI not found or not in PATH" 766→ # GitHub Issue #1: Detect API 400 errors from tool use concurrency 767→ elif echo "$claude_errors" | grep -qi "400\|bad.*request\|tool.*use\|concurrency"; then 768→ error_detected=true 769→ error_type="API 400 error (tool use concurrency)" 770→ fi 771→ fi 772→ 773→ # Clean up temp files 774→ rm -f "$claude_output_file" "$claude_error_file" 775→ 776→ # Check if we succeeded 777→ if [ "$error_detected" = false ]; then 778→ claude_success=true 779→ break 780→ fi 781→ 782→ # Log the attempt error 783→ log_error "Claude CLI error at iteration $ITERATION (attempt $claude_attempt/$max_claude_retries): $error_type" 784→ if [ -n "$claude_errors" ]; then 785→ err_truncate="${ERROR_DETAILS_TRUNCATE_LENGTH:-500}" 786→ log_error "Error details: ${claude_errors:0:$err_truncate}" 787→ fi 788→ 789→ # For non-retryable errors, don't retry 790→ if [[ "$error_type" =~ "authentication"|"CLI usage error"|"interrupted by user"|"not found" ]]; then 791→ echo -e "${RED}Non-retryable error detected: $error_type${NC}" 792→ break 793→ fi 794→ 795→ # Increment retry counter and increase backoff with jitter 796→ claude_attempt=$((claude_attempt + 1)) 797→ if [ $claude_attempt -le $max_claude_retries ]; then 798→ # Exponential backoff: 5s, 10s, 20s with random jitter (0-2s) 799→ # Jitter prevents "thundering herd" when multiple instances retry simultaneously 800→ # This is a key fix for GitHub Issue #1 (concurrency issues) 801→ jitter=$((RANDOM % 3)) 802→ claude_retry_delay=$(( (claude_retry_delay * 2) + jitter )) 803→ fi 804→ done 805→ 806→ # If all retries failed, stop iterations 807→ if [ "$claude_success" = false ]; then 808→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 809→ echo -e "${RED} Claude CLI Error (after $claude_attempt attempts): $error_type${NC}" 810→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 811→ 812→ # Check if this is a transient error that might benefit from manual retry 813→ # API 400 (tool use concurrency) is now retryable with proper locking 814→ if [[ "$error_type" =~ "rate limit"|"network"|"timeout"|"API 400" ]]; then 815→ echo -e "${YELLOW}This appears to be a transient error.${NC}" 816→ echo -e "${YELLOW}You may want to retry in a few minutes.${NC}" 817→ fi 818→ 819→ # Send error notification and log 820→ log_error "Stopping Ralph due to Claude CLI failure at iteration $ITERATION after $claude_attempt attempts" 821→ notify ":x: *Ralph Error*\n\`\`\`Plan: $PLAN_BASENAME\nIteration: $ITERATION\nError: $error_type (after $claude_attempt retries)\nRepo: $REPO_NAME\`\`\`" ":x:" 822→ exit $claude_exit_code 823→ fi 824→ 825→ echo "" 826→ echo -e "${GREEN}Iteration $ITERATION complete${NC}" 827→ 828→ # Plan mode: exit after one iteration 829→ if [ "$MODE" = "plan" ]; then 830→ echo "" 831→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 832→ echo -e "${GREEN} Planning complete! Task list created in $PROGRESS_FILE${NC}" 833→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 834→ echo "" 835→ echo -e "Next step: Run ${YELLOW}ralph $PLAN_FILE build${NC} to implement tasks" 836→ notify ":clipboard: *Ralph Planning Complete!*\n\`\`\`Plan: $PLAN_BASENAME\nTask list created in: $PROGRESS_FILE\nRepo: $REPO_NAME\`\`\`" ":clipboard:" 837→ break 838→ fi 839→ 840→ # Send iteration notification (configurable frequency via RALPH_NOTIFY_FREQUENCY) 841→ notify_default="${NOTIFY_FREQUENCY_DEFAULT:-5}" 842→ NOTIFY_FREQ="${RALPH_NOTIFY_FREQUENCY:-$notify_default}" 843→ # Validate notification frequency 844→ notify_min="${NOTIFY_FREQUENCY_MIN:-1}" 845→ notify_max="${NOTIFY_FREQUENCY_MAX:-100}" 846→ if ! validate_numeric "$NOTIFY_FREQ" "RALPH_NOTIFY_FREQUENCY" "$notify_min" "$notify_max"; then 847→ NOTIFY_FREQ="$notify_default" 848→ log_error "Invalid RALPH_NOTIFY_FREQUENCY, using default: $notify_default" 849→ fi 850→ if [ "$ITERATION" -eq 1 ] || [ $((ITERATION % NOTIFY_FREQ)) -eq 0 ]; then 851→ notify ":gear: *Ralph Progress*: Iteration $ITERATION completed\n\`Plan: $PLAN_BASENAME\`" ":gear:" 852→ fi 853→ 854→ # Small delay between iterations 855→ iter_delay="${ITERATION_DELAY:-2}" 856→ sleep "$iter_delay" 857→done 858→ 859→echo "" 860→echo "Total iterations: $ITERATION" 861→echo "Progress file: $PROGRESS_FILE" 862→

Summary

Summary