Features added:
- Added --timeout/-t option to set execution timeout in minutes
- Default timeout increased from 10 to 15 minutes
- Validation: timeout must be 1-120 minutes
- Shows timeout in execution start message
Usage examples:
- ralph --monitor # 15-minute default timeout
- ralph --monitor --timeout 30 # 30-minute timeout for complex tasks
- ralph --verbose --timeout 5 # 5-minute timeout with progress logs
Benefits:
- Prevents hanging on very complex tasks requiring >15 minutes
- Allows shorter timeouts for simpler tasks to fail faster
- User can adjust based on their specific project complexity
- Clear feedback about configured timeout in logs
Key improvements:
- Added --verbose flag to control 10-second progress updates in logs
- Real-time progress now shows in monitor display only (not logs)
- Created progress.json file for monitor communication
- Monitor shows live Claude Code progress with spinner and elapsed time
- Clean logs by default, detailed progress available with --verbose
Usage:
- ralph --monitor # Clean logs, progress in monitor only
- ralph --monitor --verbose # Progress in both monitor and logs
- ralph --verbose # Just verbose logs without monitor
Monitor now displays:
┌─ Claude Code Progress ──────────────────────────────┐
│ Status: ⠋ Working (120s elapsed)
│ Output: Analyzing authentication system...
└─────────────────────────────────────────────────────┘
This keeps logs clean while providing rich real-time feedback in the monitor.
Features added:
- Animated progress spinner (⠋⠙⠹⠸) during Claude Code execution
- Real-time display of last output line from Claude Code
- Timer showing elapsed execution time in 10-second intervals
- 10-minute timeout for Claude Code execution to prevent hanging
- Visual indicators: ⏳ starting, ✅ success, ❌ failure
Counter fixes:
- Fixed call counter jumping issue by only incrementing on successful execution
- Counter now accurately reflects actual successful Claude Code calls
- Prevents double-counting on retries or failures
Monitoring improvements:
- Shows 'Claude Code working... (30s elapsed)' with spinner
- Displays last line of output: 'Claude Code: Reading file... (40s)'
- Clear success/failure indicators in logs
- Better visibility into long-running operations
- Changed from 'npx @anthropic-ai/claude-code' to 'claude'
- This assumes Claude Code is installed globally with npm install -g
- Updated ralph_loop.sh, ralph_import.sh, and README.md
- Much cleaner and faster execution without npx overhead
- Updated from @anthropic/claude-code to @anthropic-ai/claude-code
- This was causing npm 404 errors when trying to execute Claude Code
- Fixed in ralph_loop.sh, ralph_import.sh, install.sh, and README.md
- Ralph should now be able to successfully execute Claude Code commands
The issue was in line 378: if [[ $? -eq 0 ]]
- $? was checking the return code of 'local exit_reason=$(...)'
- This command always succeeds, so $? was always 0
- This caused Ralph to always exit immediately after loop #1
Fixed by:
- Calling should_exit_gracefully directly in the if condition
- Only calling it again to get exit reason if it returns 0 (exit needed)
- This properly checks the function's actual return code
- Add logging to show total_items and completed_items counts
- Add final debug statement to confirm function completion
- This will help identify if the fix_plan completion check is the culprit
- The debug log_status calls in should_exit_gracefully() were being
captured as stdout when called with
- This caused the debug messages to be treated as the exit reason
- Fixed by redirecting debug logging to stderr with >&2
- Ralph should now continue past the exit condition check properly
- Add debug statements to identify which exit condition is triggering
- Log each step of @fix_plan.md parsing and task completion checking
- Add logging for jq operations and file reading
- This should help identify why Ralph immediately exits after loop #1
🐛 Bug Fix: Silent Exit Issue
- Ralph was silently exiting when PROMPT.md not found (no error shown)
- Added comprehensive error handling with helpful guidance
- Now clearly explains when directory is not a Ralph project
🎯 Enhanced User Experience:
- Detects partial Ralph projects vs completely wrong directories
- Provides specific actionable solutions:
1. ralph-setup my-project (create new)
2. ralph-import requirements.md (import existing)
3. Navigate to existing Ralph project
4. Create PROMPT.md manually
- Updated help text with "IMPORTANT" note about project directories
- Added example workflow in help documentation
🔧 Technical Improvements:
- Better error detection logic
- Informative messages instead of silent failures
- Maintains proper exit codes for scripting
- Clear guidance for different scenarios
This resolves the confusing behavior where ralph would start logging
but then silently exit without explanation when run outside a Ralph project.
Major architectural change to make Ralph available as global commands:
🌟 New Global Installation System:
- Add install.sh script for global installation to ~/.local/bin
- Creates ralph, ralph-monitor, ralph-setup global commands
- Installs templates and scripts to ~/.ralph/ directory
- Automatic dependency checking and PATH configuration
🚀 Enhanced User Experience:
- ralph-setup my-project (run from anywhere, no directory constraints)
- ralph --monitor (start from any project directory)
- ralph-monitor (global monitoring command)
- No more ../ralph_loop.sh relative path requirements
🔧 Improved Architecture:
- Global template system in ~/.ralph/templates/
- Smart path detection (global commands vs local scripts)
- Maintains backward compatibility during transition
- Clean separation of installation vs project files
📚 Updated Documentation:
- All examples now use global commands (ralph vs ../ralph_loop.sh)
- Clear installation instructions with ./install.sh
- Global command reference in CLAUDE.md
- Streamlined Quick Start workflow
This makes Ralph much more professional and user-friendly by eliminating
directory structure requirements and providing standard Unix command 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).
- Fix nested EOF heredoc conflicts in update_status() and show_help() functions
- Use unique delimiters (STATUSEOF, HELPEOF) to avoid conflicts
- Complete Ralph for Claude Code implementation with all components:
- ralph_loop.sh: Main autonomous development loop with rate limiting
- ralph_monitor.sh: Live monitoring dashboard
- setup.sh: Project initialization script
- templates/: Template files for new projects
- .gitignore: Comprehensive ignore rules
All scripts are now executable and syntax-validated.
Features:
- Intelligent exit detection (knows when project is done)
- Test limiting (enforces 20% rule to prevent busy work)
- Rate limiting with graceful API usage management
- Live monitoring dashboard with real-time progress
- Auto-generated documentation every 10 iterations
- Specification-driven development approach
Based on Geoffrey Huntley's Ralph technique, adapted for Claude Code.
