Project Roadmap
Relevant source files
The following files were used as context for generating this wiki page:The Ralph for Claude Code project follows a phased development roadmap to systematically enhance its capabilities, moving from core CLI features to advanced integrations like SDKs, GitHub issues, and sandboxed environments. The plan prioritizes building a robust foundation before expanding into new functionality, ensuring stability and comprehensive test coverage at each stage. The current version is v0.9.8, with 276 passing tests, and the project is actively in Phase 1.
This roadmap outlines the planned development phases, their objectives, and the recommended implementation order. It serves as a guide for contributors and stakeholders to understand the project's direction and current status. For detailed contribution guidelines, refer to the CONTRIBUTING.md and for technical specifications, see CLAUDE.md.
Sources: IMPLEMENTATION_PLAN.md, README.md:4, 12, 51, IMPLEMENTATION_STATUS.md:4
Current Status (v0.9.8)
The project is currently in the final stages of Phase 1, focusing on CLI modernization. Core features are complete and stable, supported by a comprehensive test suite.
| Metric | Current Status |
|---|---|
| Version | v0.9.8 |
| Total Tests | 276 |
| Test Pass Rate | 100% |
| Current Phase | Phase 1: CLI Modernization (In Progress) |
| CI/CD | GitHub Actions operational |
Sources: IMPLEMENTATION_PLAN.md:3, 103, IMPLEMENTATION_STATUS.md:4, 10-12, README.md:4, 12
Development Phases
The project's development is structured into six distinct phases, each with a specific focus.
This diagram illustrates the progression of the planned development phases.
Sources: IMPLEMENTATION_PLAN.md:13-81
Phase 1: CLI Modernization (In Progress)
This phase focuses on modernizing the CLI, enhancing response parsing with JSON support, and establishing session management for continuity. The core features of this phase are complete, with remaining work focused on documentation and minor bug fixes.
Key Objectives:
- Update CLI commands with modern options (
--output-format,--allowed-tools). - Enhance response parsing to support structured JSON output from the Claude Code CLI.
- Implement session management for context preservation across loops.
- Update the
ralph-importtool with these CLI enhancements.
Status:
- Completed: Core CLI commands, JSON parsing, session management,
ralph-importupdates, and associated tests. - Remaining: Session expiration implementation and creation of
TESTING.mdandCONTRIBUTING.mdguides.
Sources: IMPLEMENTATION_PLAN.md:7-18, IMPLEMENTATION_STATUS.md:21-38, README.md:53-61
Phase 2: Agent SDK Integration (Planned)
This phase will migrate the project from a CLI-only execution model to a hybrid architecture that incorporates the Claude Agent SDK. This will allow for more robust and flexible tool definition and execution.
| Issue | Title | Priority |
|---|---|---|
| #32 | Phase 2.1: Create Agent SDK proof of concept | P2 |
| #33 | Phase 2.2: Define custom tools for Agent SDK | P2 |
| #34 | Phase 2.3: Implement hybrid CLI/SDK architecture | P2 |
| #35 | Phase 2.4: Document SDK migration strategy | P2 |
Sources: IMPLEMENTATION_PLAN.md:22-29
Phase 3: Configuration & Infrastructure (Planned)
This phase introduces foundational infrastructure features, including configuration file support, log rotation, and a dry-run mode. It also includes plans for more advanced features like metrics and notifications.
| Issue | Title | Priority |
|---|---|---|
| #36 | Phase 3.1: Add JSON configuration file support | P2 |
| #18 | Phase 3.4: Implement log rotation feature | P2 |
| #19 | Phase 3.5: Implement dry-run mode feature | P2 |
| #20 | Phase 3.6: Implement config file support (.ralphrc) | P2 |
| #21 | Phase 3.7: Implement metrics and analytics | P3 |
| #22 | Phase 3.8: Implement notification system | P3 |
| #23 | Phase 3.9: Implement backup and rollback system | P3 |
Sources: IMPLEMENTATION_PLAN.md:33-45, CONTRIBUTING.md:310-317
Phase 4: Validation Testing (Planned)
This phase is dedicated to creating comprehensive tests for the features developed in the preceding phases, ensuring the stability and correctness of integrations like tmux, the monitor dashboard, and the SDK.
| Issue | Title | Priority |
|---|---|---|
| #14 | Phase 4.4: Implement tmux integration tests | P2 |
| #15 | Phase 4.5: Implement monitor dashboard tests | P2 |
| #16 | Phase 4.6: Implement status update tests | P2 |
| #39 | Phase 4.1: Implement CLI enhancement tests | P3 |
| #40 | Phase 4.2: Implement SDK integration tests | P3 |
| #17 | Phase 4.7: Implement E2E full loop tests | P3 |
Sources: IMPLEMENTATION_PLAN.md:49-58
Phase 5: GitHub Issue Integration (Planned)
A future enhancement to enable Ralph to import development plans directly from GitHub issues. This would allow for a more seamless workflow where project management and autonomous development are tightly integrated.
Key Objectives:
- Import a development plan from a single GitHub issue.
- Assess issue completeness and generate an implementation plan.
- Filter and select issues based on metadata like labels and assignees.
- Manage the issue lifecycle, potentially closing issues upon task completion.
Sources: IMPLEMENTATION_PLAN.md:62-68
Phase 6: Sandbox Execution Environments (Planned)
This long-term goal aims to run Ralph in isolated sandbox environments for enhanced security and reproducibility. The plan includes first-class support for providers like Docker and E2B, with a plugin architecture for others.
First-Class Providers:
- Docker (local)
- E2B
- Daytona
- Cloudflare
Sources: IMPLEMENTATION_PLAN.md:72-84
Implementation Order
The following sequence is recommended for tackling the planned work to ensure a logical progression of features and dependencies.
This diagram shows the recommended order for implementing the development phases.
Sources: IMPLEMENTATION_PLAN.md:88-97
Priority Legend
The project uses a priority system to classify the importance and urgency of tasks.
| 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 |
Sources: IMPLEMENTATION_PLAN.md:100-107
Completed Development
A significant amount of work has been completed, primarily as part of Phase 1, along with numerous bug fixes and foundational testing.
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 |
Sources: IMPLEMENTATION_PLAN.md:112-143
Summary
The project roadmap provides a clear and structured path forward, building upon a well-tested and stable foundation. The immediate focus is on completing the final items in Phase 1, followed by core infrastructure enhancements in Phase 3 and parallel work on SDK integration in Phase 2. Future phases aim to significantly expand Ralph's capabilities by integrating with external systems like GitHub and providing secure, sandboxed execution environments. This phased approach ensures that quality and stability are maintained as the project evolves.
Sources: IMPLEMENTATION_PLAN.md, README.md:368-386