Feature: Live Monitoring with tmux
Relevant source files
The following files were used as context for generating this wiki page:The Live Monitoring feature provides a real-time terminal dashboard to observe the status of the autonomous ralph_loop.sh script. It is implemented in ralph_monitor.sh and is designed to run concurrently with the main development loop, offering immediate insights into its progress, API usage, and recent activities. The monitoring is recommended to be used via its tmux integration for a seamless, split-pane view.
This feature is crucial for observing the agent's behavior, debugging issues, and understanding when manual intervention might be required. It relies on a decoupled architecture where the main loop produces status files that the monitor script consumes.
Sources: create_files.sh:409-410, README.md:213-216, CLAUDE.md:21-22
Architecture and Data Flow
The monitoring system operates on a producer-consumer model. The ralph_loop.sh script acts as the producer, writing state to status.json and activity logs to logs/ralph.log. The ralph_monitor.sh script is the consumer, periodically reading these files to refresh its display.
Sources: create_files.sh:412-413, create_files.sh:101-115
This diagram illustrates the data flow between the main loop and the monitor.
The ralph_monitor.sh Script
This script is a self-contained bash application responsible for rendering the live dashboard.
Sources: create_files.sh:409-503
Core Components
| Component | Description | Source File |
|---|---|---|
REFRESH_INTERVAL | The interval in seconds at which the dashboard refreshes. Defaults to 2. | create_files.sh:414 |
STATUS_FILE | The primary JSON data source for status information. Defaults to status.json. | create_files.sh:412 |
LOG_FILE | The source for recent activity logs. Defaults to logs/ralph.log. | create_files.sh:413 |
display_status() | The main function that clears the screen and renders all UI components. | create_files.sh:445-495 |
cleanup() | A trap function that ensures the cursor is made visible again when the script is terminated (e.g., via Ctrl+C). | create_files.sh:436-442 |
Dashboard Layout
The monitor presents information in three main sections within the terminal.
- Header: Displays the title "🤖 RALPH MONITOR".
- Current Status: Shows key metrics parsed from
status.json, including loop count, current status, and API call usage. - Recent Activity: Displays the last 8 lines from
logs/ralph.logto provide context on recent events. - Footer: Shows control information (Ctrl+C to exit), the refresh interval, and the current timestamp.
Sources: create_files.sh:448-499
Data Sources
The monitor is non-invasive and relies entirely on files generated by ralph_loop.sh.
status.json
This file provides a structured snapshot of the loop's current state. It is overwritten on each significant action within the loop.
The following table details the fields found in status.json, as defined by the update_status function in ralph_loop.sh.
| Field | Type | Description |
|---|---|---|
timestamp | String (ISO 8601) | The timestamp of the last status update. |
loop_count | Number | The current iteration number of the main loop. |
calls_made_this_hour | Number | The number of API calls made in the current hour. |
max_calls_per_hour | Number | The configured maximum number of calls per hour. |
last_action | String | A description of the last action performed (e.g., "executing", "graceful_exit"). |
status | String | The overall status of the loop (e.g., "running", "completed", "error"). |
exit_reason | String | If the loop exited, the reason for termination (e.g., "plan_complete"). |
next_reset | String | The time for the next hourly API call counter reset. |
Sources: create_files.sh:101-115, tests/helpers/fixtures.bash:242-276
logs/ralph.log
A plain text file where all status messages from the ralph_loop.sh script are appended. The monitor displays the tail -n 8 of this file to show the most recent activities.
Sources: create_files.sh:89-90, create_files.sh:482-487
Usage and tmux Integration
The monitoring feature can be launched in two ways, with the integrated tmux session being the recommended method for a side-by-side view.
Sources: README.md:213, CLAUDE.md:100
Integrated tmux Mode
This is the primary way to use the monitor. It launches the ralph_loop.sh and ralph_monitor.sh scripts in a new tmux session with a vertical split.
- Command:
ralph --monitor
Sources: README.md:214, CLAUDE.md:101
The following sequence diagram shows the conceptual startup flow for the integrated tmux mode.
Sources: README.md:522, CLAUDE.md:100-103
Standalone Mode
The monitor can also be run as a separate command in a different terminal window.
- Command:
ralph-monitor
This is useful if you prefer not to use tmux or want to manage terminal windows manually.
Sources: README.md:217, CLAUDE.md:105
tmux Controls
When using the integrated mode, the following tmux commands are useful:
| Command | Action |
|---|---|
Ctrl+B then D | Detach from the session (leaves Ralph running in the background). |
tmux list-sessions | View all active tmux sessions. |
tmux attach -t <session-name> | Reattach to a detached session. |
Sources: README.md:562-565
Summary
The Live Monitoring feature is an essential observability tool for the Ralph for Claude Code project. By leveraging tmux and a simple file-based data exchange, it provides a robust, real-time view into the autonomous agent's operations without tightly coupling the monitoring logic to the main execution loop. This allows developers to track progress, manage API usage, and quickly diagnose issues as they arise.
Sources: CONTRIBUTING.md:49, create_files.sh:409-410