ralph-claude-code

Implements a continuous execution loop that repeatedly invokes the Claude Code CLI with 15-minute timeouts, analyzes responses for completion signals, and automatically re-enters the loop for multi-step development tasks. The loop integrates five quality gates: rate limiting checks via can_make_call(), circuit breaker pre-checks via should_halt_execution() to detect stagnation, exit detection via should_exit_gracefully() to identify task completion, Claude execution with timeout enforcement, and post-execution analysis via analyze_response() and record_loop_result() to evaluate progress and decide whether to continue or exit.

Analyzes Claude Code responses using the should_exit_gracefully() function to detect task completion by evaluating multiple signals: explicit completion markers in Claude's output, convergence detection (no meaningful changes between iterations), error state analysis, and timeout conditions. The response_analyzer.sh library module implements two-stage error filtering to distinguish between recoverable errors (retry) and terminal errors (exit), using pattern matching against known Claude Code failure modes and success indicators.

Implements execute_claude_code() function that invokes the Claude Code CLI with a 15-minute timeout using the timeout command, captures stdout/stderr to temporary files, and parses the output to extract generated code and status information. The function handles timeout scenarios (kills the process and logs timeout error), exit codes from Claude Code, and streams output to both log files and the terminal for real-time visibility.

Implements response_analyzer.sh library module that performs two-stage error filtering on Claude Code responses: first stage identifies error patterns (compilation failures, infinite loops, resource exhaustion) using regex matching against known failure modes; second stage classifies errors as recoverable (retry) or terminal (exit) based on error type and context. The analyzer extracts key information from Claude's output (files modified, errors encountered, progress indicators) and returns structured analysis for decision-making.

Implements rate limiting via the can_make_call() function that tracks API calls in state files and enforces configurable hourly quotas before invoking Claude Code. The system records call timestamps in ~/.ralph/state/call_history.json and checks against MAX_CALLS_PER_HOUR configuration parameter using date_utils.sh for timestamp calculations. If the hourly quota is exceeded, the loop sleeps until the oldest call in the window expires, then retries.

Implements a circuit breaker via should_halt_execution() and circuit_breaker.sh library module that detects when Ralph is stuck in a loop making no meaningful progress. The circuit breaker tracks consecutive iterations with no file changes or identical responses, maintains a state machine with OPEN/CLOSED/HALF_OPEN states, and triggers exit when stagnation threshold is exceeded. Pattern matching in circuit_breaker.sh identifies known failure modes (compilation errors, infinite loops, resource exhaustion) and immediately opens the circuit without waiting for iteration count threshold.

Provides ralph-setup command that initializes a new Ralph project by copying template files (PROMPT.md, @fix_plan.md, @AGENT.md, .ralph.config) from ~/.ralph/templates/ to the target directory, creating .git repository, and setting up directory structure. Additionally, ralph-import command parses product requirement documents (PRDs) using Claude Code to automatically generate PROMPT.md and @fix_plan.md templates, reducing manual setup time for new projects.

Provides ralph-monitor command that displays a live dashboard showing Ralph's current execution status, recent log entries, progress metrics (iterations completed, files modified, API calls made), and real-time log tailing from ~/.ralph/logs/. The monitor uses shell-based UI rendering with periodic updates (default 2-second interval) to show loop progress without requiring separate terminal windows or external monitoring tools.

Implements task management through the @fix_plan.md file, which serves as a persistent task list that Claude updates during execution to track completed subtasks, remaining work, and blockers. Ralph parses @fix_plan.md to extract task status and uses it as input to subsequent Claude Code invocations, enabling Claude to maintain context about what has been completed and what remains. The file format uses markdown checkboxes and structured sections to represent task state, which Claude can read and modify.

Provides a library architecture with three reusable Bash modules in ~/.ralph/lib/: response_analyzer.sh (two-stage error filtering and response analysis), circuit_breaker.sh (stagnation detection and state machine), and date_utils.sh (timestamp calculations for rate limiting). Each library module exports functions that are sourced by ralph_loop.sh, enabling code reuse and separation of concerns. Libraries are installed globally during setup.sh and can be updated independently.

Implements configuration via .ralph.config file in each project directory, which defines parameters like MAX_CALLS_PER_HOUR, CLAUDE_CODE_TIMEOUT, STAGNATION_THRESHOLD, and other runtime settings. Configuration is sourced by ralph_loop.sh and can be overridden by environment variables (e.g., MAX_CALLS_PER_HOUR=20 ralph). Default values are provided in template .ralph.config during project initialization, enabling per-project customization without modifying global scripts.

Implements state persistence using local files in ~/.ralph/state/ directory, storing execution state across iterations: call_history.json (API call timestamps for rate limiting), circuit_breaker.state (circuit breaker state machine), last_response.txt (previous Claude Code output for convergence detection), and loop_results.log (iteration history). State files are read/written by library functions and the main loop, enabling Ralph to resume from checkpoints and maintain context across system restarts (if state files are preserved).