* 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>
- Bump version from v0.11.2 to v0.11.3
- Update test count from 440 to 452 across all badges and references
- Add v0.11.3 release notes for live streaming output (#125) and beads fix (#150)
- Document --live flag for real-time Claude Code visibility
- Add Live Streaming Output configuration section
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>
New users were confused about which files they write vs. which Ralph
manages, and how PROMPT.md, specs/, and fix_plan.md relate to each other.
Added:
- docs/user-guide/ with quick start tutorial, file reference, and
requirements writing guide
- examples/simple-cli-tool/ showing minimal Ralph configuration
- examples/rest-api/ demonstrating when to use specs/
- README section explaining Ralph files and their relationships
Also documents specs/stdlib/ purpose for reusable patterns.
* 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>
* 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(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>
Major updates:
- Version bumped to v0.9.9
- Test count updated to 308 (from 276)
- Added v0.9.9 release notes: EXIT_SIGNAL gate fix, uninstall script, session expiration
- New "Uninstalling Ralph" section with dedicated uninstall.sh
- Updated "Intelligent Exit Detection" with dual-condition check explanation
- Added EXIT_SIGNAL decision table to Configuration section
- New troubleshooting entries: "Premature Exit" and "Session Expired"
- Updated test coverage breakdown (164 unit + 144 integration)
- Added "Clean Uninstall" to Features list
- Updated Command Reference with ./uninstall.sh
- Add GitHub Actions CI badge (dynamic, links to workflow)
- Add MIT License badge (links to LICENSE file)
- Add GitHub Issues badge (dynamic count)
- Keep Awesome Claude Code and X follow badges
- Remove redundant status badge, keep version and tests
- Create CONTRIBUTING.md with 8 sections covering the full contributor
journey: Getting Started, Development Workflow, Code Style, Testing,
PR Process, Code Review, Quality Standards, and Community Guidelines
- Include workflow diagram, quality gates table, and test commands reference
- Update README.md to reference CONTRIBUTING.md, consolidating duplicate
contributor information into the dedicated guide
- Add version history entries for v0.9.3 through v0.9.8
- Add Session Continuity feature to features list
- Add new Session Continuity configuration section
- Add --reset-session flag to command reference
- Add new test file references (session, import, setup, installation)
- Convert CLAUDE_ALLOWED_TOOLS to bash array for proper quoting
- Use array expansion "${CLAUDE_ALLOWED_TOOLS[@]}" in CLI invocation
- Default empty version components to 0 (handles "2.1" style versions)
- Add stderr_file cleanup in JSON error path
- Add type validation for PARSED_FILES_CREATED before array iteration
- Check for empty file names in JSON array iteration
- Fix stale test counts in README.md (165 → 276, 8 → 11 test files)
- Fix check_claude_version() to use numeric semantic version comparison
- Fix detect_response_format() to read first non-whitespace character
- Wire PARSED_RESULT into success message output
- Wire PARSED_FILES_CREATED into file verification logic
- Add --allowedTools flag to CLI invocation using CLAUDE_ALLOWED_TOOLS
- Separate stderr to avoid corrupting JSON output file
- Clean up stderr file on completion and error
- Update README.md version badges to v0.9.8 and 276 tests
- Update roadmap section with current test coverage breakdown
- 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)
README.md:
- Update version badge to v0.9.3
- Update test count to 165 in all locations
- Update test coverage breakdown (111 unit + 54 integration)
test_installation.bats:
- Add missing mock setup.sh in setup() function
- Fix dependency test to mock all three deps (jq, git, node/npx)
- Remove unused source_install_functions helper function
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).
- Added attribution to Paul Gauthier as creator of the Ralph technique
- Documented new 5-hour API limit detection and handling feature
- Added documentation for --verbose and --timeout options
- Included complete Ralph Loop Options reference section
- Updated Features section with new capabilities
- Enhanced troubleshooting section with API limit and timeout guidance
- Corrected command examples to match actual implementation
- 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
🚀 New Feature: ralph-import
- Converts existing PRDs/specs to Ralph format using Claude Code intelligence
- Supports multiple formats: Markdown, text, JSON, Word docs, PDFs
- Creates complete Ralph project with PROMPT.md, @fix_plan.md, specs/
- Leverages Claude Code for intelligent requirement parsing and conversion
🔧 Implementation:
- ralph_import.sh: Core conversion script with Claude Code integration
- Global installation: ralph-import command available system-wide
- Smart conversion prompt that extracts goals, priorities, and technical specs
- Auto-generates proper Ralph project structure from any source format
📚 Enhanced Documentation:
- New "Importing Existing Requirements" section in README
- Option A (import PRD) vs Option B (manual setup) in Quick Start
- Comprehensive format support and usage examples
- Command reference updated with ralph-import
🎯 Benefits:
- Eliminates manual conversion from PRDs to Ralph format
- Leverages Claude Code's intelligence for requirement interpretation
- Dramatically reduces onboarding friction for existing projects
- Maintains all original requirement context while making it actionable
Sample PRD included for testing and demonstration purposes.
- Add clear distinction between one-time installation and per-project setup
- Include visual workflow diagram showing install once → use many times
- Separate Phase 1 (Install Ralph) and Phase 2 (Initialize Projects)
- Add dedicated "Ongoing Usage" section for daily workflow
- Include comprehensive Command Reference section
- Reorganize Quick Start for better user understanding
- Emphasize "Install once, use everywhere" concept
This addresses confusion about when to run installation commands vs
when to run project setup commands, making the user journey much clearer.
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.
