From d81519584f31c2a442f7b2cc029a3754fc0d18e8 Mon Sep 17 00:00:00 2001 From: frankbria Date: Wed, 27 Aug 2025 09:33:25 -0700 Subject: [PATCH] Add tmux integration for seamless monitoring experience - Add --monitor flag to ralph_loop.sh for integrated tmux monitoring - Automatically creates split-pane session with Ralph loop and monitor - Include tmux availability check with installation instructions - Update documentation to recommend tmux workflow - Add tmux session management commands and controls - Preserve all existing functionality for users without tmux New workflow: ../ralph_loop.sh --monitor # Creates split session automatically Traditional workflow still supported: ../ralph_loop.sh # Terminal 1 ../ralph_monitor.sh # Terminal 2 System requirements updated to include tmux (recommended). --- CLAUDE.md | 19 ++++++++++++--- README.md | 42 ++++++++++++++++++++++++++++---- ralph_loop.sh | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 119 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 683a537..abb040c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,11 +26,14 @@ cd my-project-name ### Running the Ralph Loop ```bash -# Start the autonomous development loop (from project directory) +# Start with integrated tmux monitoring (recommended) +../ralph_loop.sh --monitor + +# Start without monitoring ../ralph_loop.sh -# With custom parameters -../ralph_loop.sh --calls 50 --prompt my_custom_prompt.md +# With custom parameters and monitoring +../ralph_loop.sh --monitor --calls 50 --prompt my_custom_prompt.md # Check current status ../ralph_loop.sh --status @@ -38,8 +41,15 @@ cd my-project-name ### Monitoring ```bash -# Launch live monitoring dashboard (from project directory) +# Integrated tmux monitoring (recommended) +../ralph_loop.sh --monitor + +# Manual monitoring in separate terminal ../ralph_monitor.sh + +# tmux session management +tmux list-sessions +tmux attach -t ``` ### System Setup @@ -103,6 +113,7 @@ Templates in `templates/` provide starting points for new projects: Ralph integrates with: - **Claude Code CLI**: Uses `npx @anthropic/claude-code` as the execution engine +- **tmux**: Terminal multiplexer for integrated monitoring sessions - **Git**: Expects projects to be git repositories - **jq**: For JSON processing of status and exit signals - **Standard Unix tools**: bash, grep, date, etc. diff --git a/README.md b/README.md index d261e17..d92beef 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,12 @@ Edit the generated files: ### 4. Start the Ralph Loop ```bash -# Start autonomous development -../ralph_loop.sh +# Recommended: Start with integrated tmux monitoring (requires tmux) +../ralph_loop.sh --monitor -# Monitor progress (in another terminal) -../ralph_monitor.sh +# Alternative: Manual monitoring (two separate terminals) +../ralph_loop.sh # Terminal 1: Ralph loop +../ralph_monitor.sh # Terminal 2: Live monitor ``` ## 📖 How It Works @@ -74,6 +75,9 @@ Ralph automatically stops when it detects: # Default: 100 calls per hour ../ralph_loop.sh --calls 50 +# With integrated monitoring +../ralph_loop.sh --monitor --calls 50 + # Check current usage ../ralph_loop.sh --status ``` @@ -83,6 +87,9 @@ Ralph automatically stops when it detects: ```bash # Use custom prompt file ../ralph_loop.sh --prompt my_custom_instructions.md + +# With integrated monitoring +../ralph_loop.sh --monitor --prompt my_custom_instructions.md ``` ### Exit Thresholds @@ -138,15 +145,33 @@ my-project/ - **Bash 4.0+** - For script execution - **Claude Code CLI** - `npx @anthropic/claude-code` +- **tmux** - Terminal multiplexer for integrated monitoring (recommended) - **jq** - JSON processing for status tracking - **Git** - Version control (projects are initialized as git repos) - **Standard Unix tools** - grep, date, etc. +### Installing tmux + +```bash +# Ubuntu/Debian +sudo apt-get install tmux + +# macOS +brew install tmux + +# CentOS/RHEL +sudo yum install tmux +``` + ## 📊 Monitoring and Debugging ### Live Dashboard ```bash +# Integrated tmux monitoring (recommended) +../ralph_loop.sh --monitor + +# Manual monitoring in separate terminal ../ralph_monitor.sh ``` @@ -156,6 +181,12 @@ Shows real-time: - Recent log entries - Rate limit countdown +**tmux Controls:** +- `Ctrl+B` then `D` - Detach from session (keeps Ralph running) +- `Ctrl+B` then `←/→` - Switch between panes +- `tmux list-sessions` - View active sessions +- `tmux attach -t ` - Reattach to session + ### Status Checking ```bash @@ -171,7 +202,8 @@ tail -f logs/ralph.log - **Rate Limits** - Ralph automatically waits and displays countdown - **Stuck Loops** - Check `@fix_plan.md` for unclear or conflicting tasks - **Early Exit** - Review exit thresholds if Ralph stops too soon -- **Missing Dependencies** - Ensure Claude Code CLI is installed +- **Missing Dependencies** - Ensure Claude Code CLI and tmux are installed +- **tmux Session Lost** - Use `tmux list-sessions` and `tmux attach` to reconnect ## 🤝 Contributing diff --git a/ralph_loop.sh b/ralph_loop.sh index 19d19d4..e37a970 100755 --- a/ralph_loop.sh +++ b/ralph_loop.sh @@ -15,6 +15,7 @@ MAX_CALLS_PER_HOUR=100 # Adjust based on your plan SLEEP_DURATION=3600 # 1 hour in seconds CALL_COUNT_FILE=".call_count" TIMESTAMP_FILE=".last_reset" +USE_TMUX=false # Exit detection configuration EXIT_SIGNALS_FILE=".exit_signals" @@ -33,6 +34,61 @@ NC='\033[0m' # No Color # Initialize directories mkdir -p "$LOG_DIR" "$DOCS_DIR" +# Check if tmux is available +check_tmux_available() { + if ! command -v tmux &> /dev/null; then + log_status "ERROR" "tmux is not installed. Please install tmux or run without --monitor flag." + echo "Install tmux:" + echo " Ubuntu/Debian: sudo apt-get install tmux" + echo " macOS: brew install tmux" + echo " CentOS/RHEL: sudo yum install tmux" + exit 1 + fi +} + +# Setup tmux session with monitor +setup_tmux_session() { + local session_name="ralph-$(date +%s)" + local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + + log_status "INFO" "Setting up tmux session: $session_name" + + # Create new tmux session detached + tmux new-session -d -s "$session_name" -c "$(pwd)" + + # Split window vertically to create monitor pane on the right + tmux split-window -h -t "$session_name" -c "$(pwd)" + + # Start monitor in the right pane + tmux send-keys -t "$session_name:0.1" "'$script_dir/ralph_monitor.sh'" Enter + + # Start ralph loop in the left pane (exclude tmux flag to avoid recursion) + local ralph_cmd="'$script_dir/ralph_loop.sh'" + if [[ "$MAX_CALLS_PER_HOUR" != "100" ]]; then + ralph_cmd="$ralph_cmd --calls $MAX_CALLS_PER_HOUR" + fi + if [[ "$PROMPT_FILE" != "PROMPT.md" ]]; then + ralph_cmd="$ralph_cmd --prompt '$PROMPT_FILE'" + fi + + tmux send-keys -t "$session_name:0.0" "$ralph_cmd" Enter + + # Focus on left pane (main ralph loop) + tmux select-pane -t "$session_name:0.0" + + # Set window title + tmux rename-window -t "$session_name:0" "Ralph: Loop | Monitor" + + log_status "SUCCESS" "Tmux session created. Attaching to session..." + log_status "INFO" "Use Ctrl+B then D to detach from session" + log_status "INFO" "Use 'tmux attach -t $session_name' to reattach" + + # Attach to session (this will block until session ends) + tmux attach-session -t "$session_name" + + exit 0 +} + # Initialize call tracking init_call_tracking() { local current_hour=$(date +%Y%m%d%H) @@ -310,6 +366,7 @@ Options: -c, --calls NUM Set max calls per hour (default: $MAX_CALLS_PER_HOUR) -p, --prompt FILE Set prompt file (default: $PROMPT_FILE) -s, --status Show current status and exit + -m, --monitor Start with tmux session and live monitor (requires tmux) Files created: - $LOG_DIR/: All execution logs @@ -346,6 +403,10 @@ while [[ $# -gt 0 ]]; do fi exit 0 ;; + -m|--monitor) + USE_TMUX=true + shift + ;; *) echo "Unknown option: $1" show_help @@ -354,5 +415,11 @@ while [[ $# -gt 0 ]]; do esac done +# If tmux mode requested, set it up +if [[ "$USE_TMUX" == "true" ]]; then + check_tmux_available + setup_tmux_session +fi + # Start the main loop main