Ralph for Claude Code - Implementation Plan
January 10, 2026 ยท View on GitHub
Version: v0.9.8 | Tests: 276 passing (100% pass rate) | CI/CD: GitHub Actions
Current Phase
Phase 1: CLI Modernization (In Progress)
Phase 1 focuses on modernizing Ralph's CLI integration with Claude Code, including JSON output parsing, session management, and documentation.
Status: Core features complete (1.1-1.4), remaining items are documentation and bug fixes.
| Issue | Title | Priority | Status |
|---|---|---|---|
| #51 | Phase 1.5: Implement session expiration for .claude_session_id | P2 | Open |
| #24 | Phase 1.9: Create TESTING.md documentation | P3 | Open |
| #25 | Phase 1.10: Create CONTRIBUTING.md guide | P3 | Open |
| #26 | Phase 1.11: Update README with testing instructions | P3 | Open |
| #27 | Phase 1.12: Add badges to README | P3 | Open |
Completed Phase 1 Issues: #28 (CLI commands), #29 (JSON parsing), #30 (session management), #31 (ralph-import), #48 (security), #50 (input validation)
Planned Development
Phase 2: Agent SDK Integration (P2)
Migrate from CLI-only execution to a hybrid CLI/SDK architecture using Claude's Agent SDK.
| Issue | Title | Priority | Status |
|---|---|---|---|
| #32 | Phase 2.1: Create Agent SDK proof of concept | P2 | Open |
| #33 | Phase 2.2: Define custom tools for Agent SDK | P2 | Open |
| #34 | Phase 2.3: Implement hybrid CLI/SDK architecture | P2 | Open |
| #35 | Phase 2.4: Document SDK migration strategy | P2 | Open |
Phase 3: Configuration & Infrastructure (P2-P3)
Add configuration file support, infrastructure features, and advanced functionality.
| Issue | Title | Priority | Status |
|---|---|---|---|
| #36 | Phase 3.1: Add JSON configuration file support | P2 | Open |
| #37 | Phase 3.2: Update installation for SDK support | P2 | Open |
| #18 | Phase 3.4: Implement log rotation feature | P2 | Open |
| #19 | Phase 3.5: Implement dry-run mode feature | P2 | Open |
| #20 | Phase 3.6: Implement config file support (.ralphrc) | P2 | Open |
| #38 | Phase 3.3: Create CLI and SDK documentation | P3 | Open |
| #21 | Phase 3.7: Implement metrics and analytics | P3 | Open |
| #22 | Phase 3.8: Implement notification system | P3 | Open |
| #23 | Phase 3.9: Implement backup and rollback system | P3 | Open |
Phase 4: Validation Testing (P2-P3)
Comprehensive testing for all new features and integration scenarios.
| Issue | Title | Priority | Status |
|---|---|---|---|
| #14 | Phase 4.4: Implement tmux integration tests | P2 | Open |
| #15 | Phase 4.5: Implement monitor dashboard tests | P2 | Open |
| #16 | Phase 4.6: Implement status update tests | P2 | Open |
| #39 | Phase 4.1: Implement CLI enhancement tests | P3 | Open |
| #40 | Phase 4.2: Implement SDK integration tests | P3 | Open |
| #41 | Phase 4.3: Implement backward compatibility tests | P3 | Open |
| #17 | Phase 4.7: Implement E2E full loop tests | P3 | Open |
Phase 5: GitHub Issue Integration (P4)
Enable Ralph to import development plans directly from GitHub issues.
| Issue | Title | Priority | Status |
|---|---|---|---|
| #69 | Phase 5.1: Allow plan import from GitHub Issue | P4 | Open |
| #70 | Phase 5.2: Assess issue completeness and generate implementation plan | P4 | Open |
| #71 | Phase 5.3: Filter and select GitHub issues by metadata | P4 | Open |
| #72 | Phase 5.4: Batch processing and issue queue management | P4 | Open |
| #73 | Phase 5.5: Issue lifecycle management and completion workflows | P4 | Open |
Summary: Import single issues (#69), generate plans for incomplete issues (#70), filter by labels/assignees (#71), process multiple issues (#72), and manage issue lifecycle (#73).
Phase 6: Sandbox Execution Environments (P4)
Run Ralph in isolated sandbox environments for security and reproducibility.
| Issue | Title | Priority | Status |
|---|---|---|---|
| #49 | Phase 6.0: Sandbox execution environments (umbrella) | P4 | Open |
| #74 | Phase 6.1: Local Docker Sandbox Execution | P4 | Open |
| #75 | Phase 6.2: E2B Cloud Sandbox Integration | P4 | Open |
| #76 | Phase 6.3: Sandbox File Synchronization | P4 | Open |
| #77 | Phase 6.4: Sandbox Security and Resource Policies | P4 | Open |
| #78 | Phase 6.5: Generic Sandbox Interface and Plugin Architecture | P4 | Open |
| #79 | Phase 6.6: Daytona Sandbox Integration | P4 | Open |
| #80 | Phase 6.7: Cloudflare Sandbox Integration | P4 | Open |
First-class providers: Docker (local), E2B, Daytona, Cloudflare Plugin-based (via Phase 6.5): Gitpod, Codespaces, Modal, Replit, etc.
Priority Legend
| Priority | Description | Target |
|---|---|---|
| P0 | Critical - Foundation/Blocking | Immediate |
| P1 | High - Core features | Near-term |
| P2 | Medium - Important enhancements | Mid-term |
| P3 | Low - Nice to have | When available |
| P4 | Enhancements - New functionality | Future |
Implementation Order
Recommended sequence:
- Phase 1 Completion (P2-P3): Finish documentation and bug fixes
- Phase 3 Core (P2): Log rotation, dry-run, config file support
- Phase 4 Testing (P2): tmux, monitor, status tests
- Phase 2 SDK (P2): Agent SDK integration (can run parallel with Phase 3)
- Phase 3 Advanced (P3): Metrics, notifications, backup
- Phase 4 Validation (P3): CLI, SDK, backward compatibility tests
- Phase 5 GitHub (P4): GitHub issue integration
- Phase 6 Sandbox (P4): Sandbox execution environments
Test Coverage
Current: 276 tests across 11 test files (100% pass rate)
| Category | Tests | Files |
|---|---|---|
| CLI Parsing | 27 | test_cli_parsing.bats |
| CLI Modern | 29 | test_cli_modern.bats |
| JSON Parsing | 36 | test_json_parsing.bats |
| Session Continuity | 26 | test_session_continuity.bats |
| Exit Detection | 20 | test_exit_detection.bats |
| Rate Limiting | 15 | test_rate_limiting.bats |
| Loop Execution | 20 | test_loop_execution.bats |
| Edge Cases | 20 | test_edge_cases.bats |
| Installation | 14 | test_installation.bats |
| Project Setup | 36 | test_project_setup.bats |
| PRD Import | 33 | test_prd_import.bats |
Completed Development
Click to expand completed work
Phase 1: CLI Modernization (Completed Issues)
| Issue | Title | Status |
|---|---|---|
| #28 | Phase 1.1: Update CLI commands with modern options | Closed |
| #29 | Phase 1.2: Enhance response parsing for JSON output | Closed |
| #30 | Phase 1.3: Add session management for continuity | Closed |
| #31 | Phase 1.4: Update ralph-import with CLI enhancements | Closed |
| #48 | MAJOR-01: Enhance shell escaping to prevent command injection | Closed |
| #50 | MAJOR-02: Add input validation for --allowed-tools flag | Closed |
Testing Issues (Completed)
| Issue | Title | Status |
|---|---|---|
| #10 | Implement CLI parsing tests | Closed |
| #11 | Implement installation tests | Closed |
| #12 | Implement project setup tests | Closed |
| #13 | Implement PRD import tests | Closed |
Bug Fixes (Completed)
| Issue | Title | Status |
|---|---|---|
| #1 | Cannot find file ~/.ralph/lib/response_analyzer.sh | Closed |
| #2 | is_error: false triggers "error" circuit breaker incorrectly | Closed |
| #5 | Bug: date: illegal option -- d on macOS | Closed |
| #7 | Review codebase for updated Anthropic CLI | Closed |
| #42 | Windows: Git Bash windows spawn when running Ralph loop | Closed |
| #55 | --prompt-file flag does not exist in Claude Code CLI | Closed |
Other Completed
| Issue | Title | Status |
|---|---|---|
| #56 | Project featured in Awesome Claude Code! | Closed |
| #63 | Fix IMPLEMENTATION_PLAN | Closed |
Version History
| Version | Key Changes |
|---|---|
| v0.9.8 | Modern CLI for PRD import with JSON output |
| v0.9.7 | Session lifecycle management with auto-reset |
| v0.9.6 | JSON output and session management |
| v0.9.5 | PRD import tests (22 tests) |
| v0.9.4 | Project setup tests (36 tests) |
| v0.9.3 | Installation tests (14 tests) |
| v0.9.2 | Prompt file fix (-p flag) |
| v0.9.1 | Modern CLI commands (Phase 1.1) |
| v0.9.0 | Circuit breaker enhancements |
Last Updated: 2026-01-10 Status: Phase 1 in progress, Phases 2-6 planned