Configuration
Relevant source files
The following files were used as context for generating this wiki page:Configuration for the Ralph for Claude Code system is managed through a combination of command-line arguments, internal script variables, project-specific control files, and state-tracking files. This layered approach allows for both global defaults and fine-grained, per-project customization. The system is designed to be configurable at runtime without modifying the core scripts for most use cases.
The primary configuration happens when invoking the main loop script, ralph_loop.sh (or the global ralph command), which reads both command-line flags and a set of control files within the target project's directory. Future plans include support for a centralized .ralphrc configuration file to further streamline setup.
Sources: README.md:415-416, IMPLEMENTATION_PLAN.md:30
Runtime Configuration
Runtime configuration is primarily handled by the ralph_loop.sh script, which defines default behaviors that can be overridden by command-line arguments.
Sources: ralph_loop.sh
Command-Line Arguments
The ralph command accepts several flags to modify its behavior for a specific run. These flags take precedence over the internal default variables.
The following diagram shows the flow of how command-line arguments are parsed to override default settings.
Sources: ralph_loop.sh:383-424
The table below details the available command-line arguments for the ralph command.
| Flag (Short) | Flag (Long) | Parameter | Description | Default Value |
|---|---|---|---|---|
-h | --help | - | Shows the help message and exits. | - |
-c | --calls | NUM | Sets the maximum number of Claude API calls per hour. | 100 |
-p | --prompt | FILE | Specifies the path to the prompt file to use. | PROMPT.md |
-s | --status | - | Shows the current status from status.json and exits. | - |
-m | --monitor | - | Starts the loop within a tmux session with a live monitor. | - |
-v | --verbose | - | Shows detailed progress updates during execution. | - |
-t | --timeout | MIN | Sets the execution timeout for Claude Code in minutes (1-120). | 15 |
--output-format | FORMAT | Sets the output format (json or text). | json | |
--allowed-tools | TOOLS | Sets the allowed Claude tools as a comma-separated string. | Write,Bash(git *),Read | |
--no-continue | - | Disables session continuity, starting a fresh loop. | - | |
--reset-circuit | - | Resets the circuit breaker state. | - | |
--circuit-status | - | Shows the current circuit breaker status. | - | |
--reset-session | - | Resets the session state manually. | - |
Sources: ralph_loop.sh:383-424, README.md:440-456, CLAUDE.md:430-446
Internal Configuration Variables
The ralph_loop.sh script defines several variables at the top of the file that control its core behavior. These act as the default settings if not overridden by command-line flags.
| Variable | Default Value | Description |
|---|---|---|
PROMPT_FILE | "PROMPT.md" | The main prompt file that drives each loop iteration. |
LOG_DIR | "logs" | Directory to store execution logs for each loop. |
DOCS_DIR | "docs/generated" | Directory for auto-generated documentation. |
STATUS_FILE | "status.json" | File to store real-time status in JSON format. |
CLAUDE_CODE_CMD | "npx @anthropic/claude-code" | The command used to execute Claude Code. |
MAX_CALLS_PER_HOUR | 100 | Default rate limit for API calls per hour. |
CALL_COUNT_FILE | ".call_count" | Hidden file to track the number of API calls made in the current hour. |
TIMESTAMP_FILE | ".last_reset" | Hidden file to store the timestamp of the last rate limit counter reset. |
EXIT_SIGNALS_FILE | ".exit_signals" | Hidden file to track signals for graceful exit conditions. |
Sources: create_files.sh:15-29, ralph_loop.sh:15-29
Exit Condition Thresholds
The script uses a set of thresholds to determine when to exit gracefully, preventing infinite loops or non-productive work.
| Variable | Default Value | Description |
|---|---|---|
MAX_CONSECUTIVE_TEST_LOOPS | 3 | Exits if this many consecutive loops perform only testing. |
MAX_CONSECUTIVE_DONE_SIGNALS | 2 | Exits after receiving this many "done" signals from Claude. |
TEST_PERCENTAGE_THRESHOLD | 30 | Flags a potential exit condition if testing constitutes more than this percentage of recent loops. |
Sources: ralph_loop.sh:31-34, README.md:315-319
Project-Level Configuration
Each project managed by Ralph contains its own set of configuration files that define the scope, tasks, and build instructions. These files are created by the setup.sh script from templates.
This diagram illustrates how the main loop interacts with project-specific configuration files.
| File | Purpose |
|---|---|
PROMPT.md | Contains the main development instructions, objectives, and principles for the AI agent. It defines the overall goal of the project. |
@fix_plan.md | A prioritized to-do list in Markdown checklist format. Ralph uses this file to determine the next task to work on. |
@AGENT.md | Stores project-specific build, test, and run commands. It also serves as a knowledge base for the agent to learn about the project's toolchain. |
specs/ | A directory containing detailed technical specifications and requirements for the project. |
Sources: README.md:324-334, CLAUDE.md:154-164
Modern Claude CLI Configuration
The system can leverage modern features of the Claude Code CLI. This is configured through variables in ralph_loop.sh and ralph_import.sh.
| Variable | Default Value | Description |
|---|---|---|
CLAUDE_OUTPUT_FORMAT | "json" | Sets the output format from the Claude CLI. Enables structured data parsing. |
CLAUDE_ALLOWED_TOOLS | ('Read' 'Write' 'Bash(mkdir:*)' 'Bash(cp:*)') | An array of tool permissions granted to the Claude agent. |
CLAUDE_MIN_VERSION | "2.0.76" | The minimum required version of the Claude Code CLI to use modern features. |
CLAUDE_USE_CONTINUE | true | Enables session continuity to maintain context between loop iterations. |
Sources: CLAUDE.md:80-84, ralph_import.sh:8-12
State and Tracking Files
Ralph uses several files, typically hidden, to maintain state between executions and across loop iterations.
| File | Purpose |
|---|---|
status.json | A JSON file containing the real-time status of the Ralph loop, including loop count, API calls, and current action. |
.call_count | Stores the number of API calls made within the current hour for rate-limiting purposes. |
.last_reset | Stores the timestamp of the last hourly rate-limit counter reset. |
.exit_signals | A JSON file tracking signals related to graceful exit conditions, such as test-only loops and completion signals. |
.claude_session_id | Stores the session ID to enable context continuity between loops. It has a 24-hour expiration. |
.ralph_session_history | Logs the last 50 session transitions for debugging purposes. |
Sources: ralph_loop.sh:18-29, 80-94, CLAUDE.md:99-100, 260-264
The status.json file provides a structured overview of the loop's current state.
This diagram shows the schema for the status.json file.
Sources: ralph_loop.sh:80-94
Summary
The configuration of the Ralph for Claude Code project is decentralized, relying on a hierarchy of command-line arguments, internal script variables, and project-specific files. This design provides flexibility, allowing users to run the system with default settings for simple tasks or to create highly customized configurations for complex projects. The use of plain text and JSON for control and state files makes the system transparent and easy to debug. Future development aims to centralize some of these settings into a .ralphrc file for easier management.
Sources: README.md:415-416