Feature: Intelligent Exit Detection
Relevant source files
The following files were used as context for generating this wiki page:
The Intelligent Exit Detection system is a core safeguard within the Ralph autonomous development loop. Its primary purpose is to automatically determine when a project's objectives are complete, allowing the loop to terminate gracefully. This prevents infinite execution, manages API usage, and provides a clear signal that the AI agent considers its work finished.
The system employs a multi-faceted approach, analyzing AI-generated completion signals, tracking task progress against a plan, and detecting behavioral patterns indicative of stagnation or completion, such as repeated test-only loops. This logic is primarily encapsulated within the should_exit_gracefully function in the main ralph_loop.sh script, which is called at the beginning of each development cycle.
Sources: README.md, create_files.sh:31-40, 203-247
Core Logic Flow
The decision to exit is made by the should_exit_gracefully function within ralph_loop.sh. At the start of each loop, this function evaluates several conditions in a specific order to determine if a graceful exit is warranted.
The following diagram illustrates the logical flow of the should_exit_gracefully function.
Sources: create_files.sh:203-247
Exit Signal Sources
Ralph aggregates signals from multiple sources to make an informed exit decision. These sources range from explicit instructions from the AI to implicit indicators based on project state.
1. AI-Generated Completion Signals
The most direct signal comes from the AI agent itself. The PROMPT.md template instructs the agent to include a special status block in its output. When the agent determines the project is complete, it sets EXIT_SIGNAL: true within this block.
Example Status Block from PROMPT.md:
---RALPH_STATUS---
STATUS: COMPLETE
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 1
TESTS_STATUS: PASSING
WORK_TYPE: DOCUMENTATION
EXIT_SIGNAL: true
RECOMMENDATION: All requirements met, project ready for review
---END_RALPH_STATUS---
The response_analyzer.sh library (described in CLAUDE.md) is responsible for parsing this output, detecting the EXIT_SIGNAL, and recording it. These signals are tracked as "done signals" or "completion indicators" in the .exit_signals state file.
Sources: templates/PROMPT.md:45-81, CLAUDE.md:80-94
2. Task Plan Completion
A key indicator of project completion is the status of the @fix_plan.md file. This file serves as a prioritized TODO list for the agent. The exit logic directly inspects this file to see if all tasks are marked as complete.
The should_exit_gracefully function checks if the total number of checklist items (- [ ] or - [x]) equals the number of completed items (- [x]). If they match and there is at least one item, it triggers a graceful exit.
Sources: create_files.sh:235-242, templates/fix_plan.md
3. Loop Stagnation and Behavioral Patterns
The system also detects when the agent is no longer making meaningful progress, even if it hasn't explicitly signaled completion. This is determined by analyzing patterns over the last few loops.
- Test Saturation: If the agent runs only tests for several consecutive loops without implementing new code, it's a strong indicator that it believes all features are complete. The
MAX_CONSECUTIVE_TEST_LOOPSthreshold controls this. - Repeated "Done" Signals: If the agent sends multiple completion signals (even if not strong enough to exit on their own), the system will exit after a certain threshold (
MAX_CONSECUTIVE_DONE_SIGNALS).
These behavioral patterns are tracked in the .exit_signals file.
Sources: create_files.sh:217-234, CLAUDE.md:195-197
State Management: The .exit_signals File
To track completion indicators over time, the system uses a hidden state file named .exit_signals. This file is a JSON object that stores arrays of recent signals.
- Initialization: The file is created with empty arrays if it doesn't exist.
- Structure:
{ "test_only_loops": [], "done_signals": [], "completion_indicators": [] } - Function: The
response_analyzer.shcomponent is responsible for parsing the AI's output and populating these arrays. Theshould_exit_gracefullyfunction then reads this file to count the number of recent signals of each type. The file is intended to be cleared or managed to only reflect recent history (e.g., the last 5 loops).
Sources: create_files.sh:32-35, 68-71, 212-215
Configuration and Thresholds
The sensitivity of the exit detection logic is controlled by several configurable variables defined at the top of ralph_loop.sh. These thresholds determine how many signals or patterns must be observed before an exit is triggered.
| Variable | Default Value | Description |
|---|---|---|
MAX_CONSECUTIVE_TEST_LOOPS | 3 | The number of consecutive loops with only testing activity before exiting. |
MAX_CONSECUTIVE_DONE_SIGNALS | 2 | The number of consecutive "done" signals from the AI before exiting. |
TEST_PERCENTAGE_THRESHOLD | 30 | If more than this percentage of recent loops are test-only, it's flagged (currently used to trigger the test_saturation exit). |
Sources: create_files.sh:32-35, CLAUDE.md:195-197
Summary
The Intelligent Exit Detection feature is a sophisticated system that ensures the Ralph agent can operate autonomously without running indefinitely. By combining explicit signals from the AI (EXIT_SIGNAL), project state analysis (@fix_plan.md), and behavioral pattern detection (stagnation), it provides a reliable and robust mechanism for determining project completion. This allows for efficient use of resources and provides a definitive end-point to the development loop.
Sources: README.md:118-124, create_files.sh:203-247