Feature: Autonomous Development Loop

Relevant source files

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

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

The Autonomous Development Loop, primarily implemented in ralph_loop.sh, is the core engine of the Ralph for Claude Code system. It enables continuous, autonomous software development by repeatedly executing the Claude Code AI with a given set of instructions. The system is designed with safeguards like API rate limiting, intelligent exit detection, and status monitoring to manage the development process without human intervention until the project goals are met or a blocker is encountered.

The loop's behavior is guided by a series of control files, most notably PROMPT.md, which provides the AI with its objectives, principles, and status reporting requirements for each cycle. This allows Ralph to iteratively work on a codebase, run tests, and update documentation until it determines the project is complete.

Sources: create_files.sh:11-16, README.md:16-19, templates/PROMPT.md:3-8

Architecture and Core Components

The loop system is composed of several shell scripts, control files, and state-tracking files that work together to create the autonomous cycle.

Sources: create_files.sh, CLAUDE.md:10-14, README.md:213-224

Component Overview

The following diagram illustrates the main components and their interactions.

Key Components

Component	Description	Source File
ralph_loop.sh	The main script that orchestrates the autonomous development cycle. It handles initialization, rate limiting, execution, and exit detection.	create_files.sh:11-404
ralph_monitor.sh	A live terminal dashboard that displays real-time status from status.json and logs/ralph.log.	create_files.sh:407-518
PROMPT.md	The primary instruction file for the AI agent. It defines objectives, principles, and critical status reporting formats.	templates/PROMPT.md
@fix_plan.md	A prioritized to-do list that the AI uses to determine the next task. The AI updates this file as it completes work.	templates/fix_plan.md
status.json	A JSON file containing the real-time status of the loop, including loop count, API calls, and current action.	create_files.sh:86-102
.call_count	A hidden file that tracks the number of API calls made in the current hour for rate limiting.	create_files.sh:23, 133-142
.exit_signals	A JSON file that tracks signals for graceful termination, such as consecutive test-only loops or "done" signals.	create_files.sh:26, 52-55

Sources: create_files.sh, templates/PROMPT.md, CLAUDE.md:24-31

Main Execution Flow

The main function in ralph_loop.sh orchestrates the entire autonomous cycle. It runs an infinite loop that is broken only when graceful exit conditions are met.

This flowchart shows the logic of a single loop iteration.

The core logic within the while true loop is as follows:

1. Initialization: The loop counter is incremented, and init_call_tracking is called to reset the API call counter if a new hour has started.
2. Rate Limit Check: can_make_call checks if the number of API calls has exceeded MAX_CALLS_PER_HOUR. If so, wait_for_reset is called, which pauses execution until the next hour.
3. Graceful Exit Check: should_exit_gracefully evaluates several conditions to determine if the project is complete. If so, the loop breaks.
4. Status Update: status.json is updated to reflect that the loop is executing.
5. Execution: execute_claude_code runs the Claude Code CLI, piping in PROMPT.md and saving the output to a timestamped log file in logs/.
6. Post-Execution: The status is updated based on success or failure, and a brief pause occurs before the next iteration.
7. Signal Handling: A trap is set to call the cleanup function on SIGINT or SIGTERM, ensuring a graceful shutdown if the user interrupts the process.

Sources: create_files.sh:305-353, 299-302

Configuration

The loop's behavior can be modified through command-line arguments and internal configuration variables.

Parameter	Flag	Description	Default Value
MAX_CALLS_PER_HOUR	-c, --calls	Sets the maximum number of Claude Code API calls allowed per hour.	100
PROMPT_FILE	-p, --prompt	Specifies the path to the main prompt file.	PROMPT.md
STATUS_FILE	(Internal)	The file to write real-time JSON status to.	status.json
LOG_DIR	(Internal)	The directory for storing all execution logs.	logs
EXIT_SIGNALS_FILE	(Internal)	The file for tracking exit conditions.	.exit_signals

Sources: create_files.sh:18-32, 374-391, README.md:462-475

State Management

The loop maintains its state across executions using several files in the project root.

File	Purpose	Data Format
status.json	Provides a real-time snapshot of the loop's status for monitoring.	JSON
.call_count	A single integer representing API calls made in the current hour.	Plain Text
.last_reset	A timestamp (YYYYmmddHH) indicating when the call counter was last reset.	Plain Text
.exit_signals	Tracks consecutive signals that might lead to a graceful exit.	JSON

Sources: create_files.sh:20-29, 40-55, 86-102

status.json Structure

The status.json file is updated on each loop and provides a structured overview for the ralph_monitor.sh script or other external tools.

{
    "timestamp": "2025-09-30T12:00:00-04:00",
    "loop_count": 5,
    "calls_made_this_hour": 42,
    "max_calls_per_hour": 100,
    "last_action": "executing",
    "status": "running",
    "exit_reason": "",
    "next_reset": "13:00:00"
}

Sources: create_files.sh:86-102, tests/helpers/fixtures.bash:198-211

Rate Limiting

To prevent excessive API usage, the loop includes a robust rate-limiting mechanism.

The following sequence diagram shows how the rate limit is checked and handled.

Key functions involved:

• can_make_call(): Checks if $(cat .call_count) is less than MAX_CALLS_PER_HOUR.
• increment_call_counter(): Increments the value in .call_count.
• wait_for_reset(): Calculates the time remaining until the next hour, displays a countdown, and sleeps for that duration before resetting the counter.

Sources: create_files.sh:122-181

Intelligent Exit Detection

A key feature of the loop is its ability to determine when the project is "done" and terminate gracefully. This logic is encapsulated in the should_exit_gracefully function.

This prevents the agent from getting stuck in "busy work" loops, such as repeatedly running tests without making progress.

Sources: create_files.sh:184-243, templates/PROMPT.md:73-82

Exit Conditions

The loop will exit if any of the following conditions are met:

Condition	Threshold Variable	Default	Description
Test Saturation	MAX_CONSECUTIVE_TEST_LOOPS	3	Exits if the AI performs only testing for 3 consecutive loops.
Completion Signals	MAX_CONSECUTIVE_DONE_SIGNALS	2	Exits if the AI reports the task is "done" or "complete" twice in a row.
Strong Indicators	(Hardcoded)	2	Exits if 2 or more strong completion indicators are found in recent outputs.
Plan Completion	(File Check)	N/A	Exits if all tasks in @fix_plan.md are checked off ([x]).

Sources: create_files.sh:27-30, 184-243, CLAUDE.md:154-157

Exit Logic Flow

Prompting and AI Control

The AI's behavior within the loop is not hardcoded; it is directed by the content of PROMPT.md. This file instructs the AI on its objectives, principles, and, most importantly, how to report its status.

The RALPH_STATUS Block

A critical part of the PROMPT.md template is the RALPH_STATUS block. The AI is instructed to include this block at the end of every response. The ralph_loop.sh script (or more advanced versions in the repo's future plans) parses this block to understand the outcome of the loop iteration.

The structure is as follows:

---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:43-53

The EXIT_SIGNAL: true field is a direct instruction from the AI to the loop control script that it believes the project is complete, which is a primary trigger for the graceful exit mechanism.

Sources: templates/PROMPT.md:55-61

Summary

The Autonomous Development Loop is a sophisticated system that combines shell scripting, file-based state management, and carefully engineered AI prompts to automate the software development lifecycle. By implementing robust controls for rate limiting, status monitoring, and intelligent completion detection, it provides a framework for Claude Code to work on projects autonomously while minimizing wasted resources and preventing infinite loops. Its modular design, relying on external control files like PROMPT.md and @fix_plan.md, makes it a flexible and powerful tool for AI-driven development.

Sources: README.md:16-19, 81-83, CONTRIBUTING.md:21-26