its-consulting/ralph-claude-code
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update README.md and CLAUDE.md for v0.9.1

Browse source 
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
This commit is contained in:
frankbria 2026-01-08 23:34:01 -07:00
parent 970e683236
commit 6c08757652
2 changed files with 216 additions and 147 deletions
Download patch file Download diff file Expand all files Collapse all files

109
CLAUDE.md
View file

@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
This is the Ralph for Claude Code repository - an autonomous AI development loop system that enables continuous development cycles with intelligent exit detection and rate limiting. This is the Ralph for Claude Code repository - an autonomous AI development loop system that enables continuous development cycles with intelligent exit detection and rate limiting.
**Version**: v0.9.1 | **Tests**: 145 passing (100% pass rate) | **CI/CD**: GitHub Actions
## Core Architecture ## Core Architecture
The system consists of four main bash scripts and a modular library system: The system consists of four main bash scripts and a modular library system:
@ -72,6 +74,10 @@ ralph --monitor --calls 50 --prompt my_custom_prompt.md
# Check current status # Check current status
ralph --status ralph --status
# Circuit breaker management
ralph --reset-circuit
ralph --circuit-status
``` ```
### Monitoring ### Monitoring
@ -87,6 +93,21 @@ tmux list-sessions
tmux attach -t <session-name> tmux attach -t <session-name>
``` ```
### Running Tests
```bash
# Run all tests (145 tests)
npm test
# Run specific test suites
npm run test:unit
npm run test:integration
# Run individual test files
bats tests/unit/test_cli_parsing.bats
bats tests/unit/test_json_parsing.bats
bats tests/unit/test_cli_modern.bats
```
## Ralph Loop Configuration ## Ralph Loop Configuration
The loop is controlled by several key files and environment variables: The loop is controlled by several key files and environment variables:
@ -138,6 +159,27 @@ The loop automatically exits when it detects project completion through:
- All items in @fix_plan.md marked as completed - All items in @fix_plan.md marked as completed
- Strong completion indicators in responses - Strong completion indicators in responses
## CI/CD Pipeline
Ralph uses GitHub Actions for continuous integration:
### Workflows (`.github/workflows/`)
1. **test.yml** - Main test suite
- Runs on push to `main`/`develop` and PRs to `main`
- Executes unit, integration, and E2E tests
- Coverage reporting with kcov (informational only)
- Uploads coverage artifacts
2. **claude.yml** - Claude Code GitHub Actions integration
- Automated code review capabilities
3. **claude-code-review.yml** - PR code review workflow
- Automated review on pull requests
### Coverage Note
Bash code coverage measurement with kcov has fundamental limitations when tracing subprocess executions. The `COVERAGE_THRESHOLD` is set to 0 (disabled) because kcov cannot instrument subprocesses spawned by bats. **Test pass rate (100%) is the quality gate.** See [bats-core#15](https://github.com/bats-core/bats-core/issues/15) for details.
## Project Structure for Ralph-Managed Projects ## Project Structure for Ralph-Managed Projects
Each project created with `./setup.sh` follows this structure: Each project created with `./setup.sh` follows this structure:
@ -166,6 +208,7 @@ Templates in `templates/` provide starting points for new projects:
- Hidden files (e.g., `.call_count`, `.exit_signals`) track loop state - Hidden files (e.g., `.call_count`, `.exit_signals`) track loop state
- `logs/` contains timestamped execution logs - `logs/` contains timestamped execution logs
- `docs/generated/` for Ralph-created documentation - `docs/generated/` for Ralph-created documentation
- `docs/code-review/` for code review reports
## Global Installation ## Global Installation
@ -173,7 +216,7 @@ Ralph installs to:
- **Commands**: `~/.local/bin/` (ralph, ralph-monitor, ralph-setup, ralph-import) - **Commands**: `~/.local/bin/` (ralph, ralph-monitor, ralph-setup, ralph-import)
- **Templates**: `~/.ralph/templates/` - **Templates**: `~/.ralph/templates/`
- **Scripts**: `~/.ralph/` (ralph_loop.sh, ralph_monitor.sh, setup.sh, ralph_import.sh) - **Scripts**: `~/.ralph/` (ralph_loop.sh, ralph_monitor.sh, setup.sh, ralph_import.sh)
- **Libraries**: `~/.ralph/lib/` (circuit_breaker.sh, response_analyzer.sh) - **Libraries**: `~/.ralph/lib/` (circuit_breaker.sh, response_analyzer.sh, date_utils.sh)
After installation, the following global commands are available: After installation, the following global commands are available:
- `ralph` - Start the autonomous development loop - `ralph` - Start the autonomous development loop
@ -188,6 +231,7 @@ Ralph integrates with:
- **tmux**: Terminal multiplexer for integrated monitoring sessions - **tmux**: Terminal multiplexer for integrated monitoring sessions
- **Git**: Expects projects to be git repositories - **Git**: Expects projects to be git repositories
- **jq**: For JSON processing of status and exit signals - **jq**: For JSON processing of status and exit signals
- **GitHub Actions**: CI/CD pipeline for automated testing
- **Standard Unix tools**: bash, grep, date, etc. - **Standard Unix tools**: bash, grep, date, etc.
## Exit Conditions and Thresholds ## Exit Conditions and Thresholds
@ -226,8 +270,47 @@ Ralph uses advanced error detection with two-stage filtering to eliminate false
- Uses literal fixed-string matching (`grep -qF`) to avoid regex edge cases - Uses literal fixed-string matching (`grep -qF`) to avoid regex edge cases
- Prevents false negatives when multiple distinct errors occur simultaneously - Prevents false negatives when multiple distinct errors occur simultaneously
## Test Suite
### Test Files (145 tests total)
| File | Tests | Description |
|------|-------|-------------|
| `test_cli_parsing.bats` | 27 | CLI argument parsing for all 12 flags |
| `test_cli_modern.bats` | 23 | Modern CLI commands (Phase 1.1) |
| `test_json_parsing.bats` | 20 | JSON output format parsing |
| `test_exit_detection.bats` | 20 | Exit signal detection |
| `test_rate_limiting.bats` | 15 | Rate limiting behavior |
| `test_loop_execution.bats` | 20 | Integration tests |
| `test_edge_cases.bats` | 20 | Edge case handling |
### Running Tests
```bash
# All tests
npm test
# Unit tests only
npm run test:unit
# Specific test file
bats tests/unit/test_cli_parsing.bats
```
## Recent Improvements ## Recent Improvements
### CLI Parsing Tests (v0.9.1)
- Added 27 comprehensive CLI argument parsing tests
- Covers all 12 CLI flags with both long and short forms
- Boundary value testing for `--timeout` (0, 1, 120, 121)
- Invalid input handling and error message validation
- Code review report: `docs/code-review/2026-01-08-cli-parsing-tests-review.md`
### CI/CD Pipeline (v0.9.1)
- Added GitHub Actions workflow for automated testing
- kcov coverage measurement (informational only due to subprocess limitations)
- Coverage artifacts uploaded for debugging
- Codecov integration (optional)
### Modern CLI Commands (v0.9.1 - Phase 1.1) ### Modern CLI Commands (v0.9.1 - Phase 1.1)
**JSON Output Format Support** **JSON Output Format Support**
@ -254,11 +337,6 @@ Ralph uses advanced error detection with two-stage filtering to eliminate false
- `--prompt-file` - Use file instead of stdin piping - `--prompt-file` - Use file instead of stdin piping
- Version checking with `check_claude_version()` - Version checking with `check_claude_version()`
**Test Coverage**
- 20 new JSON parsing tests in `test_json_parsing.bats`
- 23 new CLI modern tests in `test_cli_modern.bats`
- All 98 tests passing (100% pass rate)
### Circuit Breaker Enhancements (v0.9.0) ### Circuit Breaker Enhancements (v0.9.0)
**Multi-line Error Matching Fix** **Multi-line Error Matching Fix**
@ -272,12 +350,6 @@ Ralph uses advanced error detection with two-stage filtering to eliminate false
- Stage 2 detects actual error messages in specific contexts - Stage 2 detects actual error messages in specific contexts
- Aligned patterns between `response_analyzer.sh` and `ralph_loop.sh` for consistent behavior - Aligned patterns between `response_analyzer.sh` and `ralph_loop.sh` for consistent behavior
**Test Coverage**
- Added comprehensive test suite for error detection and stuck loop scenarios
- 13/13 error detection tests passing
- 9/9 stuck loop detection tests passing (including multi-error scenarios)
- Tests validate both single and multiple simultaneous recurring errors
### Installation Improvements ### Installation Improvements
- Added `lib/` directory to installation process for modular architecture - Added `lib/` directory to installation process for modular architecture
- Fixed issue where `response_analyzer.sh` and `circuit_breaker.sh` were not being copied during global installation - Fixed issue where `response_analyzer.sh` and `circuit_breaker.sh` were not being copied during global installation
@ -289,23 +361,16 @@ Ralph uses advanced error detection with two-stage filtering to eliminate false
### Testing Requirements ### Testing Requirements
- **Minimum Coverage**: 85% code coverage ratio required for all new code
- **Test Pass Rate**: 100% - all tests must pass, no exceptions - **Test Pass Rate**: 100% - all tests must pass, no exceptions
- **Test Types Required**: - **Test Types Required**:
- Unit tests for bash script functions (if applicable) - Unit tests for bash script functions (if applicable)
- Integration tests for Ralph loop behavior - Integration tests for Ralph loop behavior
- End-to-end tests for full development cycles - End-to-end tests for full development cycles
- **Coverage Validation**: Run coverage reports before marking features complete:
```bash
# For projects with test suites
./test.sh --coverage
# Manual testing of Ralph loop
ralph --monitor --calls 5
```
- **Test Quality**: Tests must validate behavior, not just achieve coverage metrics - **Test Quality**: Tests must validate behavior, not just achieve coverage metrics
- **Test Documentation**: Complex test scenarios must include comments explaining the test strategy - **Test Documentation**: Complex test scenarios must include comments explaining the test strategy
> **Note on Coverage**: The 85% coverage threshold is aspirational for bash scripts. Due to kcov subprocess limitations, test pass rate is the enforced quality gate.
### Git Workflow Requirements ### Git Workflow Requirements
Before moving to the next feature, ALL changes must be: Before moving to the next feature, ALL changes must be:
@ -376,10 +441,10 @@ Before moving to the next feature, ALL changes must be:
Before marking ANY feature as complete, verify: Before marking ANY feature as complete, verify:
- [ ] All tests pass (if applicable) - [ ] All tests pass (if applicable)
- [ ] Code coverage meets 85% minimum threshold (if applicable)
- [ ] Script functionality manually tested - [ ] Script functionality manually tested
- [ ] All changes committed with conventional commit messages - [ ] All changes committed with conventional commit messages
- [ ] All commits pushed to remote repository - [ ] All commits pushed to remote repository
- [ ] CI/CD pipeline passes
- [ ] @fix_plan.md task marked as complete - [ ] @fix_plan.md task marked as complete
- [ ] Implementation documentation updated - [ ] Implementation documentation updated
- [ ] Inline code comments updated or added - [ ] Inline code comments updated or added

244
README.md
View file

@ -2,8 +2,8 @@
![Version](https://img.shields.io/badge/version-0.9.1-blue) ![Version](https://img.shields.io/badge/version-0.9.1-blue)
![Status](https://img.shields.io/badge/status-active%20development-yellow) ![Status](https://img.shields.io/badge/status-active%20development-yellow)
![Tests](https://img.shields.io/badge/tests-98%20passing-green) ![Tests](https://img.shields.io/badge/tests-145%20passing-green)
![Coverage](https://img.shields.io/badge/coverage-65%25-orange) ![Coverage](https://img.shields.io/badge/coverage-informational-lightgrey)
> **Autonomous AI development loop with intelligent exit detection and rate limiting** > **Autonomous AI development loop with intelligent exit detection and rate limiting**
@ -11,13 +11,13 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
**Install once, use everywhere** - Ralph becomes a global command available in any directory. **Install once, use everywhere** - Ralph becomes a global command available in any directory.
## 📌 Project Status ## Project Status
**Version**: v0.9.1 - Active Development **Version**: v0.9.1 - Active Development
**Core Features**: ✅ Working and tested **Core Features**: Working and tested
**Test Coverage**: 65% (expanding to 90%+ - see [roadmap](#-development-roadmap)) **Test Coverage**: 145 tests, 100% pass rate
### What's Working Now ✅ ### What's Working Now
- Autonomous development loops with intelligent exit detection - Autonomous development loops with intelligent exit detection
- Rate limiting with hourly reset (100 calls/hour, configurable) - Rate limiting with hourly reset (100 calls/hour, configurable)
- Circuit breaker with advanced error detection (prevents runaway loops) - Circuit breaker with advanced error detection (prevents runaway loops)
@ -29,27 +29,29 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
- 5-hour API limit handling with user prompts - 5-hour API limit handling with user prompts
- tmux integration for live monitoring - tmux integration for live monitoring
- PRD import functionality - PRD import functionality
- 98 passing tests covering critical paths (20 JSON parsing + 23 CLI modern + 55 core tests) - **CI/CD pipeline with GitHub Actions**
- 145 passing tests across 7 test files
### Recent Improvements 🎉 ### Recent Improvements
**v0.9.1 - Modern CLI Commands (Phase 1.1)** **v0.9.1 - Modern CLI Commands (Phase 1.1)**
- ✅ JSON output format support with `--output-format json` (default) - JSON output format support with `--output-format json` (default)
- ✅ Session continuity using `--continue` flag for cross-loop context - Session continuity using `--continue` flag for cross-loop context
- ✅ Tool permissions via `--allowed-tools` flag - Tool permissions via `--allowed-tools` flag
- ✅ Loop context injection with `build_loop_context()` function - Loop context injection with `build_loop_context()` function
- ✅ Backward-compatible: automatic fallback to text parsing - Backward-compatible: automatic fallback to text parsing
- ✅ 43 new tests: JSON parsing (20) + CLI modern (23) - 70 new tests: JSON parsing (20) + CLI modern (23) + CLI parsing (27)
- CI/CD pipeline with kcov coverage reporting
**v0.9.0 - Circuit Breaker Enhancements** **v0.9.0 - Circuit Breaker Enhancements**
- ✅ Fixed multi-line error matching in stuck loop detection - Fixed multi-line error matching in stuck loop detection
- ✅ Eliminated JSON field false positives (e.g., `"is_error": false`) - Eliminated JSON field false positives (e.g., `"is_error": false`)
- ✅ Added two-stage error filtering for accurate detection - Added two-stage error filtering for accurate detection
- ✅ Comprehensive test suite: 22 new tests for error detection - Comprehensive test suite: 22 new tests for error detection
- ✅ Fixed installation to include lib/ directory components - Fixed installation to include lib/ directory components
### In Progress 🚧 ### In Progress
- Expanding test coverage (60% → 90%+) - Expanding test coverage
- Log rotation functionality - Log rotation functionality
- Dry-run mode - Dry-run mode
- Configuration file support (.ralphrc) - Configuration file support (.ralphrc)
@ -57,39 +59,39 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
- Desktop notifications - Desktop notifications
- Git backup and rollback system - Git backup and rollback system
**Timeline to v1.0**: ~4 weeks • [Full roadmap](IMPLEMENTATION_PLAN.md) • **Contributions welcome!** **Timeline to v1.0**: ~4 weeks | [Full roadmap](IMPLEMENTATION_PLAN.md) | **Contributions welcome!**
## 🌟 Features ## Features
- **🔄 Autonomous Development Loop** - Continuously executes Claude Code with your project requirements - **Autonomous Development Loop** - Continuously executes Claude Code with your project requirements
- **🛡️ Intelligent Exit Detection** - Automatically stops when project objectives are complete - **Intelligent Exit Detection** - Automatically stops when project objectives are complete
- **⚡ Rate Limiting** - Built-in API call management with hourly limits and countdown timers - **Rate Limiting** - Built-in API call management with hourly limits and countdown timers
- **🚫 5-Hour API Limit Handling** - Detects Claude's 5-hour usage limit and offers wait/exit options - **5-Hour API Limit Handling** - Detects Claude's 5-hour usage limit and offers wait/exit options
- **📊 Live Monitoring** - Real-time dashboard showing loop status, progress, and logs - **Live Monitoring** - Real-time dashboard showing loop status, progress, and logs
- **🎯 Task Management** - Structured approach with prioritized task lists and progress tracking - **Task Management** - Structured approach with prioritized task lists and progress tracking
- **🔧 Project Templates** - Quick setup for new projects with best-practice structure - **Project Templates** - Quick setup for new projects with best-practice structure
- **📝 Comprehensive Logging** - Detailed execution logs with timestamps and status tracking - **Comprehensive Logging** - Detailed execution logs with timestamps and status tracking
- **⏱️ Configurable Timeouts** - Set execution timeout for Claude Code operations (1-120 minutes) - **Configurable Timeouts** - Set execution timeout for Claude Code operations (1-120 minutes)
- **🔍 Verbose Progress Mode** - Optional detailed progress updates during execution - **Verbose Progress Mode** - Optional detailed progress updates during execution
- **🧠 Response Analyzer** - AI-powered analysis of Claude Code responses with semantic understanding - **Response Analyzer** - AI-powered analysis of Claude Code responses with semantic understanding
- **🔌 Circuit Breaker** - Advanced error detection with two-stage filtering, multi-line error matching, and automatic recovery - **Circuit Breaker** - Advanced error detection with two-stage filtering, multi-line error matching, and automatic recovery
- **✅ Test Coverage** - 75 comprehensive tests with 60%+ code coverage (target: 90%+) - **CI/CD Integration** - GitHub Actions workflow with automated testing
## 🚀 Quick Start ## Quick Start
Ralph has two phases: **one-time installation** and **per-project setup**. Ralph has two phases: **one-time installation** and **per-project setup**.
``` ```
🔧 INSTALL ONCE 🚀 USE MANY TIMES INSTALL ONCE USE MANY TIMES
┌─────────────────┐ ┌──────────────────────┐ +-----------------+ +----------------------+
│ ./install.sh │ → │ ralph-setup project1 │ | ./install.sh | -> | ralph-setup project1 |
│ │ │ ralph-setup project2 │ | | | ralph-setup project2 |
│ Adds global │ │ ralph-setup project3 │ | Adds global | | ralph-setup project3 |
│ commands │ │ ... │ | commands | | ... |
└─────────────────┘ └──────────────────────┘ +-----------------+ +----------------------+
``` ```
### 📦 Phase 1: Install Ralph (One Time Only) ### Phase 1: Install Ralph (One Time Only)
Install Ralph globally on your system: Install Ralph globally on your system:
@ -103,7 +105,7 @@ This adds `ralph`, `ralph-monitor`, and `ralph-setup` commands to your PATH.
> **Note**: You only need to do this once per system. After installation, you can delete the cloned repository if desired. > **Note**: You only need to do this once per system. After installation, you can delete the cloned repository if desired.
### 🎯 Phase 2: Initialize New Projects (Per Project) ### Phase 2: Initialize New Projects (Per Project)
For each new project you want Ralph to work on: For each new project you want Ralph to work on:
@ -137,7 +139,7 @@ cd my-awesome-project
ralph --monitor ralph --monitor
``` ```
### 🔄 Ongoing Usage (After Setup) ### Ongoing Usage (After Setup)
Once Ralph is installed and your project is initialized: Once Ralph is installed and your project is initialized:
@ -150,26 +152,26 @@ ralph # Terminal 1: Ralph loop
ralph-monitor # Terminal 2: Live monitor dashboard ralph-monitor # Terminal 2: Live monitor dashboard
``` ```
## 📖 How It Works ## How It Works
Ralph operates on a simple but powerful cycle: Ralph operates on a simple but powerful cycle:
1. **📋 Read Instructions** - Loads `PROMPT.md` with your project requirements 1. **Read Instructions** - Loads `PROMPT.md` with your project requirements
2. **🤖 Execute Claude Code** - Runs Claude Code with current context and priorities 2. **Execute Claude Code** - Runs Claude Code with current context and priorities
3. **📊 Track Progress** - Updates task lists and logs execution results 3. **Track Progress** - Updates task lists and logs execution results
4. **🔍 Evaluate Completion** - Checks for exit conditions and project completion signals 4. **Evaluate Completion** - Checks for exit conditions and project completion signals
5. **🔄 Repeat** - Continues until project is complete or limits are reached 5. **Repeat** - Continues until project is complete or limits are reached
### Intelligent Exit Detection ### Intelligent Exit Detection
Ralph automatically stops when it detects: Ralph automatically stops when it detects:
- ✅ All tasks in `@fix_plan.md` marked complete - All tasks in `@fix_plan.md` marked complete
- 🎯 Multiple consecutive "done" signals from Claude Code - Multiple consecutive "done" signals from Claude Code
- 🧪 Too many test-focused loops (indicating feature completeness) - Too many test-focused loops (indicating feature completeness)
- 📋 Strong completion indicators in responses - Strong completion indicators in responses
- 🚫 Claude API 5-hour usage limit reached (with user prompt to wait or exit) - Claude API 5-hour usage limit reached (with user prompt to wait or exit)
## 📄 Importing Existing Requirements ## Importing Existing Requirements
Ralph can convert existing PRDs, specifications, or requirement documents into the proper Ralph format using Claude Code. Ralph can convert existing PRDs, specifications, or requirement documents into the proper Ralph format using Claude Code.
@ -208,7 +210,7 @@ Ralph-import creates a complete project with:
The conversion is intelligent and preserves your original requirements while making them actionable for autonomous development. The conversion is intelligent and preserves your original requirements while making them actionable for autonomous development.
## 🛠️ Configuration ## Configuration
### Rate Limiting & Circuit Breaker ### Rate Limiting & Circuit Breaker
@ -293,7 +295,7 @@ CB_SAME_ERROR_THRESHOLD=5 # Open circuit after 5 loops with repeated erro
CB_OUTPUT_DECLINE_THRESHOLD=70 # Open circuit if output declines by >70% CB_OUTPUT_DECLINE_THRESHOLD=70 # Open circuit if output declines by >70%
``` ```
## 📁 Project Structure ## Project Structure
Ralph creates a standardized structure for each project: Ralph creates a standardized structure for each project:
@ -310,7 +312,7 @@ my-project/
└── docs/generated/ # Auto-generated documentation └── docs/generated/ # Auto-generated documentation
``` ```
## 🎯 Best Practices ## Best Practices
### Writing Effective Prompts ### Writing Effective Prompts
@ -333,7 +335,7 @@ my-project/
- Monitor `status.json` for programmatic access - Monitor `status.json` for programmatic access
- Watch for exit condition signals - Watch for exit condition signals
## 🔧 System Requirements ## System Requirements
- **Bash 4.0+** - For script execution - **Bash 4.0+** - For script execution
- **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code` - **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code`
@ -350,7 +352,7 @@ If you want to run the test suite:
# Install BATS testing framework # Install BATS testing framework
npm install -g bats bats-support bats-assert npm install -g bats bats-support bats-assert
# Run all tests (98 tests) # Run all tests (145 tests)
bats tests/ bats tests/
# Run specific test suites # Run specific test suites
@ -358,6 +360,7 @@ bats tests/unit/test_rate_limiting.bats
bats tests/unit/test_exit_detection.bats bats tests/unit/test_exit_detection.bats
bats tests/unit/test_json_parsing.bats bats tests/unit/test_json_parsing.bats
bats tests/unit/test_cli_modern.bats bats tests/unit/test_cli_modern.bats
bats tests/unit/test_cli_parsing.bats
bats tests/integration/test_loop_execution.bats bats tests/integration/test_loop_execution.bats
# Run error detection and circuit breaker tests # Run error detection and circuit breaker tests
@ -366,12 +369,13 @@ bats tests/integration/test_loop_execution.bats
``` ```
Current test status: Current test status:
- **98 tests** across 7 test files (55 core + 20 JSON parsing + 23 CLI modern) - **145 tests** across 7 test files
- **100% pass rate** (98/98 passing) - **100% pass rate** (145/145 passing)
- **~65% code coverage** (target: 90%+)
- Comprehensive unit and integration tests - Comprehensive unit and integration tests
- Specialized tests for JSON parsing, CLI flags, and circuit breaker functionality - Specialized tests for JSON parsing, CLI flags, and circuit breaker functionality
> **Note on Coverage**: Bash code coverage measurement with kcov has fundamental limitations when tracing subprocess executions. Test pass rate (100%) is the quality gate. See [bats-core#15](https://github.com/bats-core/bats-core/issues/15) for details.
### Installing tmux ### Installing tmux
```bash ```bash
@ -385,7 +389,7 @@ brew install tmux
sudo yum install tmux sudo yum install tmux
``` ```
## 📊 Monitoring and Debugging ## Monitoring and Debugging
### Live Dashboard ### Live Dashboard
@ -429,7 +433,7 @@ tail -f logs/ralph.log
- **Missing Dependencies** - Ensure Claude Code CLI and tmux are installed - **Missing Dependencies** - Ensure Claude Code CLI and tmux are installed
- **tmux Session Lost** - Use `tmux list-sessions` and `tmux attach` to reconnect - **tmux Session Lost** - Use `tmux list-sessions` and `tmux attach` to reconnect
## 🤝 Contributing ## Contributing
Ralph is actively seeking contributors! We're working toward v1.0.0 with clear priorities and a detailed roadmap. Ralph is actively seeking contributors! We're working toward v1.0.0 with clear priorities and a detailed roadmap.
@ -456,19 +460,17 @@ Ralph is actively seeking contributors! We're working toward v1.0.0 with clear p
### Priority Contribution Areas ### Priority Contribution Areas
**🔥 High Priority (Help Needed!)** **High Priority (Help Needed!)**
1. **Test Implementation** - We need 65+ more tests to reach 90% coverage 1. **Test Implementation** - We need more tests to reach comprehensive coverage
- See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for detailed test specifications - See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for detailed test specifications
- Week 3-4: Installation, CLI, tmux tests (58 tests)
- Week 5-6: Features and E2E tests (42 tests)
2. **Feature Development** 2. **Feature Development**
- Log rotation functionality (Week 5, Day 3) - Log rotation functionality
- Dry-run mode (Week 5, Day 4) - Dry-run mode
- Config file support (Week 5, Day 5) - Config file support
- Metrics tracking (Week 6, Day 1) - Metrics tracking
- Notifications (Week 6, Day 2) - Notifications
- Backup/rollback (Week 6, Day 3) - Backup/rollback
3. **Documentation** 3. **Documentation**
- TESTING.md guide - TESTING.md guide
@ -484,7 +486,6 @@ Ralph is actively seeking contributors! We're working toward v1.0.0 with clear p
### Development Guidelines ### Development Guidelines
- **Tests Required**: All new features must include tests - **Tests Required**: All new features must include tests
- **Coverage Goal**: Maintain or improve coverage (currently 60%, target 90%+)
- **Code Style**: Follow existing bash patterns and conventions - **Code Style**: Follow existing bash patterns and conventions
- **Documentation**: Update README and relevant docs for user-facing changes - **Documentation**: Update README and relevant docs for user-facing changes
- **Commit Messages**: Clear, descriptive commit messages - **Commit Messages**: Clear, descriptive commit messages
@ -506,7 +507,7 @@ Ralph is actively seeking contributors! We're working toward v1.0.0 with clear p
### Development Roadmap Reference ### Development Roadmap Reference
See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete 6-week plan including: See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete roadmap including:
- Detailed test specifications - Detailed test specifications
- Feature implementation guides - Feature implementation guides
- Code examples for new functionality - Code examples for new functionality
@ -518,26 +519,26 @@ See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete 6-week pla
- Check existing issues for planned work - Check existing issues for planned work
- Join discussions on pull requests - Join discussions on pull requests
**Every contribution matters** - from fixing typos to implementing major features. Thank you for helping make Ralph better! 🙏 **Every contribution matters** - from fixing typos to implementing major features. Thank you for helping make Ralph better!
## 📄 License ## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments ## Acknowledgments
- Inspired by the [Ralph technique](https://github.com/paul-gauthier/aider/blob/main/docs/more/aider-benchmarks.md#ralph) created by Paul Gauthier for the Aider project - Inspired by the [Ralph technique](https://ghuntley.com/ralph/) created by Geoffrey Huntley
- Built for [Claude Code](https://claude.ai/code) by Anthropic - Built for [Claude Code](https://claude.ai/code) by Anthropic
- Community feedback and contributions - Community feedback and contributions
## 🔗 Related Projects ## Related Projects
- [Claude Code](https://claude.ai/code) - The AI coding assistant that powers Ralph - [Claude Code](https://claude.ai/code) - The AI coding assistant that powers Ralph
- [Aider](https://github.com/paul-gauthier/aider) - Original Ralph technique implementation - [Aider](https://github.com/paul-gauthier/aider) - Original Ralph technique implementation
--- ---
## 📋 Command Reference ## Command Reference
### Installation Commands (Run Once) ### Installation Commands (Run Once)
```bash ```bash
@ -559,6 +560,8 @@ ralph [OPTIONS]
--output-format FORMAT Set output format: json (default) or text --output-format FORMAT Set output format: json (default) or text
--allowed-tools TOOLS Set allowed Claude tools (default: Write,Bash(git *),Read) --allowed-tools TOOLS Set allowed Claude tools (default: Write,Bash(git *),Read)
--no-continue Disable session continuity (start fresh each loop) --no-continue Disable session continuity (start fresh each loop)
--reset-circuit Reset the circuit breaker
--circuit-status Show circuit breaker status
``` ```
### Project Commands (Per Project) ### Project Commands (Per Project)
@ -582,61 +585,62 @@ tmux attach -t <name> # Reattach to detached session
--- ---
## 🗺️ Development Roadmap ## Development Roadmap
Ralph is under active development with a clear path to v1.0.0. See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete 6-week roadmap. Ralph is under active development with a clear path to v1.0.0. See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete roadmap.
### Current Status: v0.9.1
### Current Status: v0.9.0 (Week 1-2 Complete)
**What's Delivered:** **What's Delivered:**
- ✅ Core loop functionality with intelligent exit detection - Core loop functionality with intelligent exit detection
- ✅ Rate limiting (100 calls/hour) and circuit breaker pattern - Rate limiting (100 calls/hour) and circuit breaker pattern
- ✅ Response analyzer with semantic understanding - Response analyzer with semantic understanding
- ✅ 75 comprehensive tests (100% pass rate, 60% coverage) - 145 comprehensive tests (100% pass rate)
- ✅ tmux integration and live monitoring - tmux integration and live monitoring
- ✅ PRD import functionality - PRD import functionality
- ✅ Installation system and project templates - Installation system and project templates
- ✅ Comprehensive documentation (2,300+ lines) - Modern CLI commands with JSON output support
- CI/CD pipeline with GitHub Actions
**Test Coverage Breakdown:** **Test Coverage Breakdown:**
- Unit Tests: 35 (rate limiting, exit detection) - Unit Tests: 105 (CLI parsing, JSON, exit detection, rate limiting)
- Integration Tests: 40 (loop execution, edge cases) - Integration Tests: 40 (loop execution, edge cases)
- Coverage: ~60% of critical code paths - Test Files: 7
### Path to v1.0.0 (~4 weeks) ### Path to v1.0.0 (~4 weeks)
**Week 3-4: Enhanced Testing**
- ⏳ Installation and setup workflow tests (28 tests)
- ⏳ CLI argument parsing tests (10 tests)
- ⏳ tmux integration tests (12 tests)
- ⏳ Monitor dashboard tests (8 tests)
**Week 5: Core Features** **Enhanced Testing**
- ⏳ Log rotation functionality (5 tests) - Installation and setup workflow tests
- ⏳ Dry-run mode (4 tests) - tmux integration tests
- ⏳ Configuration file support - .ralphrc (6 tests) - Monitor dashboard tests
**Week 6: Advanced Features & Polish** **Core Features**
- ⏳ Metrics and analytics tracking (4 tests) - Log rotation functionality
- ⏳ Desktop notifications (3 tests) - Dry-run mode
- ⏳ Git backup and rollback system (5 tests) - Configuration file support - .ralphrc
- ⏳ End-to-end tests (10 tests)
- ⏳ Final documentation and release prep
**Target:** 140+ tests, 90%+ coverage, all planned features implemented **Advanced Features & Polish**
- Metrics and analytics tracking
- Desktop notifications
- Git backup and rollback system
- End-to-end tests
- Final documentation and release prep
See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for detailed week-by-week progress tracking. See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for detailed progress tracking.
### How to Contribute ### How to Contribute
Ralph is seeking contributors! Priority areas: Ralph is seeking contributors! Priority areas:
1. **Test Implementation** - Help reach 90%+ coverage ([see plan](IMPLEMENTATION_PLAN.md)) 1. **Test Implementation** - Help expand test coverage ([see plan](IMPLEMENTATION_PLAN.md))
2. **Feature Development** - Log rotation, dry-run mode, config files 2. **Feature Development** - Log rotation, dry-run mode, config files
3. **Documentation** - Usage examples, tutorials, troubleshooting guides 3. **Documentation** - Usage examples, tutorials, troubleshooting guides
4. **Bug Reports** - Real-world usage feedback and edge cases 4. **Bug Reports** - Real-world usage feedback and edge cases
See [Contributing](#-contributing) section below for guidelines. See [Contributing](#contributing) section above for guidelines.
--- ---
**Ready to let AI build your project?** Start with `./install.sh` and let Ralph take it from there! 🚀 **Ready to let AI build your project?** Start with `./install.sh` and let Ralph take it from there!
## Star History ## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=frankbria/ralph-claude-code&type=date&legend=top-left)](https://www.star-history.com/#frankbria/ralph-claude-code&type=date&legend=top-left) [![Star History Chart](https://api.star-history.com/svg?repos=frankbria/ralph-claude-code&type=date&legend=top-left)](https://www.star-history.com/#frankbria/ralph-claude-code&type=date&legend=top-left)