When wizard prompt functions (prompt_text, prompt_number, select_option,
select_with_default) were used with command substitution, ANSI-colored
prompts were captured along with user responses, corrupting .ralphrc
values like: PROJECT_NAME="[0;36mProject name[0m [value]: value"
Fix:
- Redirect all display output (colored prompts, validation messages) to
stderr using >&2, matching the pattern already used by select_multiple()
- Keep only the actual response/result on stdout for command substitution
Changes:
- lib/wizard_utils.sh: Add >&2 to prompt_text (lines 84-87),
prompt_number (lines 118-121, 131-151), confirm (lines 44, 60),
select_option (lines 190-215), select_with_default (lines 330-364)
- tests/unit/test_wizard_utils.bats: Add 20 new tests for stdout/stderr
separation and clean command substitution results
- CLAUDE.md: Update test count to 420
Test count: 420 (up from 396)
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
Merged origin/main into PR branch and applied review feedback:
Review fixes:
- Guard against empty result_obj if jq fails (Macroscope)
- Prioritize result object's session_id over init message (CodeRabbit)
- Add regression test for arrays with session_id only in result element
Resolved conflicts:
- CLAUDE.md: Updated test count to 319
All 319 tests pass.
Claude Code CLI outputs a JSON array instead of a single object:
[{type: "system", ...}, {type: "assistant", ...}, {type: "result", ...}]
This caused parse_json_response to fail with "jq: invalid JSON text"
because it assumed the top-level JSON was an object.
Changes:
- Detect if JSON is an array before parsing
- Extract the "result" type message from the array
- Preserve session_id from init message for continuity
- Normalize to object format for existing parsing logic
- Clean up temporary file after processing
Fixes#112
Co-Authored-By: Claude <noreply@anthropic.com>
* 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>
- Add --output-format json flag for structured Claude CLI responses
- Implement detect_response_format() for JSON vs text detection
- Implement parse_conversion_response() for extracting JSON fields
- Add check_claude_version() for modern CLI feature detection
- Enhance error handling with structured JSON error messages
- Improve file verification with JSON-derived status information
- Maintain backward compatibility with automatic text fallback
- Add 11 new TDD tests for modern CLI features (tests 23-33)
- Update README.md with Modern CLI Features section
- Update CLAUDE.md with v0.9.8 release notes
Test count: 276 (up from 265)
- Fix BSD date parsing to handle milliseconds in ISO timestamps
(e.g., 2026-01-09T10:30:00.123+00:00)
- Document error_count mapping behavior when only has_errors=true is present
- Remove unused has_session_id_field variable
- Add debug logging for session persistence (controlled by VERBOSE_PROGRESS)
- Standardize session filename to .claude_session_id across all files
All 239 tests passing.
- Extend parse_json_response() to support both flat and Claude CLI formats
- Extract result, sessionId, and metadata fields
- Support metadata.files_changed, metadata.has_errors, completion_status
- Parse progress_indicators array for confidence boosting
- Add session management functions for continuity tracking:
- store_session_id(): Persist session with ISO timestamp
- get_last_session_id(): Retrieve stored session ID
- should_resume_session(): Check session validity (24-hour expiration)
- Add get_epoch_seconds() to date_utils.sh for cross-platform epoch time
- Auto-persist sessionId to .session_id file during response analysis
- Add 16 new TDD tests for Claude CLI format and session management
- Update documentation for v0.9.6 (239 tests total)
Test count: 239 (up from 223)
- Add test_installation.bats with full coverage of install.sh
- Tests cover directory creation, command installation, permissions
- Template and lib file copying verification
- Dependency detection with mocked failures (jq, git, node)
- PATH detection and warning system tests
- Uninstallation cleanup verification
- Idempotency testing (run twice without errors)
- End-to-end installation workflow validation
- All tests use isolated temp directories for safety
- Update CLAUDE.md with new test count (165 total)
- Fix npm test script to run tests recursively
- Version bump to v0.9.3
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)
README.md:
- Update test count: 98 → 145 tests (accurate count from all 7 test files)
- Change coverage badge to informational (kcov subprocess limitation)
- Add CI/CD integration mention
- Add coverage note with link to bats-core#15
- Add --reset-circuit and --circuit-status to command reference
- Simplify formatting (remove emoji prefixes)
CLAUDE.md:
- Add version/test status line at top
- Add CI/CD Pipeline section documenting all 3 workflows
- Add Test Suite table with all 7 test files
- Add Running Tests section with npm/bats commands
- Document CLI parsing tests (27 new tests)
- Update Feature Completion Checklist with CI/CD requirement
- Add coverage note explaining kcov limitations
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)
Updated both documentation files to reflect recent enhancements and fixes:
CLAUDE.md Changes:
- Added comprehensive Core Architecture section detailing main scripts and lib/ components
- Documented lib/circuit_breaker.sh and lib/response_analyzer.sh modular architecture
- Added detailed Exit Conditions and Thresholds section with circuit breaker thresholds
- Documented advanced two-stage error detection process to eliminate false positives
- Documented multi-line error matching for accurate stuck loop detection
- Added Recent Improvements section highlighting v0.9.0 circuit breaker enhancements
- Updated Global Installation section to include lib/ directory and ralph-import command
- Test coverage details: 13 error detection + 9 stuck loop tests
README.md Changes:
- Updated "What's Working Now" section with circuit breaker enhancements
- Added "Recent Improvements" section highlighting v0.9.0 updates
- Updated test count from 75 to 97 tests (75 core + 13 error detection + 9 stuck loop)
- Enhanced circuit breaker description with two-stage filtering details
- Added circuit breaker thresholds to Exit Thresholds section
- Updated test commands to include error detection and stuck loop test scripts
- Updated current test status with specialized test file counts
Key improvements documented:
- Multi-line error matching fix for detect_stuck_loop function
- JSON field false positive elimination (e.g., "is_error": false)
- Two-stage error filtering for accurate error detection
- Installation fix for lib/ directory components
- 22 new tests added for circuit breaker functionality
These updates ensure documentation accurately reflects the current state of the
codebase following PR #6 (circuit-breaker false positives fix) and PR #4
(installation lib/ directory fix).
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).
- Create professional README.md with complete feature overview, quick start guide,
configuration options, best practices, and troubleshooting
- Add CLAUDE.md for future Claude Code instances with architectural guidance,
key commands, and operational knowledge
- Transform minimal README into comprehensive project documentation
- Include visual hierarchy, code examples, and clear user journey
Documentation now covers the complete Ralph for Claude Code autonomous
development loop system for both end users and future AI agents.
