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→# Model setting (default: sonnet) 175→# Can be set via: export RALPH_MODEL="claude-opus-4-6" in ~/.ralph.env 176→RALPH_MODEL="${RALPH_MODEL:-sonnet}" 177→ 178→# Check if plan file contains DO_NOT_COMMIT directive 179→# Skips content inside ``` code blocks to avoid false positives 180→should_skip_commit_from_plan() { 181→ local plan_file="$1" 182→ [ ! -f "$plan_file" ] && return 1 183→ 184→ # Use awk to skip code blocks and find DO_NOT_COMMIT on its own line 185→ # Handles whitespace before/after the directive 186→ awk ' 187→ /^```/ { in_code = !in_code; next } 188→ !in_code && /^[[:space:]]*DO_NOT_COMMIT[[:space:]]*$/ { found=1; exit } 189→ END { exit !found } 190→ ' "$plan_file" 191→} 192→ 193→# Notification helper with retry logic and error logging 194→notify() { 195→ local message="$1" 196→ local emoji="${2:-}" 197→ local max_retries="${NOTIFY_MAX_RETRIES:-3}" 198→ local retry_delay="${NOTIFY_RETRY_DELAY:-2}" 199→ local attempt=1 200→ local notification_log="${LOG_DIR}/ralph_notifications_$(date '+%Y%m%d').log" 201→ 202→ # Skip if LOG_DIR is not available (use platform-appropriate null device) 203→ if [ -z "$LOG_DIR" ] || [ ! -d "$LOG_DIR" ]; then 204→ if command -v get_null_device &>/dev/null; then 205→ notification_log="$(get_null_device)" 206→ else 207→ notification_log="/dev/null" 208→ fi 209→ fi 210→ 211→ while [ $attempt -le $max_retries ]; do 212→ local notify_output 213→ local notify_exit=0 214→ 215→ # Capture output and exit code 216→ notify_output=$("$RALPH_DIR/notify.sh" "$message" "$emoji" 2>&1) || notify_exit=$? 217→ 218→ # Log the output with proper error handling (check for null device) 219→ local null_dev="/dev/null" 220→ if command -v get_null_device &>/dev/null; then 221→ null_dev="$(get_null_device)" 222→ fi 223→ if [ "$notification_log" != "$null_dev" ] && [ "$notification_log" != "NUL" ]; then 224→ if ! echo "[$(date '+%Y-%m-%d %H:%M:%S')] Attempt $attempt: $notify_output" >> "$notification_log" 2>/dev/null; then 225→ # If logging fails, report to stderr but don't fail the notification 226→ echo "Warning: Failed to write to notification log: $notification_log" >&2 227→ fi 228→ fi 229→ 230→ if [ $notify_exit -eq 0 ]; then 231→ return 0 232→ fi 233→ 234→ if [ $attempt -lt $max_retries ]; then 235→ log_error "Notification attempt $attempt/$max_retries failed (exit $notify_exit), retrying in ${retry_delay}s..." 236→ sleep $retry_delay 237→ # Exponential backoff 238→ retry_delay=$((retry_delay * 2)) 239→ else 240→ local msg_truncate="${MESSAGE_TRUNCATE_LENGTH:-100}" 241→ log_error "Notification failed after $max_retries attempts (exit $notify_exit): ${message:0:$msg_truncate}..." 242→ fi 243→ 244→ attempt=$((attempt + 1)) 245→ done 246→ 247→ return 1 # Failed after all retries 248→} 249→ 250→# Check if any notification platform is configured 251→notifications_enabled() { 252→ [ -n "${RALPH_SLACK_WEBHOOK_URL:-}" ] || \ 253→ [ -n "${RALPH_DISCORD_WEBHOOK_URL:-}" ] || \ 254→ ([ -n "${RALPH_TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${RALPH_TELEGRAM_CHAT_ID:-}" ]) || \ 255→ [ -n "${RALPH_CUSTOM_NOTIFY_SCRIPT:-}" ] 256→} 257→ 258→usage() { 259→ echo -e "${GREEN}PortableRalph${NC} v${VERSION} - Autonomous AI Development Loop" 260→ echo "" 261→ echo -e "${YELLOW}Usage:${NC}" 262→ echo " ralph [mode] [max-iterations]" 263→ echo " ralph update [--check|--list|]" 264→ echo " ralph rollback" 265→ echo " ralph config " 266→ echo " ralph notify " 267→ echo " ralph --help | -h" 268→ echo " ralph --version | -v" 269→ echo "" 270→ echo -e "${YELLOW}Full path:${NC} ~/ralph/ralph.sh (alias: ralph)" 271→ echo "" 272→ echo -e "${YELLOW}Arguments:${NC}" 273→ echo " plan-file Path to your plan/spec file (required)" 274→ echo " mode 'plan' or 'build' (default: build)" 275→ echo " max-iterations Maximum loop iterations (default: unlimited)" 276→ echo "" 277→ echo -e "${YELLOW}Modes:${NC}" 278→ echo " plan Analyze codebase, create task list (runs once, then exits)" 279→ echo " build Implement tasks one at a time until RALPH_DONE" 280→ echo "" 281→ echo -e "${YELLOW}Examples:${NC}" 282→ echo " ralph ./feature.md # Build until done" 283→ echo " ralph ./feature.md plan # Plan only (creates task list, exits)" 284→ echo " ralph ./feature.md build 20 # Build, max 20 iterations" 285→ echo "" 286→ echo -e "${YELLOW}Exit Conditions:${NC}" 287→ echo " - Plan mode: Exits after 1 iteration when task list is created" 288→ echo " - Build mode: RALPH_DONE appears in _PROGRESS.md" 289→ echo " - Max iterations reached (if specified)" 290→ echo " - Ctrl+C" 291→ echo "" 292→ echo -e "${YELLOW}Progress File:${NC}" 293→ echo " Created as _PROGRESS.md in current directory" 294→ echo " This is the only artifact left in your repo" 295→ echo "" 296→ echo -e "${YELLOW}Updates:${NC}" 297→ echo " ralph update Update to latest version" 298→ echo " ralph update --check Check for updates without installing" 299→ echo " ralph update --list List all available versions" 300→ echo " ralph update Install specific version (e.g., 1.4.0)" 301→ echo " ralph rollback Rollback to previous version" 302→ echo "" 303→ echo -e "${YELLOW}Configuration:${NC}" 304→ echo " ralph config commit on Enable auto-commit (default)" 305→ echo " ralph config commit off Disable auto-commit" 306→ echo " ralph config commit status Show current setting" 307→ echo "" 308→ echo -e "${YELLOW}Plan File Directives:${NC}" 309→ echo " Add DO_NOT_COMMIT on its own line to disable commits for that plan" 310→ echo "" 311→ echo -e "${YELLOW}Notifications (optional):${NC}" 312→ echo " Supports Slack, Discord, Telegram, and custom scripts" 313→ echo " ralph notify setup Configure notification platforms" 314→ echo " ralph notify test Send a test notification" 315→ echo "" 316→ echo "More info: https://github.com/aaron777collins/portableralph" 317→ exit 0 318→} 319→ 320→version() { 321→ echo "PortableRalph v${VERSION}" 322→ exit 0 323→} 324→ 325→# Parse arguments 326→if [ $# -lt 1 ]; then 327→ usage 328→fi 329→ 330→# Handle help and version flags 331→if [ "$1" = "--help" ] || [ "$1" = "-h" ] || [ "$1" = "help" ]; then 332→ usage 333→fi 334→ 335→if [ "$1" = "--version" ] || [ "$1" = "-v" ]; then 336→ version 337→fi 338→ 339→if [ "$1" = "--test-notify" ] || [ "$1" = "--test-notifications" ]; then 340→ "$RALPH_DIR/notify.sh" --test 341→ exit 0 342→fi 343→ 344→# Handle update subcommand 345→if [ "$1" = "update" ]; then 346→ exec "$RALPH_DIR/update.sh" "${@:2}" 347→fi 348→ 349→# Handle rollback subcommand 350→if [ "$1" = "rollback" ]; then 351→ exec "$RALPH_DIR/update.sh" --rollback 352→fi 353→ 354→# Handle notify subcommand 355→if [ "$1" = "notify" ]; then 356→ case "${2:-}" in 357→ setup) 358→ exec "$RALPH_DIR/setup-notifications.sh" 359→ ;; 360→ test) 361→ exec "$RALPH_DIR/notify.sh" --test 362→ ;; 363→ "") 364→ echo -e "${YELLOW}Usage:${NC} ralph notify " 365→ echo "" 366→ echo -e "${YELLOW}Commands:${NC}" 367→ echo " setup Configure Slack, Discord, Telegram, or custom notifications" 368→ echo " test Send a test notification to all configured platforms" 369→ exit 1 370→ ;; 371→ *) 372→ echo -e "${RED}Unknown notify command: $2${NC}" 373→ echo "Run 'ralph notify' for available commands." 374→ exit 1 375→ ;; 376→ esac 377→fi 378→ 379→# Handle config subcommand 380→if [ "$1" = "config" ]; then 381→ CONFIG_FILE="$RALPH_CONFIG_FILE" 382→ 383→ # Helper to set a config value (handles both export and non-export patterns) 384→ set_config_value() { 385→ local key="$1" 386→ local value="$2" 387→ 388→ # Security: Escape special characters in value for safe sed usage 389→ # This prevents sed injection by escaping: / \ & newlines and special chars 390→ local escaped_value 391→ escaped_value=$(printf '%s\n' "$value" | sed -e 's/[\/&]/\\&/g' -e 's/$/\\/' | tr -d '\n' | sed 's/\\$//') 392→ 393→ if [ -f "$CONFIG_FILE" ]; then 394→ # Check if key exists (with or without export) 395→ if grep -qE "^(export )?${key}=" "$CONFIG_FILE" 2>/dev/null; then 396→ # Update existing (handle both patterns) 397→ # Use a temporary file for atomic operation 398→ local temp_file 399→ temp_file=$(mktemp) || { 400→ log_error "Failed to create temp file for config update" 401→ return 1 402→ } 403→ chmod 600 "$temp_file" 404→ trap 'rm -f "$temp_file" 2>/dev/null' RETURN 405→ 406→ # Process the file line by line to avoid sed injection 407→ while IFS= read -r line || [ -n "$line" ]; do 408→ if [[ "$line" =~ ^export\ ${key}= ]] || [[ "$line" =~ ^${key}= ]]; then 409→ echo "export ${key}=\"${escaped_value}\"" 410→ else 411→ echo "$line" 412→ fi 413→ done < "$CONFIG_FILE" > "$temp_file" 414→ 415→ mv "$temp_file" "$CONFIG_FILE" 416→ else 417→ # Append to existing file (preserve content) 418→ echo "" >> "$CONFIG_FILE" 419→ echo "# Auto-commit setting" >> "$CONFIG_FILE" 420→ echo "export ${key}=\"${escaped_value}\"" >> "$CONFIG_FILE" 421→ fi 422→ else 423→ # Create new file 424→ echo '# PortableRalph Configuration' > "$CONFIG_FILE" 425→ echo "# Generated on $(date)" >> "$CONFIG_FILE" 426→ echo "" >> "$CONFIG_FILE" 427→ echo "export ${key}=\"${escaped_value}\"" >> "$CONFIG_FILE" 428→ chmod 600 "$CONFIG_FILE" 429→ fi 430→ } 431→ 432→ case "${2:-}" in 433→ commit) 434→ case "${3:-}" in 435→ on|true|yes|1) 436→ set_config_value "RALPH_AUTO_COMMIT" "true" 437→ echo -e "${GREEN}Auto-commit enabled${NC}" 438→ echo "Ralph will commit after each iteration." 439→ ;; 440→ off|false|no|0) 441→ set_config_value "RALPH_AUTO_COMMIT" "false" 442→ echo -e "${YELLOW}Auto-commit disabled${NC}" 443→ echo "Ralph will NOT commit after each iteration." 444→ echo "You can also add DO_NOT_COMMIT on its own line in your plan file." 445→ ;; 446→ status|"") 447→ echo -e "${YELLOW}Auto-commit setting:${NC}" 448→ if [ "$RALPH_AUTO_COMMIT" = "true" ]; then 449→ echo -e " Current: ${GREEN}enabled${NC} (commits after each iteration)" 450→ else 451→ echo -e " Current: ${YELLOW}disabled${NC} (no automatic commits)" 452→ fi 453→ echo "" 454→ echo -e "${YELLOW}Usage:${NC}" 455→ echo " ralph config commit on Enable auto-commit (default)" 456→ echo " ralph config commit off Disable auto-commit" 457→ echo "" 458→ echo -e "${YELLOW}Plan file override:${NC}" 459→ echo " Add DO_NOT_COMMIT on its own line to disable commits for that plan" 460→ ;; 461→ *) 462→ echo -e "${RED}Unknown option: $3${NC}" 463→ echo "Usage: ralph config commit " 464→ exit 1 465→ ;; 466→ esac 467→ exit 0 468→ ;; 469→ "") 470→ echo -e "${YELLOW}Usage:${NC} ralph config " 471→ echo "" 472→ echo -e "${YELLOW}Settings:${NC}" 473→ echo " commit Configure auto-commit behavior" 474→ exit 1 475→ ;; 476→ *) 477→ echo -e "${RED}Unknown config setting: $2${NC}" 478→ echo "Run 'ralph config' for available settings." 479→ exit 1 480→ ;; 481→ esac 482→fi 483→ 484→PLAN_FILE="$1" 485→MODE="${2:-build}" 486→MAX_ITERATIONS="${3:-${MAX_ITERATIONS_DEFAULT:-0}}" 487→ 488→# Validate plan file path and existence 489→if ! validate_file_path "$PLAN_FILE" "Plan file"; then 490→ exit 1 491→fi 492→ 493→if [ ! -f "$PLAN_FILE" ]; then 494→ log_error "Plan file not found: $PLAN_FILE" 495→ exit 1 496→fi 497→ 498→# Validate mode 499→if [ "$MODE" != "plan" ] && [ "$MODE" != "build" ]; then 500→ log_error "Mode must be 'plan' or 'build', got: $MODE" 501→ echo "Run 'ralph --help' for usage information." 502→ exit 1 503→fi 504→ 505→# Validate max iterations 506→if [ "$MAX_ITERATIONS" != "0" ]; then 507→ max_iter_min="${MAX_ITERATIONS_MIN:-1}" 508→ max_iter_max="${MAX_ITERATIONS_MAX:-10000}" 509→ if ! validate_numeric "$MAX_ITERATIONS" "Max iterations" "$max_iter_min" "$max_iter_max"; then 510→ exit 1 511→ fi 512→fi 513→ 514→# Derive progress file name from plan file 515→PLAN_BASENAME=$(basename "$PLAN_FILE" .md) 516→PROGRESS_FILE="${PLAN_BASENAME}_PROGRESS.md" 517→GUARDRAILS_FILE="RALPH_GUARDRAILS.md" 518→PLAN_FILE_ABS=$(realpath "$PLAN_FILE") 519→ 520→# Select prompt template 521→if [ "$MODE" = "plan" ]; then 522→ PROMPT_TEMPLATE="$RALPH_DIR/PROMPT_plan.md" 523→else 524→ PROMPT_TEMPLATE="$RALPH_DIR/PROMPT_build.md" 525→fi 526→ 527→# Verify prompt template exists 528→if [ ! -f "$PROMPT_TEMPLATE" ]; then 529→ echo -e "${RED}Error: Prompt template not found: $PROMPT_TEMPLATE${NC}" 530→ echo "Run the setup script or create the template manually." 531→ exit 1 532→fi 533→ 534→# Compute commit setting (check env var and plan file) 535→# DO_NOT_COMMIT in plan file takes precedence for that specific plan 536→SHOULD_COMMIT="true" 537→COMMIT_DISABLED_REASON="" 538→if [ "$RALPH_AUTO_COMMIT" != "true" ]; then 539→ SHOULD_COMMIT="false" 540→ COMMIT_DISABLED_REASON="(disabled via config)" 541→elif should_skip_commit_from_plan "$PLAN_FILE"; then 542→ SHOULD_COMMIT="false" 543→ COMMIT_DISABLED_REASON="(DO_NOT_COMMIT in plan)" 544→fi 545→ 546→# Print banner 547→echo "" 548→echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 549→echo -e "${GREEN} RALPH - Autonomous AI Development Loop${NC}" 550→echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 551→echo -e " Plan: ${YELLOW}$PLAN_FILE${NC}" 552→echo -e " Mode: ${YELLOW}$MODE${NC}" 553→echo -e " Progress: ${YELLOW}$PROGRESS_FILE${NC}" 554→[ "$MAX_ITERATIONS" -gt 0 ] && echo -e " Max Iter: ${YELLOW}$MAX_ITERATIONS${NC}" 555→echo -e " Model: ${YELLOW}$RALPH_MODEL${NC}" 556→if [ "$SHOULD_COMMIT" = "true" ]; then 557→ echo -e " Commit: ${GREEN}enabled${NC}" 558→else 559→ echo -e " Commit: ${YELLOW}disabled${NC} ${COMMIT_DISABLED_REASON}" 560→fi 561→if notifications_enabled; then 562→ PLATFORMS="" 563→ [ -n "${RALPH_SLACK_WEBHOOK_URL:-}" ] && PLATFORMS="${PLATFORMS}Slack " 564→ [ -n "${RALPH_DISCORD_WEBHOOK_URL:-}" ] && PLATFORMS="${PLATFORMS}Discord " 565→ [ -n "${RALPH_TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${RALPH_TELEGRAM_CHAT_ID:-}" ] && PLATFORMS="${PLATFORMS}Telegram " 566→ [ -n "${RALPH_CUSTOM_NOTIFY_SCRIPT:-}" ] && PLATFORMS="${PLATFORMS}Custom " 567→ echo -e " Notify: ${GREEN}${PLATFORMS}${NC}" 568→else 569→ echo -e " Notify: ${YELLOW}disabled${NC} (run 'ralph notify setup')" 570→fi 571→if [ -f "$GUARDRAILS_FILE" ]; then 572→ GUARDRAILS_LINES=$(wc -l < "$GUARDRAILS_FILE") 573→ guardrails_warn="${GUARDRAILS_WARN_LIMIT:-100}" 574→ if [ "$GUARDRAILS_LINES" -gt "$guardrails_warn" ]; then 575→ echo -e " Guardrails:${YELLOW} $GUARDRAILS_FILE ($GUARDRAILS_LINES lines - consider consolidating)${NC}" 576→ else 577→ echo -e " Guardrails:${GREEN} $GUARDRAILS_FILE ($GUARDRAILS_LINES lines)${NC}" 578→ fi 579→else 580→ echo -e " Guardrails:${YELLOW} none (created when needed)${NC}" 581→fi 582→echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 583→echo "" 584→echo -e "${YELLOW}Exit conditions:${NC}" 585→if [ "$MODE" = "plan" ]; then 586→ echo " - Planning completes when task list is created (Status: IN_PROGRESS)" 587→ echo " - Plan mode runs once then exits automatically" 588→else 589→ echo " - RALPH_DONE in $PROGRESS_FILE signals all tasks complete (set by AI)" 590→fi 591→echo " - Press Ctrl+C to stop manually" 592→echo "" 593→ 594→# Send start notification to Slack 595→REPO_NAME=$(basename "$(pwd)") 596→notify ":rocket: *Ralph Started*\n\`\`\`Plan: $PLAN_BASENAME\nMode: $MODE\nRepo: $REPO_NAME\`\`\`" ":rocket:" 597→ 598→# Initialize progress file if it doesn't exist 599→if [ ! -f "$PROGRESS_FILE" ]; then 600→ echo "# Progress: $PLAN_BASENAME" > "$PROGRESS_FILE" 601→ echo "" >> "$PROGRESS_FILE" 602→ echo "Started: $(date)" >> "$PROGRESS_FILE" 603→ echo "" >> "$PROGRESS_FILE" 604→ echo "## Status" >> "$PROGRESS_FILE" 605→ echo "" >> "$PROGRESS_FILE" 606→ echo "IN_PROGRESS" >> "$PROGRESS_FILE" 607→ echo "" >> "$PROGRESS_FILE" 608→ echo "## Tasks Completed" >> "$PROGRESS_FILE" 609→ echo "" >> "$PROGRESS_FILE" 610→fi 611→ 612→ITERATION=0 613→ 614→# Check for completion 615→# Uses -x to match whole lines only, preventing false positives from 616→# instructional text like "DO NOT set RALPH_DONE" in the progress file 617→is_done() { 618→ if [ -f "$PROGRESS_FILE" ]; then 619→ grep -qx "RALPH_DONE" "$PROGRESS_FILE" 2>/dev/null && return 0 620→ fi 621→ return 1 622→} 623→ 624→# ============================================================================ 625→# CONCURRENCY PROTECTION (Fix for GitHub Issue #1) 626→# ============================================================================ 627→# Prevent multiple Ralph instances from running on the same plan file 628→# This fixes API Error 400 due to tool use race conditions 629→ 630→# Generate lock file path based on plan file (unique per plan) 631→PLAN_HASH=$(echo "$PLAN_FILE_ABS" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "$PLAN_BASENAME") 632→LOCK_FILE="${TEMP_DIR:-/tmp}/ralph_${PLAN_HASH}.lock" 633→ 634→# Cleanup function for graceful exit 635→cleanup_lock() { 636→ if [ -n "${LOCK_FILE:-}" ]; then 637→ release_lock "$LOCK_FILE" 2>/dev/null || true 638→ fi 639→} 640→ 641→# Set up trap to release lock on exit (normal or error) 642→trap cleanup_lock EXIT INT TERM 643→ 644→# Acquire lock before starting the main loop 645→if ! acquire_lock "$LOCK_FILE"; then 646→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 647→ echo -e "${RED} ERROR: Another Ralph instance is already running this plan${NC}" 648→ echo -e "${RED} Plan: $PLAN_FILE${NC}" 649→ echo -e "${RED} Lock: $LOCK_FILE${NC}" 650→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 651→ echo "" 652→ echo -e "${YELLOW}To force a new instance, remove the lock file:${NC}" 653→ echo -e " rm -f $LOCK_FILE" 654→ exit 1 655→fi 656→ 657→echo -e "${GREEN}Lock acquired: $LOCK_FILE${NC}" 658→ 659→# Main loop 660→while true; do 661→ # Check exit conditions 662→ if is_done; then 663→ echo "" 664→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 665→ echo -e "${GREEN} RALPH_DONE - Work complete!${NC}" 666→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 667→ notify ":white_check_mark: *Ralph Complete!*\n\`\`\`Plan: $PLAN_BASENAME\nIterations: $ITERATION\nRepo: $REPO_NAME\`\`\`" ":white_check_mark:" 668→ break 669→ fi 670→ 671→ if [ "$MAX_ITERATIONS" -gt 0 ] && [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then 672→ echo "" 673→ echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 674→ echo -e "${YELLOW} Max iterations reached: $MAX_ITERATIONS${NC}" 675→ echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 676→ notify ":warning: *Ralph Stopped*\n\`\`\`Plan: $PLAN_BASENAME\nReason: Max iterations reached ($MAX_ITERATIONS)\nRepo: $REPO_NAME\`\`\`" ":warning:" 677→ break 678→ fi 679→ 680→ ITERATION=$((ITERATION + 1)) 681→ echo "" 682→ echo -e "${BLUE}══════════════════ ITERATION $ITERATION ══════════════════${NC}" 683→ echo "" 684→ 685→ # Build the prompt with substitutions (safely escape for sed to prevent injection) 686→ # Escape special sed characters: & \ / newlines 687→ escape_sed() { 688→ local str="$1" 689→ # Escape backslashes first, then forward slashes, then ampersands 690→ str="${str//\\/\\\\}" 691→ str="${str//\//\\/}" 692→ str="${str//&/\\&}" 693→ printf '%s' "$str" 694→ } 695→ 696→ # Variables for sed escaping (not using local since we're in main loop, not a function) 697→ safe_plan_file=$(escape_sed "$PLAN_FILE_ABS") 698→ safe_progress_file=$(escape_sed "$PROGRESS_FILE") 699→ safe_plan_name=$(escape_sed "$PLAN_BASENAME") 700→ safe_should_commit=$(escape_sed "$SHOULD_COMMIT") 701→ safe_guardrails_file=$(escape_sed "$GUARDRAILS_FILE") 702→ safe_guardrails_soft_limit=$(escape_sed "${GUARDRAILS_SOFT_LIMIT:-50}") 703→ 704→ PROMPT=$(cat "$PROMPT_TEMPLATE" | \ 705→ sed "s|\${PLAN_FILE}|$safe_plan_file|g" | \ 706→ sed "s|\${PROGRESS_FILE}|$safe_progress_file|g" | \ 707→ sed "s|\${PLAN_NAME}|$safe_plan_name|g" | \ 708→ sed "s|\${AUTO_COMMIT}|$safe_should_commit|g" | \ 709→ sed "s|\${GUARDRAILS_FILE}|$safe_guardrails_file|g" | \ 710→ sed "s|\${GUARDRAILS_SOFT_LIMIT}|$safe_guardrails_soft_limit|g") 711→ 712→ # Run Claude with retry logic (configurable attempts with exponential backoff) 713→ max_claude_retries="${CLAUDE_MAX_RETRIES:-3}" 714→ claude_retry_delay="${CLAUDE_RETRY_DELAY:-5}" 715→ claude_attempt=1 716→ claude_success=false 717→ claude_exit_code=0 718→ claude_errors="" 719→ error_detected=false 720→ error_type="unknown" 721→ 722→ while [ $claude_attempt -le $max_claude_retries ]; do 723→ if [ $claude_attempt -gt 1 ]; then 724→ echo -e "${YELLOW}Retrying Claude CLI (attempt $claude_attempt/$max_claude_retries) in ${claude_retry_delay}s...${NC}" 725→ sleep $claude_retry_delay 726→ fi 727→ 728→ # Reset for this attempt 729→ claude_exit_code=0 730→ error_detected=false 731→ error_type="unknown" 732→ claude_output_file=$(mktemp) || { 733→ log_error "Failed to create temp file for Claude output" 734→ exit 1 735→ } 736→ claude_error_file=$(mktemp) || { 737→ rm -f "$claude_output_file" 738→ log_error "Failed to create temp file for Claude errors" 739→ exit 1 740→ } 741→ chmod 600 "$claude_output_file" "$claude_error_file" 742→ 743→ # Run Claude with streaming output 744→ if command -v jq &>/dev/null; then 745→ # Stream JSON events, display text content in real-time 746→ echo "$PROMPT" | claude -p \ 747→ --dangerously-skip-permissions \ 748→ --model "$RALPH_MODEL" \ 749→ --verbose \ 750→ --output-format stream-json 2>"$claude_error_file" | \ 751→ tee "$claude_output_file" | \ 752→ jq --unbuffered -r ' 753→ select(.type == "assistant") | 754→ .message.content[]? | 755→ if .type == "text" then .text 756→ elif .type == "tool_use" then 757→ " \u001b[0;34m→ " + .name + 758→ (if .input.file_path then ": " + .input.file_path 759→ elif .input.pattern then " /" + .input.pattern + "/" 760→ elif .input.command then ": " + (.input.command | .[0:80]) 761→ elif .input.prompt then ": " + (.input.prompt | .[0:80]) 762→ else "" end) + "\u001b[0m" 763→ else empty end 764→ ' || claude_exit_code=$? 765→ else 766→ # No jq available: capture output, no streaming display 767→ echo "$PROMPT" | claude -p \ 768→ --dangerously-skip-permissions \ 769→ --model "$RALPH_MODEL" \ 770→ --verbose 2>"$claude_error_file" > "$claude_output_file" || claude_exit_code=$? 771→ fi 772→ 773→ # Capture any error output 774→ claude_errors="" 775→ if [ -f "$claude_error_file" ]; then 776→ claude_errors=$(cat "$claude_error_file" 2>/dev/null || echo "") 777→ fi 778→ 779→ # Check for known error patterns even if exit code is 0 780→ if [ $claude_exit_code -ne 0 ]; then 781→ error_detected=true 782→ case $claude_exit_code in 783→ 1) error_type="general error" ;; 784→ 2) error_type="CLI usage error" ;; 785→ 130) error_type="interrupted by user (Ctrl+C)" ;; 786→ *) error_type="exit code $claude_exit_code" ;; 787→ esac 788→ fi 789→ 790→ # Check error output for known patterns 791→ if [ -n "$claude_errors" ]; then 792→ if echo "$claude_errors" | grep -qi "authentication\|unauthorized\|api.*key"; then 793→ error_detected=true 794→ error_type="authentication failure" 795→ elif echo "$claude_errors" | grep -qi "rate.*limit\|too.*many.*requests"; then 796→ error_detected=true 797→ error_type="rate limit exceeded" 798→ elif echo "$claude_errors" | grep -qi "network\|connection\|timeout"; then 799→ error_detected=true 800→ error_type="network error" 801→ elif echo "$claude_errors" | grep -qi "not.*found\|command.*not.*found"; then 802→ error_detected=true 803→ error_type="Claude CLI not found or not in PATH" 804→ # GitHub Issue #1: Detect API 400 errors from tool use concurrency 805→ elif echo "$claude_errors" | grep -qi "400\|bad.*request\|tool.*use\|concurrency"; then 806→ error_detected=true 807→ error_type="API 400 error (tool use concurrency)" 808→ fi 809→ fi 810→ 811→ # Clean up temp files 812→ rm -f "$claude_output_file" "$claude_error_file" 813→ 814→ # Check if we succeeded 815→ if [ "$error_detected" = false ]; then 816→ claude_success=true 817→ break 818→ fi 819→ 820→ # Log the attempt error 821→ log_error "Claude CLI error at iteration $ITERATION (attempt $claude_attempt/$max_claude_retries): $error_type" 822→ if [ -n "$claude_errors" ]; then 823→ err_truncate="${ERROR_DETAILS_TRUNCATE_LENGTH:-500}" 824→ log_error "Error details: ${claude_errors:0:$err_truncate}" 825→ fi 826→ 827→ # For non-retryable errors, don't retry 828→ if [[ "$error_type" =~ "authentication"|"CLI usage error"|"interrupted by user"|"not found" ]]; then 829→ echo -e "${RED}Non-retryable error detected: $error_type${NC}" 830→ break 831→ fi 832→ 833→ # Increment retry counter and increase backoff with jitter 834→ claude_attempt=$((claude_attempt + 1)) 835→ if [ $claude_attempt -le $max_claude_retries ]; then 836→ # Exponential backoff: 5s, 10s, 20s with random jitter (0-2s) 837→ # Jitter prevents "thundering herd" when multiple instances retry simultaneously 838→ # This is a key fix for GitHub Issue #1 (concurrency issues) 839→ jitter=$((RANDOM % 3)) 840→ claude_retry_delay=$(( (claude_retry_delay * 2) + jitter )) 841→ fi 842→ done 843→ 844→ # If all retries failed, stop iterations 845→ if [ "$claude_success" = false ]; then 846→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 847→ echo -e "${RED} Claude CLI Error (after $claude_attempt attempts): $error_type${NC}" 848→ echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 849→ 850→ # Check if this is a transient error that might benefit from manual retry 851→ # API 400 (tool use concurrency) is now retryable with proper locking 852→ if [[ "$error_type" =~ "rate limit"|"network"|"timeout"|"API 400" ]]; then 853→ echo -e "${YELLOW}This appears to be a transient error.${NC}" 854→ echo -e "${YELLOW}You may want to retry in a few minutes.${NC}" 855→ fi 856→ 857→ # Send error notification and log 858→ log_error "Stopping Ralph due to Claude CLI failure at iteration $ITERATION after $claude_attempt attempts" 859→ notify ":x: *Ralph Error*\n\`\`\`Plan: $PLAN_BASENAME\nIteration: $ITERATION\nError: $error_type (after $claude_attempt retries)\nRepo: $REPO_NAME\`\`\`" ":x:" 860→ exit $claude_exit_code 861→ fi 862→ 863→ echo "" 864→ echo -e "${GREEN}Iteration $ITERATION complete${NC}" 865→ 866→ # Plan mode: exit after one iteration 867→ if [ "$MODE" = "plan" ]; then 868→ echo "" 869→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 870→ echo -e "${GREEN} Planning complete! Task list created in $PROGRESS_FILE${NC}" 871→ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" 872→ echo "" 873→ echo -e "Next step: Run ${YELLOW}ralph $PLAN_FILE build${NC} to implement tasks" 874→ notify ":clipboard: *Ralph Planning Complete!*\n\`\`\`Plan: $PLAN_BASENAME\nTask list created in: $PROGRESS_FILE\nRepo: $REPO_NAME\`\`\`" ":clipboard:" 875→ break 876→ fi 877→ 878→ # Send iteration notification (configurable frequency via RALPH_NOTIFY_FREQUENCY) 879→ notify_default="${NOTIFY_FREQUENCY_DEFAULT:-5}" 880→ NOTIFY_FREQ="${RALPH_NOTIFY_FREQUENCY:-$notify_default}" 881→ # Validate notification frequency 882→ notify_min="${NOTIFY_FREQUENCY_MIN:-1}" 883→ notify_max="${NOTIFY_FREQUENCY_MAX:-100}" 884→ if ! validate_numeric "$NOTIFY_FREQ" "RALPH_NOTIFY_FREQUENCY" "$notify_min" "$notify_max"; then 885→ NOTIFY_FREQ="$notify_default" 886→ log_error "Invalid RALPH_NOTIFY_FREQUENCY, using default: $notify_default" 887→ fi 888→ if [ "$ITERATION" -eq 1 ] || [ $((ITERATION % NOTIFY_FREQ)) -eq 0 ]; then 889→ notify ":gear: *Ralph Progress*: Iteration $ITERATION completed\n\`Plan: $PLAN_BASENAME\`" ":gear:" 890→ fi 891→ 892→ # Small delay between iterations 893→ iter_delay="${ITERATION_DELAY:-2}" 894→ sleep "$iter_delay" 895→done 896→ 897→echo "" 898→echo "Total iterations: $ITERATION" 899→echo "Progress file: $PROGRESS_FILE" 900→

Summary

Summary