The OPEN state was terminal — once triggered, it persisted across
restarts with no automatic recovery. This adds two recovery mechanisms:
1. Cooldown timer (default): OPEN → HALF_OPEN after CB_COOLDOWN_MINUTES
(default 30). The existing HALF_OPEN logic handles recovery or re-trip.
2. Auto-reset option: CB_AUTO_RESET=true bypasses cooldown, resets to
CLOSED on startup for fully unattended operation.
Changes:
- Add parse_iso_to_epoch() to lib/date_utils.sh (cross-platform)
- Add cooldown + auto-reset logic to init_circuit_breaker()
- Add opened_at field to state file when entering/staying OPEN
- Add --auto-reset-circuit CLI flag and .ralphrc config vars
- Add 19 tests in test_circuit_breaker_recovery.bats
- Update CLAUDE.md and README.md documentation
When `grep -c` finds 0 matches, it outputs "0" to stdout but exits
with code 1 (no matches found). The `|| echo "0"` fallback then
triggers, appending another "0" to the command substitution output.
This results in the variable containing "0\n0" instead of just "0",
causing a bash arithmetic syntax error on the $((...)) expression:
line 500: 0 0: syntax error in expression (error token is "0")
Fix: Replace `|| echo "0"` with `|| true` so the grep output is
preserved as-is, with a fallback to set 0 if the variable is empty
(which handles actual grep errors like missing files).
Affects 3 locations in ralph_loop.sh (lines 498, 499, 605).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: progress detection improvements (#141, #144)
- Fix checkbox regex to exclude date entries like [2026-01-29] (#144)
- Add git commit detection: files changed in commits now count as progress (#141)
- Add 13 regression tests for progress detection and checkbox regex
- Update test count from 452 to 465
Fixes#141, Fixes#144
* fix(test): increase grep context to capture echo -1 line
* fix: count both committed and working tree changes as progress
When commits are made, now unions:
- Files changed in commits (loop_start_sha..current_sha)
- Unstaged changes (git diff HEAD)
- Staged changes (git diff --cached)
Uses sort -u to deduplicate before counting.
---------
Co-authored-by: Test User <test@example.com>
- Use --resume <session_id> instead of --continue to avoid hijacking
active Claude Code sessions in the same directory (Issue #151)
- Write log_status output to stderr to prevent log messages from
interfering with function return values
The --continue flag resumes "most recent session in current directory"
which can inadvertently take over an unrelated Claude Code session.
Now Ralph only resumes its own sessions by explicit ID.
Fixes#151
Credit: @dionny (PR #153)
Fixes date command errors on macOS with Homebrew GNU coreutils:
- 'date: invalid option -- v' when GNU date runs BSD syntax
- 'syntax error in expression' when stat returns filesystem metadata
Changes:
- Replace uname-based detection with capability detection (try/fallback)
- Try GNU commands first, fall back to BSD, then ultimate fallbacks
- Add date -r fallback for file mtime (most portable)
This handles mixed environments where uname returns "Darwin" but
GNU coreutils are in PATH from Homebrew.
Credit: @farce1 (PR #119)
* feat: Add live streaming output mode with real-time Claude Code visibility
New features:
- Add --live flag for real-time streaming output using stream-json + jq
- Display tool usage with visual indicators (⚡ [Read], ⚡ [Bash], etc.)
- Add line breaks between messages for better readability
- Integrate live mode automatically in --monitor tmux layout
- Add IS_SANDBOX=1 and CLAUDE_CODE_ENABLE_DANGEROUS_PERMISSIONS_IN_SANDBOX=1
environment variables to allow --dangerously-skip-permissions with root
- Remove DEBUG log messages for cleaner output
The live streaming uses Claude Code's --output-format stream-json with jq
to extract and display text in real-time, allowing users to watch Claude
work as it happens.
tmux --monitor layout now shows:
- Left pane: Ralph loop with live streaming
- Right-top pane: tail -f on live.log
- Right-bottom pane: Status monitor
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(live): use CLAUDE_CMD_ARGS for live mode, remove sandbox exports
Live mode now properly uses build_claude_command() to preserve:
- --allowedTools (tool permissions from .ralphrc)
- --append-system-prompt (loop context)
- --continue (session continuity for save_claude_session())
- -p (prompt content)
Changes:
- Remove unconditional CLAUDE_CODE_ENABLE_DANGEROUS_PERMISSIONS_IN_SANDBOX
and IS_SANDBOX exports (tool restrictions via --allowedTools is sufficient)
- Live mode builds LIVE_CMD_ARGS from CLAUDE_CMD_ARGS, replacing
--output-format json with stream-json
- Add --verbose and --include-partial-messages for streaming
- Remove --dangerously-skip-permissions from legacy fallback mode
- Preserves session ID extraction for save_claude_session()
* fix(live): address critical issues in live mode implementation
Issue 1 - Session Continuity:
- Extract session_id from stream-json output after streaming completes
- Find the "result" type message and convert to standard JSON format
- Save to separate session file for save_claude_session() to parse
Issue 2 - Security Model:
- Remove --dangerously-skip-permissions from build_claude_command()
- Tool permissions now properly controlled via --allowedTools
- Preserves permission denial circuit breaker (Issue #101)
Issue 3 - Dependency Checks:
- Add checks for jq and stdbuf before enabling live mode
- Fall back to background mode if dependencies missing
Issue 4 - Pipeline Error Handling:
- Use set -o pipefail to capture all pipeline exit codes
- Capture PIPESTATUS array for each pipeline stage
- Warn on jq parsing issues without failing the loop
- Primary exit code from Claude command preserved
* fix(live): add timeout protection and improve session handling robustness
Issue 1 - Missing Timeout Protection:
- Add portable_timeout to live mode pipeline for consistent timeout behavior
- Prevents indefinite hangs matching background mode behavior
Issue 2 - Session Continuity Robustness:
- Use flexible regex [[:space:]]* to match various JSON formatting styles
- Preserve full stream output in _stream.log BEFORE modifying output_file
- Validate extracted JSON with jq -e before using it
- Restore stream output if validation fails
Issue 3 - Pipeline Error Handling:
- Check pipe_status[1] (first tee) for write failures
- Warn if output file write fails (could break session/logging)
- All four pipeline stages now monitored
---------
Co-authored-by: André Théo LAURET <andrelauret@icloud.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Test User <test@example.com>
When Claude Code is denied permission to execute commands (e.g., npm install),
Ralph now detects this from the permission_denials array in the JSON output
and halts the loop immediately with clear guidance for the user.
Changes:
- Add permission denial detection to parse_json_response() in response_analyzer.sh
- Extract permission_denials array from Claude Code JSON output
- Track has_permission_denials, permission_denial_count, denied_commands
- Add analyze_response() support for permission denial fields
- Add permission denial exit condition to should_exit_gracefully() in ralph_loop.sh
- Permission denial takes highest priority among exit conditions
- Display helpful guidance for updating ALLOWED_TOOLS in .ralphrc
- Update circuit breaker with CB_PERMISSION_DENIAL_THRESHOLD=2
- Track consecutive_permission_denials in state file
- Open circuit after 2 consecutive loops with permission denials
- Add 11 new TDD tests (6 in test_json_parsing.bats, 5 in test_exit_detection.bats)
- Update documentation in CLAUDE.md and README.md
Test count: 452 (up from 452 - added 11 new tests)
Fixes#101
Co-authored-by: Test User <test@example.com>
* fix(setup): create .ralphrc with consistent tool permissions (#136)
- Update default ALLOWED_TOOLS in ralph_loop.sh to include Edit,
Bash(npm *), and Bash(pytest) for test execution capability
- Make setup.sh generate .ralphrc file using same permissions as
ralph-enable, ensuring consistency between initialization paths
- Add 8 new TDD tests for .ralphrc creation and ALLOWED_TOOLS defaults
- Update documentation in README.md and CLAUDE.md
This fixes the mismatch where PROMPT.md instructs the model to run
tests, but the default permissions didn't allow it. Now both
ralph-setup and ralph-enable create projects with identical tool
permissions.
Test count: 440 (up from 424)
* fix: address PR review feedback
- Update version badges from v0.10.1 to v0.11.2 (README.md)
- Update test count badges from 310 to 440 (README.md, CLAUDE.md)
- Fix .ralphrc generator label: use sed to replace "ralph enable"
with "ralph-setup" when using generate_ralphrc() from library
- Add v0.11.2 changelog entry to CLAUDE.md
* docs(readme): comprehensive update for v0.11.2
- Reorganize Recent Improvements with v0.11.x versions prominent
- Add ralph-enable wizard section with full documentation
- Add .ralphrc configuration section with example
- Update Quick Start to show ralph-enable as Option A (recommended)
- Update test counts to 440 across 15 files
- Collapse v0.9.x versions into expandable details section
- Add new features to What's Working Now section
- Link to issue #138 for automated badge updates
- Update Command Reference with new commands
---------
Co-authored-by: Test User <test@example.com>
When using --monitor flag, the tmux session now correctly forwards all
CLI parameters to the inner ralph_loop.sh execution instead of only
--calls and --prompt.
Added forwarding for:
- --output-format (json/text)
- --verbose
- --timeout
- --allowed-tools
- --no-continue
- --session-expiry
Added 8 new tests for parameter forwarding validation.
Test count: 329 (up from 321)
Fixes#120
Co-Authored-By: Claude <noreply@anthropic.com>
Replace confidence-based heuristic in update_exit_signals() with explicit
EXIT_SIGNAL checking. JSON mode always has confidence >= 70 due to
deterministic scoring, causing completion_indicators to fill after 5 loops
and triggering premature exits even when Claude sets EXIT_SIGNAL: false.
Changes:
- lib/response_analyzer.sh: Check exit_signal == "true" instead of
confidence >= 60 when updating completion_indicators array
- ralph_loop.sh: Update safety circuit breaker comment to reflect that
completion_indicators now only accumulates on EXIT_SIGNAL=true
- tests/unit/test_exit_detection.bats: Add 4 TDD tests (32-35) validating
the fix for update_exit_signals() behavior
- CLAUDE.md: Document fix as v0.11.1, update test counts (420 → 424)
Test count: 424 passing (100% pass rate)
Co-authored-by: Test User <test@example.com>
* refactor(naming): remove @ prefix from on-disk filenames
BREAKING CHANGE: Renames @fix_plan.md → fix_plan.md and @AGENT.md → AGENT.md
This change improves POSIX compliance and compatibility with command-line tools.
The @ prefix was originally used to avoid naming conflicts, but with the .ralph/
folder structure introduced in v0.10.0, this convention is no longer necessary.
Changes:
- Update all scripts to use new naming (fix_plan.md, AGENT.md)
- Update migration script to handle both old and new naming conventions
- Update templates to use new naming
- Update all documentation references
- Update all 420 tests to expect new naming (TDD approach)
Migration:
- Existing projects with @-prefixed files will be automatically renamed
when running ralph-migrate
- Projects already using the new naming will continue to work unchanged
* docs(claude): update file naming conventions section
* fix(migrate): prevent orphaned @-prefixed files during migration
When both root/@fix_plan.md and .ralph/@fix_plan.md exist, the root file
now takes priority and the .ralph/@fix_plan.md is removed (backup exists).
This prevents orphaned legacy files after migration.
---------
Co-authored-by: Test User <test@example.com>
* feat(enable): add ralph-enable wizard for existing projects (v0.11.0)
Add interactive wizard and CI version for enabling Ralph in existing projects.
New commands:
- ralph-enable: Interactive 5-phase wizard for humans
- ralph-enable-ci: Non-interactive version with JSON output for CI/automation
New library components:
- lib/enable_core.sh: Shared logic for idempotency, project detection, templates
- lib/wizard_utils.sh: Interactive prompt utilities
- lib/task_sources.sh: Task import from beads, GitHub Issues, PRD documents
Features:
- Auto-detects project type (TypeScript, Python, Rust, Go)
- Auto-detects framework (Next.js, FastAPI, Django, Express)
- Imports tasks from beads, GitHub Issues, or PRD documents
- Generates .ralphrc project configuration file
- Idempotent: safe to run multiple times, respects existing files
- Exit codes: 0 (success), 1 (error), 2 (already enabled)
Updated:
- install.sh: Added new commands to global installation
- ralph_loop.sh: Loads .ralphrc configuration at startup
Tests: 75 new tests (30 enable_core + 23 task_sources + 22 integration)
Total: 396 tests passing (100% pass rate)
Closes#85, #121, #64, #87, #99
* fix(enable): address code review feedback
Fixes from PR #124 review:
1. sed -i portability (ralph_enable.sh:456)
- Use portable sed + mv pattern instead of GNU-only sed -i
2. sed regex portability (lib/task_sources.sh)
- Replace \s with POSIX [[:space:]] character class
- Add sed -E flag for extended regex
3. jq availability check (ralph_enable_ci.sh:177)
- Add check for jq when --json flag is used
4. Unused filter parameter (lib/task_sources.sh:44)
- Pass filter to bd list --filter command
5. Word-splitting in select_multiple (ralph_enable.sh:322)
- Return comma-separated indices instead of space-separated text
- Update caller to parse indices correctly
6. Missing || true for check_existing_ralph (ralph_enable.sh:185)
- Prevent set -e from exiting on non-zero return
7. select_multiple stdout corruption (lib/wizard_utils.sh)
- Redirect interactive output to stderr
- Only final result goes to stdout
8. Color variables not exported (lib/wizard_utils.sh:12)
- Export WIZARD_* color variables for subshells
9. select_option infinite loop (lib/wizard_utils.sh:179)
- Add guard for empty options array
* fix(tests): add missing mocks and exports for new enable feature
- Add RESPONSE_ANALYSIS_FILE export to test_session_continuity.bats setup
- Add mock ralph_enable.sh and ralph_enable_ci.sh to test_installation.bats
- Add mock lib files: enable_core.sh, wizard_utils.sh, task_sources.sh, timeout_utils.sh
All 396 tests now pass.
* fix(config): fix critical issues from PR review
1. .ralphrc Configuration Loading Fix:
- Captured env var state BEFORE setting defaults with _env_* variables
- load_ralphrc now only restores values explicitly set by environment
- .ralphrc settings are now properly applied (not overwritten by defaults)
2. sed Command Injection Fix:
- Replaced sed with awk for .ralphrc updates in ralph_enable.sh
- awk -v pattern safely handles user input without shell injection risk
3. Shell Injection Fix in safe_create_file():
- Replaced echo with printf '%s\n' for safer content handling
- Prevents issues with backslashes, -n, and special characters
4. Specific Error Codes:
- Added ENABLE_INVALID_ARGS=3 for argument errors
- Added ENABLE_FILE_NOT_FOUND=4 for missing files
- Added ENABLE_DEPENDENCY_MISSING=5 for missing deps (e.g., jq)
- Added ENABLE_PERMISSION_DENIED=6 for permission errors
- Updated ralph_enable.sh and ralph_enable_ci.sh to use specific codes
5. Added tests for .ralphrc loading pattern verification
Test count: 398 (up from 396)
* fix(enable): make --force flag actually overwrite existing files
The --force flag was accepted but safe_create_file() always skipped
existing files regardless of ENABLE_FORCE value.
Changes:
- safe_create_file() now checks ENABLE_FORCE environment variable
- When ENABLE_FORCE="true", overwrites existing files instead of skipping
- Added proper logging for overwrite operations
Added tests:
- Verify enable_ralph_in_directory actually changes file contents with --force
- Test safe_create_file overwrites when ENABLE_FORCE is true
- Test safe_create_file skips when ENABLE_FORCE is false
Test count: 400 (up from 398)
---------
Co-authored-by: Test User <test@example.com>
Root cause: Stale completion indicators in .exit_signals and .response_analysis
files persisted across sessions, causing premature exit when combined with
normal completion indicator increments.
Changes:
- Enhanced reset_session() to clear .exit_signals file (resets to empty structure)
- Enhanced reset_session() to remove .response_analysis file
- Session reset now comprehensively clears all exit-related state
Added 2 new tests:
- reset_session clears exit_signals file to prevent premature exit
- reset_session prevents issue #91 scenario (stale completion indicators)
Test count: 321 (up from 319)
Fixes#91
* feat(structure): migrate Ralph files to .ralph/ subfolder
BREAKING CHANGE: Ralph configuration files now live in .ralph/ subfolder
This refactoring moves all Ralph-specific files into a hidden .ralph/
directory while keeping src/ at the project root. This improves
compatibility with existing tooling and keeps the project root clean.
Changes:
- Move PROMPT.md, @fix_plan.md, @AGENT.md to .ralph/
- Move specs/, logs/, docs/generated/, examples/ to .ralph/
- Move state files (.response_analysis, .circuit_breaker_state, etc.) to .ralph/
- Keep src/ at project root (unchanged)
- Add RALPH_DIR=".ralph" configuration variable
- Add ralph-migrate command for existing projects
- Create migrate_to_ralph_folder.sh migration script
- Update all path references in scripts and tests
- Update documentation (README.md, CLAUDE.md)
New project structure:
project/
├── .ralph/ # Ralph configuration
│ ├── PROMPT.md
│ ├── @fix_plan.md
│ ├── @AGENT.md
│ ├── specs/
│ ├── logs/
│ └── docs/generated/
└── src/ # Source code (unchanged)
Migration: Run `ralph-migrate` in existing projects to upgrade.
All 310 tests pass (100% pass rate).
* chore: add .claude/settings.local.json to .gitignore
* fix: address code review feedback for .ralph/ subfolder structure
Fixes multiple path-related issues identified in code review:
Test fixes:
- Fix create_sample_prompt to use $RALPH_DIR/PROMPT.md in test_session_continuity.bats
- Fix result_file path to use $RALPH_DIR/.json_parse_result in test_json_parsing.bats
- Fix @fix_plan.md and .response_analysis paths in test_cli_modern.bats
- Update templates directory missing test to account for global fallback
Template fix:
- Fix @fix_plan.md reference in templates/PROMPT.md to use .ralph/ prefix
Script fixes:
- Fix PROMPT_FILE comparison in ralph_loop.sh to use $RALPH_DIR/PROMPT.md
- Fix examples migration logic in migrate_to_ralph_folder.sh (remove premature mkdir)
- Move templates directory check AFTER cd in setup.sh (was checking wrong location)
- Add template directory validation with fallback to global templates
All 310 tests pass.
* Update migrate_to_ralph_folder.sh
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* fix: address code review feedback for .ralph/ subfolder structure
Code Review Fixes:
- Fix test_json_parsing.bats: all result_file and session file paths now use $RALPH_DIR prefix
- Fix ralph_loop.sh help text: paths now show .ralph/.ralph_session, .ralph/.call_count, etc.
- Fix migrate_to_ralph_folder.sh:
- Proper error handling for date command (separate local declaration)
- Use cp -a source/. dest/ pattern to preserve dotfiles and attributes
- Remove 2>/dev/null suppression to surface copy errors
- Update create_files.sh to use .ralph/ structure for embedded scripts
- Update .gitignore with all .ralph/ state file paths
- Add old structure detection in ralph_loop.sh with helpful migration message
Version Update:
- Bump to v0.10.0 (breaking change: structural reorganization)
- Update README.md and CLAUDE.md with new version and release notes
- Add ralph-migrate documentation to Key Commands section
All 310 tests pass.
---------
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* feat(timeout): add cross-platform timeout support for macOS
Add portable timeout wrapper that automatically detects and uses the
appropriate timeout command based on the platform:
- Linux: Uses standard GNU `timeout` from coreutils
- macOS: Uses `gtimeout` from Homebrew coreutils
Changes:
- Add lib/timeout_utils.sh with detect_timeout_command() and
portable_timeout() functions
- Update ralph_loop.sh to source timeout_utils.sh and use
portable_timeout for Claude Code execution
- Update install.sh to check for coreutils on macOS and provide
installation instructions
- Update test mocks to include gtimeout and portable_timeout
- Update README.md with macOS coreutils installation instructions
- Update CLAUDE.md with timeout_utils.sh documentation
Users on macOS now need to install coreutils: brew install coreutils
* Update model reference in opencode-review workflow
* Update model name in opencode-review workflow
* Update model version in opencode-review workflow
* Update model version in opencode-review workflow
* Update lib/timeout_utils.sh
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* Update opencode-review.yml
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* Reapply "feat(session): implement session expiration with configurable timeout (#83)"
This reverts commit 1ba55a4b9c.
* fix(session): address code review feedback
- Fix integer overflow: return -1 from get_session_file_age_hours on stat
failure instead of 0, preventing false expiration
- Handle stat failure in init_claude_session with WARN log
- Add comprehensive documentation for return values and expiration strategy
- Add 6 behavioral integration tests that verify actual functionality
- Add inline comments explaining 24-hour default rationale
Test count: 286 → 292 (100% pass rate)
* fix(test): use grep-based verification to fix CI failures
Tests that sourced ralph_loop.sh with --help flag failed in GitHub
Actions due to BATS environment differences. Changed behavioral tests
to grep-based code verification that checks implementation patterns
exist without executing the script.
* fix(test): guard main with BASH_SOURCE for safe sourcing
- Add BASH_SOURCE check to only execute main when script is run directly
- Update tests to source script without --help flag
- Convert grep-based verification tests back to functional tests
- Fixes CI failures caused by script execution during sourcing
---------
Co-authored-by: Test User <test@example.com>
- Add CLAUDE_SESSION_EXPIRY_HOURS configuration variable (default: 24)
- Add get_session_file_age_hours() helper with cross-platform stat support
- Modify init_claude_session() to check session age and remove expired sessions
- Add --session-expiry CLI flag to configure expiration (positive integers only)
- Update help text with new option and example
- Add 10 new tests for session expiration (TDD approach)
Closes#51
Test count: 276 → 286 (100% pass rate)
Co-authored-by: Test User <test@example.com>
- Fix SC2155: separate declare from assign in get_session_id(),
log_session_transition(), init_session_tracking()
- Use jq for safe JSON generation in reset_session() and init_session_tracking()
instead of heredocs (prevents special character issues)
- Add corruption tolerance to log_session_transition() with JSON validation
and fallback to empty array on parse failures
- Add generate_session_id() to create unique session IDs (ralph-<epoch>-<random>)
- Add update_session_last_used() helper called on each loop iteration
- init_session_tracking() now generates unique session_id and sets last_used
- Add session files to .gitignore (.ralph_session, .ralph_session_history,
.claude_session_id)
All 265 tests pass.
- Add init_session_tracking() call in main() before loop starts
- Use literal escape codes for color in --reset-session output
- Remove conditional in reset_session() to always create file
- Remove unused old_session_id variable
- Remove duplicate SESSION_EXPIRATION_SECONDS (keep in response_analyzer.sh)
- Add clarifying comments for RALPH_SESSION_FILE vs CLAUDE_SESSION_FILE
All 265 tests pass.
The build_claude_command() function was incorrectly using --prompt-file
which doesn't exist in Claude Code CLI. This fix:
- Replaces --prompt-file with -p flag plus prompt content
- Reads prompt content via $(cat "$prompt_file") before execution
- Adds error handling for missing prompt files
- Maintains shell injection safety through array-based command building
- Updates comments to reflect the correct approach
Adds 6 TDD tests verifying the fix:
- Uses -p flag instead of --prompt-file
- Reads prompt file content correctly
- Handles missing prompt file
- Includes all modern CLI flags
- Handles multiline prompt content
- Prevents shell injection
Test count: 145 -> 151 (all passing)
Fixes three security issues identified in Phase 1.1 code review:
1. JSON injection in parse_json_response() (response_analyzer.sh:113-132)
- Replace heredoc with jq construction using --arg for strings
- Use --argjson for numeric/boolean fields
- Ensures proper escaping of quotes, newlines, backslashes
2. Input validation for --allowed-tools flag (ralph_loop.sh:903-905)
- Add VALID_TOOL_PATTERNS whitelist
- Add validate_allowed_tools() function
- Validate against whitelist in argument parsing
- Allow Bash(...) patterns with any content
3. Shell injection in build_claude_command() (ralph_loop.sh:439-444)
- Convert from string concatenation to command array
- Use global CLAUDE_CMD_ARGS array
- Execute with "${CLAUDE_CMD_ARGS[@]}" instead of bash -c
- No manual escaping needed - array handles metacharacters
All 98 tests passing.
Closes#48, #50
Implements Issue #28 - modernize CLI commands for better Claude integration.
Key changes:
- Add JSON output format support with --output-format flag (default: json)
- Add session continuity with --continue flag and .claude_session_id file
- Add tool permissions via --allowed-tools flag
- Add build_loop_context() for loop-aware context injection
- Add detect_output_format() and parse_json_response() for JSON parsing
- Maintain backward compatibility with text output fallback
- Add version checking with check_claude_version()
New CLI options:
- --output-format json|text: Control Claude output format
- --allowed-tools "Write,Read,Bash(git *)": Restrict tool permissions
- --no-continue: Disable session continuity
Test coverage:
- 20 new JSON parsing tests (test_json_parsing.bats)
- 23 new CLI modern tests (test_cli_modern.bats)
- All 98 tests passing (100% pass rate)
Add cross-platform date utility library to handle differences between
GNU date (Linux) and BSD date (macOS). Fixes issues with:
- ISO 8601 timestamp formatting (-Iseconds flag)
- Date arithmetic operations (-d vs -v flags)
Changes:
- Created lib/date_utils.sh with get_iso_timestamp() and get_next_hour_time()
- Updated ralph_loop.sh to use date utilities (2 instances)
- Updated lib/circuit_breaker.sh to use date utilities (4 instances)
- Updated lib/response_analyzer.sh to use date utilities (1 instance)
All date operations now work consistently across both platforms without
modification. The utility automatically detects the OS and uses the
appropriate date command syntax.
Tested on Linux with GNU date - all syntax checks and integration tests pass.
Fixes circuit breaker opening prematurely due to naive error pattern matching
that treated JSON field names like "is_error": false as actual errors.
Changes:
- ralph_loop.sh: Implement two-stage error detection with JSON filtering
- lib/response_analyzer.sh: Apply same filtering to error counting
- tests/test_error_detection.sh: Add comprehensive test suite (12 scenarios)
Error detection now:
- Filters out JSON field patterns before searching for errors
- Uses context-specific patterns (^Error:, ]: error, Exception, Fatal)
- Avoids type annotations (error: Error) and code identifiers
- Includes debug logging when VERBOSE_PROGRESS=true
Test coverage validates:
✓ JSON fields don't trigger false positives
✓ Real error messages are correctly detected
✓ Mixed content handled properly
✓ Code diffs and documentation excluded
This prevents the consecutive_same_error counter from incrementing on
false positives, eliminating unnecessary circuit breaker trips.
- Added detection for API 5-hour limit error messages in execute_claude_code()
- Returns special exit code (2) when API limit is detected
- Added interactive prompt for user to choose: wait 60 minutes or exit
- Implements proper countdown timer when waiting for API reset
- Prevents infinite 30-second retry loops on API limit errors
- Improves status tracking with new api_limit and api_limit_exit states
The original `|| echo 0` fallback was executing even when grep -c succeeded
but returned 0 matches (exit code 1), resulting in "0\n0" being assigned
to variables. This multi-line string caused syntax errors in [[ ]] tests.
Fixed by removing the fallback and explicitly handling empty variables
instead, which properly addresses the root cause of the line 280 error.
Ensures total_items and completed_items are explicitly cast to integers
using $((...)) arithmetic expansion to prevent floating point values
from causing syntax errors in double bracket tests at line 280.
- Eliminate double function call in should_exit_gracefully check
- Use consistent string return pattern instead of mixed return codes
- Resolves script error on line 280 with exit code handling
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).
