Feature: Circuit Breaker

Relevant source files

The following files were used as context for generating this wiki page:

• lib/circuit_breaker.sh
• ralph_loop.sh
• tests/test_stuck_loop_detection.sh
• CLAUDE.md
• README.md
• SPECIFICATION_WORKSHOP.md

The Circuit Breaker is a critical safety feature within the Ralph autonomous development loop. Its primary purpose is to prevent runaway or stuck loops by detecting stagnation, repeated errors, or significant declines in output quality. By monitoring the loop's progress, it can automatically halt execution when a problem is detected, saving API calls and developer time.

The system implements a classic three-state circuit breaker pattern: CLOSED (normal operation), HALF_OPEN (monitoring for recovery), and OPEN (halted). This allows for automatic state transitions and recovery without requiring manual intervention for temporary issues. The entire mechanism is designed to be a robust safeguard that ensures the stability and efficiency of the autonomous agent.

Sources: CLAUDE.md:23-27, README.md:162-169

Architecture and State Machine

The circuit breaker operates as a state machine with three distinct states. The main loop (ralph_loop.sh) interacts with the circuit breaker logic (lib/circuit_breaker.sh) at the beginning and end of each iteration to check its state and record results.

Sources: CLAUDE.md:24, lib/circuit_breaker.sh

States

1. CLOSED: The default state. The loop operates normally, and all calls to the Claude Code CLI are permitted. The circuit breaker continuously monitors for failure conditions.
2. OPEN: When failure thresholds are exceeded, the circuit transitions to OPEN. In this state, the Ralph loop is halted, and no further API calls are made. This prevents a stuck process from consuming resources. The session is automatically reset when the circuit opens.
3. HALF_OPEN: After a cooldown period in the OPEN state (which is implicitly handled by the loop's pause/restart), the circuit moves to HALF_OPEN. In this state, a limited number of trial executions are allowed. If a trial is successful (i.e., progress is detected), the circuit transitions back to CLOSED. If it fails, it returns to the OPEN state.

Sources: CLAUDE.md:24-27, 43, SPECIFICATION_WORKSHOP.md:83-96

State Transition Diagram

The following diagram illustrates the transitions between the circuit breaker states.

Configuration and Thresholds

The behavior of the circuit breaker is controlled by several configurable thresholds defined in ralph_loop.sh. These values determine the sensitivity of the system to various failure conditions.

Parameter	Default Value	Description
CB_NO_PROGRESS_THRESHOLD	3	Opens the circuit after this many consecutive loops with no file changes.
CB_SAME_ERROR_THRESHOLD	5	Opens the circuit after the same error occurs this many times consecutively.
CB_OUTPUT_DECLINE_THRESHOLD	70%	Opens the circuit if the output size declines by more than this percentage, indicating a potential problem.

Sources: CLAUDE.md:129-131, README.md:214-216

Error Detection and Stuck Loop Logic

A key aspect of the circuit breaker is its sophisticated error detection, which is designed to be accurate and avoid false positives.

Sources: CLAUDE.md:133-151, 252-262

Two-Stage Error Filtering

To prevent common false positives, such as JSON fields like "is_error": false, the system uses a two-stage filtering process when analyzing Claude's output for errors.

1. Stage 1: JSON Field Filtering: The initial pass filters out lines that match patterns of non-error JSON fields containing the word "error". This is done using grep -v '"[^"]*error[^"]*":'.
2. Stage 2: Actual Error Detection: The second pass searches the remaining text for genuine error indicators, such as Error:, Exception, Fatal, or context-specific patterns like ]: error.

This process is visualized in the flowchart below.

Multi-line Error Matching

To accurately detect a "stuck loop" condition, the system does not just check for the presence of errors but verifies if the exact same set of errors is repeating across multiple loops. It achieves this by:

1. Extracting all error lines from the current loop's output.
2. Comparing this set of lines against the error lines from previous recent loops.
3. A stuck loop is only confirmed if ALL error lines from the current output are present in ALL recent history files. This is performed using literal fixed-string matching (grep -qF) to avoid regex complexities and ensure precision.

This prevents the circuit from tripping incorrectly if the agent is encountering different, unrelated errors while attempting to make progress.

Sources: CLAUDE.md:148-151, 252-255, tests/test_stuck_loop_detection.sh

Integration with the Main Loop

The circuit breaker logic is tightly integrated into ralph_loop.sh. The loop checks the circuit breaker's state at the beginning of each iteration and records the outcome at the end.

The following sequence diagram shows the interaction between the main loop and the circuit breaker module during a single iteration.

CLI Management

Users can interact with and manage the circuit breaker's state via CLI flags provided by the ralph command.

Command	Description
ralph --reset-circuit	Manually resets the circuit breaker to the CLOSED state and clears its history. This also triggers a session reset.
ralph --circuit-status	Displays the current state and history of the circuit breaker.

Sources: README.md:323-325, CLAUDE.md:55, 43

Summary

The Circuit Breaker is an essential stability and safety pattern implemented in the Ralph project. It protects against infinite loops and wasted resources by intelligently detecting stagnation and repeated failures. Through its three-state machine, configurable thresholds, and sophisticated multi-stage error detection, it provides a robust, automated mechanism to halt faulty processes and allow for graceful recovery, making the autonomous development loop more reliable and efficient.

Sources: CLAUDE.md:23-27, README.md:162-169