Feature: Response Analyzer
Relevant source files
The following files were used as context for generating this wiki page:
The Response Analyzer is a critical component of the Ralph autonomous development loop. Its primary purpose is to intelligently parse the output from the Claude Code CLI to determine the state of the development process. By analyzing the response, it provides the signals necessary for the main loop to decide whether to continue to the next iteration, exit gracefully upon project completion, or halt due to recurring errors. This system supports both structured JSON output and a fallback text-based format, ensuring robust operation across different CLI versions and response types.
The analyzer is not a single script but a collection of functions distributed across ralph_loop.sh, ralph_import.sh, and the lib/ directory, as documented in CLAUDE.md. It is responsible for exit detection, error filtering, session management, and parsing completion status.
Sources: README.md:81-87, CLAUDE.md:30-43
Core Logic and Data Flow
The analysis logic is primarily triggered within the ralph_loop.sh script by the should_exit_gracefully function. This function aggregates signals from various checks to make a final exit decision. The ralph_import.sh script also contains a specialized response analyzer for converting PRDs.
Sources: create_files.sh:176-221, ralph_import.sh:78-223
This diagram illustrates the high-level data flow for response analysis within the main loop.
Sources: CLAUDE.md:30-43, create_files.sh:176-221
Response Format Handling
The analyzer is designed to handle two primary output formats from the Claude Code CLI: a modern, structured JSON format and a legacy text-based format.
Sources: CLAUDE.md:32-34, ralph_import.sh:78-109
JSON Output Parsing
The system prefers the JSON output format for its reliability. The detect_response_format function first checks if the output is valid JSON. If so, parse_conversion_response (in ralph_import.sh) or parse_json_response (documented in CLAUDE.md) is used to extract key-value pairs.
Sources: ralph_import.sh:78-171, CLAUDE.md:552-557
The following diagram shows the logic for detecting the response format.
Sources: ralph_import.sh:87-109
The analyzer extracts the following fields from a JSON response:
| Field | JSON Path | Description |
|---|---|---|
PARSED_RESULT | .result or .summary | The main summary text from the response. |
PARSED_SESSION_ID | .sessionId or .session_id | The session ID for maintaining context. |
PARSED_FILES_CHANGED | .metadata.files_changed | The number of files modified in the loop. |
PARSED_HAS_ERRORS | .metadata.has_errors | A boolean flag indicating if errors occurred. |
PARSED_COMPLETION_STATUS | .metadata.completion_status | The status of the task (e.g., "complete", "partial"). |
PARSED_ERROR_MESSAGE | .metadata.error_message | A specific error message if the task failed. |
PARSED_FILES_CREATED | .metadata.files_created | A JSON array of files that were created. |
Sources: ralph_import.sh:129-168, CLAUDE.md:563-566
Text-Based Fallback (RALPH_STATUS)
If the output is not valid JSON, the analyzer falls back to parsing a special text block defined in templates/PROMPT.md. This block is delimited by ---RALPH_STATUS--- and ---END_RALPH_STATUS--- and contains key-value pairs that communicate the agent's status.
The expected format within the prompt is:
---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: <number>
FILES_MODIFIED: <number>
TESTS_STATUS: PASSING | FAILING | NOT_RUN
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: <one line summary of what to do next>
---END_RALPH_STATUS---
Sources: templates/PROMPT.md:30-40
Exit and Completion Detection
A primary function of the analyzer is to determine if the development loop should terminate. This is handled by the should_exit_gracefully function in ralph_loop.sh, which checks for several conditions.
Sources: create_files.sh:176-221
| Exit Condition | Threshold | Description | Source File |
|---|---|---|---|
| Test-Only Loops | MAX_CONSECUTIVE_TEST_LOOPS=3 | Exits if Claude only runs tests for 3 consecutive loops, indicating no new implementation work is being done. | create_files.sh:28 |
| "Done" Signals | MAX_CONSECUTIVE_DONE_SIGNALS=2 | Exits if Claude reports EXIT_SIGNAL: true or a similar completion signal twice in a row. | create_files.sh:29 |
| Strong Completion Indicators | 2 | Exits if at least two strong indicators of completion are found in the response. | create_files.sh:200-204 |
@fix_plan.md Complete | All items checked | Exits if all tasks in the @fix_plan.md file are marked as complete (- [x]). | create_files.sh:207-215 |
Sources: create_files.sh:28-29, 176-221, CLAUDE.md:518-522
Error Detection
The analyzer includes a sophisticated two-stage error filtering mechanism to accurately detect real errors while avoiding false positives from benign text. This is crucial for the Circuit Breaker to function correctly.
Sources: CLAUDE.md:535-537
- Stage 1: JSON Field Filtering: The first stage filters out lines that contain the word "error" but are part of a JSON key-value pair, such as
"is_error": false. This prevents the circuit breaker from tripping incorrectly. - Stage 2: Actual Error Detection: The second stage uses a
greppattern to search for specific error keywords and formats likeError:,Exception, orfailed with error.
Sources: CLAUDE.md:539-550
This diagram shows the two-stage error filtering process.
Sources: CLAUDE.md:539-550
Additionally, the system implements multi-line error matching to detect stuck loops where the exact same set of multiple error lines appears repeatedly across several loop iterations.
Sources: CLAUDE.md:552-557, 584-588
Session Management
When using the JSON output format, the analyzer is responsible for extracting the sessionId to enable session continuity. This allows Claude to maintain context across multiple, independent loop iterations.
Key functions involved in this process are:
parse_json_response(): Extracts thesessionIdfrom the Claude Code CLI's JSON output.store_session_id(): Persists the session ID to the.claude_session_idfile with a timestamp.get_last_session_id(): Retrieves the most recently stored session ID.should_resume_session(): Checks if the stored session is still valid (within a 24-hour expiration window).
The session is automatically reset under certain conditions, such as a manual interrupt, project completion, or when the circuit breaker opens.
Sources: CLAUDE.md:563-570, 600-610, README.md:214-226
This sequence diagram shows the session management flow during a loop.
Sources: CLAUDE.md:563-570, 600-610
Conclusion
The Response Analyzer is the intelligent core of the Ralph system, enabling its autonomous capabilities. By robustly parsing Claude's output in multiple formats, it translates the AI's work into actionable signals. Its ability to detect completion, filter errors accurately, and manage session state allows the main loop to operate reliably, prevent infinite cycles, and know when a project is truly finished.
Sources: README.md:81-87, CLAUDE.md:30-43