Home

Relevant source files

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

• README.md
• create_files.sh
• CLAUDE.md
• CONTRIBUTING.md
• ralph_import.sh
• TESTING.md
• IMPLEMENTATION_PLAN.md
• IMPLEMENTATION_STATUS.md
• templates/PROMPT.md
• templates/AGENT.md
• SPECIFICATION_WORKSHOP.md
• tests/helpers/fixtures.bash

Ralph for Claude Code is an autonomous AI development system designed to enable continuous development cycles. It uses the Claude Code CLI (@anthropic/claude-code) to iteratively work on a software project based on a set of instructions and specifications. The system features an autonomous loop with intelligent exit detection, API rate limiting, a circuit breaker to prevent runaway processes, and a live monitoring dashboard.

The core principle is to provide a framework where an AI agent, "Ralph," can read requirements, implement features, run tests, and track progress until the project is complete. This is managed through a series of shell scripts, configuration files, and state-tracking mechanisms. The project is currently at version 0.9.8 and has a comprehensive test suite with 276 passing tests.

Sources: README.md:1-12, CLAUDE.md:3-5, IMPLEMENTATION_STATUS.md:5

Core Architecture

The system is composed of several key shell scripts that provide the main functionality, supported by a modular library and a standardized project structure.

Sources: CLAUDE.md:9-12, CONTRIBUTING.md:52-67, create_files.sh

System Components

The following diagram shows the main components of the Ralph system and their relationships.

Main Scripts

Script	Description	Source File
ralph_loop.sh	The main autonomous loop that repeatedly executes the Claude Code CLI. It manages rate limiting, exit detection, and state tracking.	create_files.sh:10-401
ralph_monitor.sh	A live monitoring dashboard that displays the current status of the ralph_loop.sh process by reading status.json and logs/ralph.log.	create_files.sh:404-508
setup.sh	An initialization script that creates a new Ralph-managed project with the standard directory structure and template files.	create_files.sh:511-541
ralph_import.sh	A tool to convert existing Product Requirement Documents (PRDs) or specifications into the Ralph project format using Claude Code.	ralph_import.sh
create_files.sh	A bootstrap script that generates the entire Ralph for Claude Code repository structure and all its core scripts.	create_files.sh

Sources: CLAUDE.md:14-25, README.md:280-304, create_files.sh

Modular Libraries

The system uses a modular architecture with reusable components located in the lib/ directory.

• lib/circuit_breaker.sh: Implements a circuit breaker pattern to prevent runaway loops by detecting stagnation or repeated errors. It has three states: CLOSED (normal), HALF_OPEN (monitoring), and OPEN (halted).
• lib/response_analyzer.sh: Intelligently analyzes the output from the Claude Code CLI for completion signals, errors, and work type. It supports both JSON and text output formats.
• lib/date_utils.sh: Provides cross-platform date and time utilities for logging and rate limit calculations.

Sources: CLAUDE.md:27-49, CONTRIBUTING.md:59-62

Development Workflow

The workflow is divided into a one-time installation and a per-project setup and execution phase.

This diagram illustrates the two main phases of using Ralph: a one-time global installation followed by a repeatable process for each new project.

Sources: README.md:121-168, CONTRIBUTING.md:118-135

The Autonomous Loop (ralph_loop.sh)

The ralph_loop.sh script is the heart of the system. It orchestrates the continuous development cycle.

Loop Sequence

The following diagram details the sequence of events within a single iteration of the main loop.

Key Features of the Loop

• Rate Limiting: By default, the loop is limited to 100 API calls per hour. This is configurable via the --calls flag. The can_make_call and increment_call_counter functions manage the state stored in .call_count and .last_reset. If the limit is reached, wait_for_reset pauses execution until the next hour.
• Intelligent Exit Detection: The loop automatically stops when it determines the project is complete. The should_exit_gracefully function checks for several conditions:
  • Too many consecutive test-only loops (MAX_CONSECUTIVE_TEST_LOOPS).
  • Multiple "done" signals from Claude (MAX_CONSECUTIVE_DONE_SIGNALS).
  • All tasks in @fix_plan.md are checked off.
• Status Tracking: The update_status function writes the current state of the loop (loop count, calls made, status) to status.json, which is used by the ralph_monitor.sh dashboard.
• Circuit Breaker: To prevent runaway loops on persistent errors, a circuit breaker (lib/circuit_breaker.sh) monitors progress. It will "open" (halt the loop) if it detects stagnation (e.g., no file changes over several loops) or the same error repeating.

Sources: create_files.sh:124-178, 181-240, README.md:175-183, 230-243, CLAUDE.md:97-102, 143-150

Configuration and State Management

Ralph's behavior is guided by a set of control files within each project, and its state is tracked using hidden files in the project root.

Control Files

These files are intended to be edited by the user (or by Ralph itself) to guide the development process.

File	Purpose	Source
PROMPT.md	The main set of instructions for Ralph, defining its objectives, principles, and reporting format.	templates/PROMPT.md
@fix_plan.md	A prioritized to-do list in Markdown checklist format. Ralph works through these tasks from high to low priority.	create_files.sh:588-622
@AGENT.md	Contains build, test, and run instructions for the project. Ralph maintains this file to document its "learnings" about the codebase.	templates/AGENT.md
specs/	A directory to hold detailed technical specifications and requirements for the project.	create_files.sh:545-585

Sources: README.md:283-293, CLAUDE.md:88-95

State Files

These files are managed by the scripts to track the loop's state.

File	Purpose	Source
status.json	A JSON file containing the real-time status of the loop, for use by ralph_monitor.sh.	create_files.sh:82-98
.call_count	Stores the number of API calls made in the current hour.	create_files.sh:22, 131-133
.last_reset	Stores the timestamp of the last hourly rate-limit counter reset.	create_files.sh:23, 53-55
.exit_signals	A JSON file tracking signals that might lead to a graceful exit, like test-only loops or "done" signals.	create_files.sh:26, 58-60
.claude_session_id	Persists the session ID from the Claude CLI to allow for context continuity between loops.	CLAUDE.md:41, 117-118

Sources: create_files.sh:417-422, CLAUDE.md:200-203

PRD Import (ralph_import.sh)

The ralph-import command streamlines project setup by converting existing requirement documents (e.g., Markdown, text, JSON) into a structured Ralph project.

Conversion Process

1. Setup Project: It first runs ralph-setup to create a new project directory.
2. Create Prompt: It constructs a detailed prompt for Claude Code, instructing it to analyze the source PRD and generate the standard Ralph control files.
3. Execute Claude: It calls the Claude Code CLI. It prefers to use modern CLI flags like --output-format json for reliable, structured output. If the installed CLI version is too old, it automatically falls back to parsing plain text.
4. Parse Response: The parse_conversion_response function extracts structured data from the JSON output, including a summary, session ID, and lists of created or missing files.
5. Verify Files: It checks that the expected files (PROMPT.md, @fix_plan.md, specs/requirements.md) were created and reports the status to the user.

Sources: ralph_import.sh:293-455, README.md:185-227

Modern CLI Integration

The importer is designed to leverage modern Claude Code CLI features for better reliability.

• JSON Output: It requests JSON output to avoid brittle text parsing. The detect_response_format function checks if the output is valid JSON.
• Tool Permissions: It uses --allowedTools to grant Claude specific file system permissions (Read, Write, mkdir, cp) without requiring interactive user prompts.
• Version Check: The check_claude_version function verifies if the installed CLI meets the minimum version required for these features (2.0.76).

Sources: ralph_import.sh:12-16, 172-202, 293-320, CLAUDE.md:104-115

Testing Strategy

The project maintains a high standard of quality with a comprehensive test suite using the BATS (Bash Automated Testing System) framework. The mandatory quality gate is a 100% test pass rate.

Sources: TESTING.md:3, 19-27, CONTRIBUTING.md:179-185

Test Suite Overview

The tests are organized into unit and integration categories, covering all major components of the system.

Test File	# Tests	Description
test_cli_parsing.bats	27	Covers all 12 CLI flags for the main ralph command.
test_cli_modern.bats	29	Tests modern CLI features like JSON output and session continuity.
test_json_parsing.bats	36	Validates parsing of various JSON response formats.
test_session_continuity.bats	26	Tests the full session management lifecycle.
test_exit_detection.bats	20	Verifies the logic for intelligent graceful exits.
test_rate_limiting.bats	15	Checks rate-limiting and reset behavior.
test_loop_execution.bats	20	Integration tests for the main development loop.
test_installation.bats	14	Validates the global installation and uninstallation process.
test_project_setup.bats	36	Tests the setup.sh script and project initialization.
test_prd_import.bats	33	Tests the ralph_import.sh script and PRD conversion.

Sources: IMPLEMENTATION_STATUS.md:15-29, CLAUDE.md:434-448, TESTING.md:41-60

Summary

Ralph for Claude Code is a robust system for automating development workflows using an AI agent. Its architecture is built on a set of cooperative shell scripts that manage a continuous loop of code generation and testing. Key features like rate limiting, intelligent exit detection, a circuit breaker, and a comprehensive test suite ensure that the autonomous process is both productive and safe. The inclusion of tools like ralph-import and a live monitor makes it a practical and user-friendly framework for AI-driven software development.

Sources: README.md:8-12, CLAUDE.md:3-5