Handling API Responses

Relevant source files

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

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

The Ralph for Claude Code system relies on robust analysis of the output from the Claude Code CLI to drive its autonomous development loop. This process involves detecting the response format, parsing structured (JSON) or unstructured (text) data, identifying errors, and extracting state information like completion signals and session IDs. This mechanism is central to features like intelligent exit detection, the circuit breaker, and session continuity.

The primary component responsible for this is lib/response_analyzer.sh, which intelligently processes responses to inform the main ralph_loop.sh. A similar, specialized implementation exists within ralph_import.sh for handling PRD conversion tasks.

Sources: CLAUDE.md:42-59, README.md:100-102

Response Processing Flow

The system first determines if the response from the Claude Code CLI is structured JSON or plain text. Based on the format, it follows a specific parsing path to extract meaningful data. This dual-path approach ensures backward compatibility with older CLI versions while leveraging the benefits of modern, structured output.

Sources: ralph_import.sh:293-301, CLAUDE.md:301-306

The following diagram illustrates the high-level data flow for response handling.

Response Format Detection

Before parsing, the system must identify the response format. The detect_response_format function in ralph_import.sh implements this logic. It provides a reliable way to distinguish between modern JSON output and legacy text output.

The detection process is as follows:

1. Check if the output file is empty. If so, it's considered text.
2. Find the first non-whitespace character. If it's not { or [, it's text.
3. If jq is available, validate the file as JSON. If valid, the format is json; otherwise, it's text.

Sources: ralph_import.sh:80-105, CLAUDE.md:301-302

This diagram shows the logic of the detect_response_format function.

JSON Response Parsing

When a JSON response is detected, the system uses jq to parse the structured data. This is the preferred method as it is less brittle than text parsing. The system supports both a flat JSON format and the official Claude Code CLI format, which includes a metadata object.

Sources: CLAUDE.md:270-274, ralph_import.sh:107-160

Key Parsed Fields

The following fields are extracted from the JSON response to guide the Ralph loop.

Field	JSON Path(s)	Description	Source File
PARSED_RESULT	.result / .summary	The main summary or result text from the execution.	ralph_import.sh:130
PARSED_SESSION_ID	.sessionId / .session_id	The session identifier used for continuity.	ralph_import.sh:133
PARSED_FILES_CHANGED	.metadata.files_changed / .files_changed	The number of files modified in the loop.	ralph_import.sh:136
PARSED_HAS_ERRORS	.metadata.has_errors / .has_errors	A boolean flag indicating if errors occurred.	ralph_import.sh:139
PARSED_COMPLETION_STATUS	.metadata.completion_status / .completion_status	The status of the task (e.g., complete, partial).	ralph_import.sh:142
PARSED_ERROR_MESSAGE	.metadata.error_message / .error_message	A specific error message if the task failed.	ralph_import.sh:145
PARSED_FILES_CREATED	.metadata.files_created	A JSON array of files that were created.	ralph_import.sh:151

Sources: ralph_import.sh:107-160, CLAUDE.md:270-278

Sequence Diagram: PRD Import

This sequence diagram shows how ralph_import.sh uses the modern Claude Code CLI with JSON output to convert a document.

Text-Based Response Parsing

For backward compatibility or when JSON output is unavailable, the system falls back to parsing a special text block from the CLI's standard output. The PROMPT.md template instructs the AI to include a ---RALPH_STATUS--- block at the end of its response.

Sources: templates/PROMPT.md:43-56

RALPH_STATUS Block

This block contains key-value pairs that the response_analyzer.sh script parses to understand the outcome of the loop.

Key	Possible Values	Description
STATUS	IN_PROGRESS, COMPLETE, BLOCKED	The overall status of the project.
TASKS_COMPLETED_THIS_LOOP	<number>	Number of tasks finished in the current iteration.
FILES_MODIFIED	<number>	Number of files changed.
TESTS_STATUS	PASSING, FAILING, NOT_RUN	The outcome of the test run.
WORK_TYPE	IMPLEMENTATION, TESTING, etc.	The category of work performed.
EXIT_SIGNAL	true, false	A signal indicating if the project is considered complete.
RECOMMENDATION	<string>	A one-line summary of the recommended next step.

Sources: templates/PROMPT.md:43-79

Error Detection

A critical part of response handling is detecting errors to prevent infinite loops and trigger the Circuit Breaker. The system uses a sophisticated two-stage filtering process to accurately identify real errors while ignoring false positives.

Sources: CLAUDE.md:231-232

Two-Stage Error Filtering

1. Stage 1: JSON Field Filtering: This stage removes 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. The pattern used is grep -v '"[^"]*error[^"]*":'.
2. Stage 2: Actual Error Detection: After filtering, this stage searches for genuine error messages using a grep -cE command with specific patterns.

Sources: CLAUDE.md:234-245

Error Detection Patterns

The following patterns are used in Stage 2 to identify errors:

• ^Error:
• ^ERROR:
• ^error:
• \]: error
• Link: error
• Error occurred
• failed with error
• [Ee]xception
• Fatal
• FATAL

Sources: CLAUDE.md:240-244

Stuck Loop Detection

To detect if the loop is stuck on a recurring error, the system performs multi-line error matching. It verifies that all error lines from the current output have appeared in all recent history files. This prevents false positives that could occur if different, unrelated errors appear in successive loops.

Sources: CLAUDE.md:247-251

Session Management

Session management enables context to be preserved across multiple loop iterations, leading to more coherent and efficient development. The sessionId is extracted from the JSON response and persisted.

• The session ID is stored in a file (e.g., .claude_session_id or .ralph_session).
• The should_resume_session() function checks if a stored session is still valid (within a 24-hour expiration window).
• If valid, the session ID is passed to the Claude Code CLI via the --continue flag.
• Sessions are automatically reset on certain events, such as a manual interrupt, project completion, or when the circuit breaker opens.

Sources: CLAUDE.md:275-281, 285-293, README.md:180-194

Summary

Handling API responses is a cornerstone of the Ralph for Claude Code architecture. By supporting both modern JSON and legacy text formats, the system ensures flexibility and backward compatibility. Its sophisticated parsing, error detection, and session management capabilities allow the autonomous loop to make intelligent decisions, track progress effectively, and protect against runaway processes, forming the foundation of its autonomous operation.

Sources: CLAUDE.md:33-60, README.md:100-108