Interacting with the Claude Code CLI

Relevant source files

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

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

The Ralph for Claude Code system is fundamentally a sophisticated wrapper around the @anthropic/claude-code command-line interface (CLI). Its primary function is to automate the process of calling the CLI, managing its input, and intelligently parsing its output to create an autonomous development loop. This interaction is the core engine that drives all of Ralph's capabilities, from iterative code generation in ralph_loop.sh to document conversion in ralph_import.sh.

The system uses both standard and modern features of the Claude Code CLI, including structured JSON output and session continuity. It is designed to be backward-compatible, automatically detecting the CLI version and adjusting its invocation strategy accordingly. This ensures robust interaction with the underlying AI, enabling features like rate limiting, intelligent exit detection, and structured error handling.

Sources: create_files.sh, ralph_import.sh, CLAUDE.md

Core Execution Scripts

Two main scripts are responsible for interacting with the Claude Code CLI: ralph_loop.sh and ralph_import.sh.

ralph_loop.sh

This is the main autonomous development loop. It repeatedly calls the Claude Code CLI to perform development tasks based on the PROMPT.md and @fix_plan.md files.

• Command: npx @anthropic/claude-code
• Input: The content of the PROMPT.md file is piped as standard input to the CLI.
• Output: The CLI's output is redirected to a timestamped log file in the logs/ directory.

The execute_claude_code function within this script encapsulates the CLI call.

Sources: create_files.sh:21, 230-247

ralph_import.sh

This script converts a Product Requirements Document (PRD) into the Ralph project format (PROMPT.md, @fix_plan.md, etc.) by making a single, targeted call to the Claude Code CLI. It showcases the more advanced CLI interactions, including version checking and JSON output parsing.

• Command: claude (alias for the CLI)
• Input: A dynamically generated prompt file (.ralph_conversion_prompt.md) containing instructions and the source PRD content.
• Output: The script is configured to request JSON output, which it saves to a temporary file (.ralph_conversion_output.json) for parsing.

Sources: ralph_import.sh:5, 258-305

CLI Invocation and Configuration

The system employs a flexible strategy for invoking the Claude Code CLI, adapting to the installed version and the specific task.

Command and Versioning

The CLI command is configurable and its version is checked to determine if modern features are available.

• CLI Command Variable: The command is stored in a variable, typically CLAUDE_CODE_CMD.
  Sources: create_files.sh:21, ralph_import.sh:5
• Minimum Version: A minimum version (CLAUDE_MIN_VERSION) is defined to enable modern features like JSON output. The default is 2.0.76.
  Sources: ralph_import.sh:10, 186-231, CLAUDE.md:104
• Version Check: The check_claude_version function executes claude --version and performs a semantic version comparison to decide whether to use the modern or standard CLI mode.
  Sources: ralph_import.sh:186-231

Modern vs. Standard CLI Modes

The ralph_import.sh script can operate in two modes depending on the detected CLI version.

This diagram illustrates the logic for choosing the CLI execution mode.

Command-Line Arguments

The scripts use several command-line arguments to control the CLI's behavior.

Argument	Script(s)	Purpose	Source
--output-format json	ralph_import.sh	Requests structured JSON output from the CLI.	[ralph_import.sh:7, 294](https://github.com/Alonso-pixel/ralph-claude-code/blob/HEAD/ralph_import.sh#L7)
--allowedTools <tools>	ralph_import.sh	Grants the CLI permission to use specific tools like Read and Write without interactive prompts.	[ralph_import.sh:9, 294](https://github.com/Alonso-pixel/ralph-claude-code/blob/HEAD/ralph_import.sh#L9)
-p, --prompt <file>	ralph_loop.sh	Specifies the prompt file to use for the development loop.	[create_files.sh:371-374](https://github.com/Alonso-pixel/ralph-claude-code/blob/HEAD/create_files.sh#L371-L374)
-c, --calls <num>	ralph_loop.sh	Sets the maximum number of API calls per hour. This is a script-level control, not a direct CLI flag.	[create_files.sh:367-370](https://github.com/Alonso-pixel/ralph-claude-code/blob/HEAD/create_files.sh#L367-L370)
--continue / --no-continue	ralph_loop.sh	Enables or disables session continuity to maintain context between loop iterations.	[CLAUDE.md:114, 303-305](https://github.com/Alonso-pixel/ralph-claude-code/blob/HEAD/CLAUDE.md#L114), [README.md:246-249](https://github.com/Alonso-pixel/ralph-claude-code/blob/HEAD/README.md#L246-L249)

Response Handling

After executing the CLI, the scripts must process the output. ralph_import.sh has the most sophisticated response handling logic.

Response Format Detection

The script first determines if the output from the CLI is JSON or plain text.

This sequence diagram shows how the response format is detected.

This logic is implemented in the detect_response_format function.

Sources: ralph_import.sh:77-105

JSON Response Parsing

When the response is identified as JSON, the parse_conversion_response function is used to extract structured data. This function is designed to be flexible, supporting both a flat format and the official Claude CLI metadata structure.

Sources: ralph_import.sh:107-184

The following fields are extracted from the JSON response:

Field Path (Primary // Fallback)	Global Variable	Description
.result // .summary	PARSED_RESULT	The main summary or result text from the conversion.
.sessionId // .session_id	PARSED_SESSION_ID	The session ID for potential continuation.
.metadata.files_changed // .files_changed	PARSED_FILES_CHANGED	The number of files modified by the operation.
.metadata.has_errors // .has_errors	PARSED_HAS_ERRORS	A boolean flag indicating if errors occurred.
.metadata.completion_status // .completion_status	PARSED_COMPLETION_STATUS	The status of the task (e.g., "complete", "failed").
.metadata.error_message // .error_message	PARSED_ERROR_MESSAGE	A specific error message if the task failed.
.metadata.error_code // .error_code	PARSED_ERROR_CODE	A specific error code if the task failed.
.metadata.files_created	PARSED_FILES_CREATED	A JSON array of files created during the operation.
.metadata.missing_files	PARSED_MISSING_FILES	A JSON array of expected files that were not created.

Sources: ralph_import.sh:148-182, CLAUDE.md:239-243

Below is an example of the JSON structure that parse_conversion_response is designed to handle.

{
    "result": "PRD conversion completed successfully.",
    "sessionId": "session-abc-123",
    "metadata": {
        "files_changed": 3,
        "has_errors": false,
        "completion_status": "complete",
        "error_message": "",
        "error_code": "",
        "files_created": [
            "PROMPT.md",
            "@fix_plan.md",
            "specs/requirements.md"
        ],
        "missing_files": []
    }
}

Sources: ralph_import.sh:107-184, CLAUDE.md:239-243

Session and Context Management

To maintain coherence across multiple CLI calls in the ralph_loop.sh, the system implements session continuity.

• Session File: The session ID from a successful CLI call is stored in a file, typically .claude_session_id.
  Sources: CLAUDE.md:112, 245
• Continuity Flag: The --continue flag is used to instruct the CLI to resume the previous session, providing it with conversational context. The --no-continue flag can be used to start a fresh, isolated iteration.
  Sources: CLAUDE.md:114, 303-305, README.md:246-249.
• Session Lifecycle: The session is automatically reset under certain conditions, such as when the circuit breaker opens, on a manual interrupt (Ctrl+C), or upon project completion, to prevent the AI from getting stuck in a faulty context. A manual reset can also be triggered with the --reset-session flag.
  Sources: README.md:255-260, CLAUDE.md:261-270

Conclusion

The interaction with the Claude Code CLI is the cornerstone of the Ralph project. The system's architecture demonstrates a robust and adaptive approach to CLI automation, leveraging modern features like JSON output and session management while maintaining backward compatibility. By wrapping the CLI with intelligent logic for versioning, response parsing, and session control, Ralph transforms a simple command-line tool into a powerful engine for autonomous software development.

Sources: CLAUDE.md, ralph_import.sh, create_files.sh