Troubleshooting

Relevant source files

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

• lib/circuit_breaker.sh
• ralph_loop.sh
• create_files.sh
• README.md
• CLAUDE.md
• TESTING.md
• ralph_import.sh
• templates/PROMPT.md

This document provides guidance for diagnosing and resolving issues within the Ralph for Claude Code autonomous development environment. It covers monitoring the system's state, understanding its automated recovery mechanisms like the circuit breaker, and debugging common problems such as stuck loops, API errors, and component-specific failures.

The primary tools for troubleshooting are the live monitoring dashboard, status files, and detailed execution logs. Understanding these components is key to effectively managing Ralph's autonomous operation. For issues related to the test suite, refer to the Testing Guide.

Monitoring and Status Checking

The first step in troubleshooting is to observe Ralph's current state. The system provides several mechanisms for real-time and historical analysis.

Live Monitoring Dashboard

The recommended way to monitor Ralph is by using the integrated tmux dashboard, which can be started with the --monitor flag. A standalone monitor can also be run with the ralph-monitor command. This dashboard provides a live view of the loop's status.

The monitor displays:

• Current loop count and status (e.g., running, completed).
• API calls made in the current hour versus the configured maximum.
• The last 8 log entries from logs/ralph.log.
• A countdown timer when waiting for an API rate limit reset.

This diagram shows the flow of information to the monitor.

Status File (status.json)

The ralph_loop.sh script maintains a status.json file in the project root, providing a machine-readable snapshot of its current state. You can view its formatted content by running ralph --status.

Field	Type	Description
timestamp	String	ISO 8601 timestamp of the last update.
loop_count	Number	The number of the current or last completed loop.
calls_made_this_hour	Number	API calls made in the current hourly window.
max_calls_per_hour	Number	The configured maximum calls per hour.
last_action	String	The most recent action taken (e.g., executing, graceful_exit).
status	String	The overall status of the loop (e.g., running, completed, error).
exit_reason	String	The reason for a graceful exit (e.g., plan_complete, test_saturation).
next_reset	String	The time when the hourly API call counter will reset.
Sources: create_files.sh:88-103, README.md:405-408

Execution Logs

All operations are logged to logs/ralph.log, with detailed, timestamped output for each loop. Additionally, the raw output from each Claude Code execution is saved to a separate file in the logs/ directory, named claude_output_<timestamp>.log. These files are essential for diagnosing specific execution failures.

Log Level	Color	Purpose
INFO	Blue	General informational messages.
WARN	Yellow	Warnings or non-critical issues.
ERROR	Red	Critical errors or execution failures.
SUCCESS	Green	Successful completion of major operations.
LOOP	Purple	Messages indicating the start and end of a loop.
Sources: create_files.sh:70-85, README.md:214-216

Diagnosing Loop Issues

Problems often manifest as the loop getting stuck, exiting unexpectedly, or failing to make progress.

Stuck Loops and The Circuit Breaker

To prevent infinite loops on persistent errors, Ralph implements a circuit breaker pattern. This mechanism monitors the loop for signs of stagnation and can temporarily halt execution. The circuit breaker is defined in lib/circuit_breaker.sh and its logic is integrated into the main loop.

The circuit breaker has three states:

• CLOSED: Normal operation. All calls are permitted.
• OPEN: An error threshold has been breached. Execution is halted, and the loop will not call the Claude API.
• HALF_OPEN: After a cooldown period, the circuit allows a limited number of trial executions to see if the issue is resolved. Success transitions the state to CLOSED; failure transitions it back to OPEN.

This diagram illustrates the state transitions of the circuit breaker.

The circuit breaker opens when certain thresholds are met:

Threshold Variable	Default	Description
CB_NO_PROGRESS_THRESHOLD	3	Opens the circuit after 3 consecutive loops with no file changes.
CB_SAME_ERROR_THRESHOLD	5	Opens the circuit after 5 consecutive loops with the same repeated error.
CB_OUTPUT_DECLINE_THRESHOLD	70	Opens the circuit if the output size from Claude declines by more than 70%.
Sources: CLAUDE.md:204-208, README.md:341-345

You can check the circuit breaker's status with ralph --circuit-status and reset it with ralph --reset-circuit.
Sources: README.md:465-466

API Rate Limiting and Usage Errors

Ralph has built-in handling for two types of API limits.

1. Hourly Rate Limit: By default, Ralph is limited to 100 API calls per hour. When this limit is reached, the wait_for_reset function is triggered. It calculates the time remaining until the top of the next hour, displays a countdown, and pauses execution.
2. 5-Hour Usage Limit: If the Claude API returns a 5-hour usage limit error, Ralph detects it and prompts the user to either wait for the limit to reset or exit gracefully.

This flowchart shows the rate limit handling process.

Intelligent Exit Detection

Ralph may exit automatically if it determines the project is complete or that it is no longer making meaningful progress. If Ralph exits sooner than expected, check the exit thresholds in ralph_loop.sh.

Threshold Variable	Default	Description
MAX_CONSECUTIVE_TEST_LOOPS	3	Exits after 3 consecutive loops that only involve running tests.
MAX_CONSECUTIVE_DONE_SIGNALS	2	Exits after receiving 2 consecutive completion signals from Claude.
TEST_PERCENTAGE_THRESHOLD	30	Flags a warning if more than 30% of recent loops were test-only.
Sources: create_files.sh:29-32, README.md:335-339

An exit can also be triggered if all tasks in @fix_plan.md are marked as complete.
Sources: create_files.sh:220-227

Error Detection and Analysis

Ralph's ability to troubleshoot itself relies on parsing the output from the Claude Code CLI. This is primarily handled by response_analyzer.sh (described in CLAUDE.md) and the RALPH_STATUS block specified in templates/PROMPT.md.

A sequence diagram showing how an error is detected and handled.

To avoid false positives from the word "error" appearing in non-error contexts (like JSON fields), Ralph uses a two-stage filtering process.

1. Stage 1: Filters out known safe patterns like "is_error": false.
2. Stage 2: Searches for specific error prefixes (Error:, Exception, Fatal) and patterns.

This ensures that the circuit breaker only trips on genuine, repeated errors.
Sources: CLAUDE.md:210-223

Troubleshooting Specific Components

PRD Import (ralph-import)

The ralph-import script automates the conversion of existing documents into the Ralph project format. Failures during this process can be diagnosed by examining its output and the files it creates.

Key troubleshooting steps:

1. Check Dependencies: Ensure ralph-setup is installed and the Claude Code CLI is available. The script will warn if it cannot find them.
2. Examine Logs: The script provides [INFO], [WARN], and [ERROR] level logs. Pay close attention to any warnings or errors.
3. Review Conversion Output: The script temporarily creates .ralph_conversion_output.json. If an error occurs, this file may contain details. The script uses detect_response_format and parse_conversion_response to process this file. If the CLI output is not valid JSON, it falls back to text parsing.
4. Verify Created Files: After a successful run, the script logs which files were created. If it reports that expected files (PROMPT.md, @fix_plan.md, specs/requirements.md) are missing, the conversion by Claude was incomplete.

This flowchart outlines the ralph-import process and potential failure points.

Troubleshooting Test Failures

The project includes a comprehensive test suite run with npm test. If tests fail, especially in a CI environment, use the following steps to debug:

1. Run a Single Test: Isolate the failure by running one test file or a single test case using the --filter flag.

   # Run a specific test file
   bats tests/unit/test_rate_limiting.bats
   
   # Run a single test by its name
   bats tests/unit/test_rate_limiting.bats --filter "can_make_call"
   

2. Add Debug Output: Print variable states or messages to the test output using echo "message" >&3.
3. Use set -x: Enable shell tracing within a test case to see every command that is executed.
4. Preserve Temp Directory: Comment out the rm -rf "$TEST_TEMP_DIR" line in the teardown function to inspect the state of files created during the test.

Sources: TESTING.md:401-440

Conclusion

Troubleshooting Ralph involves a combination of real-time monitoring, log analysis, and understanding its internal state machines like the circuit breaker. By using ralph-monitor for a high-level overview, status.json for a detailed snapshot, and the logs/ directory for in-depth history, developers can effectively diagnose and resolve most issues that arise during autonomous operation. For component-specific issues like PRD import or test failures, the system provides targeted logging and debugging strategies.