feat: Windows support (PowerShell/CMD wrappers, Windows Terminal monitoring)

[frankbria]

Summary

Add first-class Windows support for Ralph, enabling users to run Ralph natively on Windows without WSL2.

Background

PR #86 by @danielcrenna proposed comprehensive Windows support including:

• PowerShell/CMD wrappers for ralph commands
• Windows Terminal split-pane monitoring (alternative to tmux)
• Cross-platform platform utilities for OS/multiplexer detection
• Windows-specific installation scripts

Scope

This is a significant enhancement that requires architectural assessment before implementation:

1. Platform abstraction layer - How to cleanly separate platform-specific code
2. Testing strategy - CI/CD for Windows (GitHub Actions Windows runners)
3. Dependency management - Windows equivalents for bash, jq, tmux
4. Documentation - Windows-specific installation and usage guides

Prior Art

• PR Add windows split-pane monitoring support, additional support for Windows users #86 contains a working implementation (~1000 lines) that can inform the design
• Contributors: @danielcrenna

Priority

P3 - Enhancement (not blocking core functionality)

Labels

• enhancement
• platform: windows

[traycerai]

Plan

Observations

Ralph is a bash-based autonomous development loop for Claude Code with 452 passing tests and a modular architecture. The codebase already shows cross-platform awareness (file:lib/date_utils.sh handles macOS/Linux differences). Core dependencies include bash, jq, tmux, git, and coreutils. The architecture is well-structured with library modules (file:lib/circuit_breaker.sh, file:lib/enable_core.sh) and comprehensive BATS testing. PR #86 proposed ~1000 lines of Windows implementation including PowerShell/CMD wrappers and Windows Terminal monitoring.

Approach

The implementation will follow a platform abstraction layer strategy rather than full rewrites. Create a thin abstraction layer that detects the OS and delegates to platform-specific implementations (bash for Unix, PowerShell for Windows). This preserves the existing Unix codebase while adding Windows support through parallel implementations. The approach prioritizes: (1) Platform detection and abstraction, (2) Windows equivalents for core scripts, (3) Dependency management, (4) Testing infrastructure, (5) CI/CD integration, and (6) Documentation.

Implementation Plan

Phase 1: Platform Abstraction Foundation

1.1 Create Platform Detection Module

• Create file:lib/platform_utils.sh (or .ps1 wrapper) to detect OS (Windows/Linux/macOS)
• Implement get_platform() function returning: windows, linux, macos
• Implement get_shell_type() returning: bash, powershell, cmd
• Implement get_multiplexer() returning: tmux, windows-terminal, none
• Add platform-specific path utilities: normalize_path(), get_home_dir(), get_temp_dir()

1.2 Create Platform Abstraction Interface

• Design file:lib/platform_interface.sh with function signatures for:
  • platform_run_command() - Execute commands cross-platform
  • platform_get_json_tool() - Return jq path or Windows equivalent
  • platform_get_timeout_cmd() - Return timeout/gtimeout/Windows equivalent
  • platform_setup_monitoring() - Setup tmux or Windows Terminal
  • platform_get_timestamp() - Cross-platform timestamp generation
• Document the interface contract in file:docs/platform-abstraction.md

1.3 Extend Existing Cross-Platform Utilities

• Enhance file:lib/date_utils.sh to support Windows (PowerShell Get-Date)
• Add Windows detection: if [[ "$os_type" == "MINGW"* || "$os_type" == "MSYS"* ]]
• Create file:lib/json_utils.sh to abstract jq vs Windows alternatives (PowerShell ConvertFrom-Json)

Phase 2: Windows Core Implementation

2.1 PowerShell Core Scripts

• Create file:windows/ralph_loop.ps1 - PowerShell equivalent of file:ralph_loop.sh
  • Port core loop logic: rate limiting, session management, Claude CLI execution
  • Use PowerShell native JSON handling (ConvertFrom-Json, ConvertTo-Json)
  • Implement timeout using Start-Job with -Timeout parameter
  • Handle Windows paths with Join-Path and Resolve-Path
• Create file:windows/ralph_monitor.ps1 - PowerShell monitoring dashboard
  • Use PowerShell console formatting (Write-Host with colors)
  • Implement refresh loop with Start-Sleep
  • Read status from file:.ralph/status.json using Get-Content | ConvertFrom-Json

2.2 Windows Terminal Integration

• Create file:windows/ralph_terminal.ps1 for split-pane monitoring
  • Use Windows Terminal CLI: wt.exe with split-pane arguments
  • Example: wt -w 0 split-pane -H powershell -NoExit -Command ".\ralph_monitor.ps1"
  • Implement --monitor flag to launch split-pane view
  • Add fallback to separate windows if Windows Terminal not available
• Document Windows Terminal setup in file:docs/windows-terminal-setup.md

2.3 PowerShell Library Modules

• Create file:windows/lib/CircuitBreaker.psm1 - Port file:lib/circuit_breaker.sh
  • Use PowerShell classes for state management
  • Store state in file:.ralph/.circuit_breaker_state as JSON
  • Implement same thresholds: CB_NO_PROGRESS_THRESHOLD=3, etc.
• Create file:windows/lib/EnableCore.psm1 - Port file:lib/enable_core.sh
  • Project detection using PowerShell file system cmdlets
  • Template generation with here-strings (@" ... "@)
  • Safe file operations with Test-Path, New-Item

2.4 CMD Wrapper Scripts (Optional)

• Create file:windows/ralph.cmd - Thin wrapper calling PowerShell

  @echo off
  powershell -ExecutionPolicy Bypass -File "%~dp0ralph_loop.ps1" %*

• Create file:windows/ralph-monitor.cmd, file:windows/ralph-setup.cmd similarly
• Enables users to run ralph from CMD without typing powershell

Phase 3: Dependency Management

3.1 Windows Dependency Detection

• Create file:windows/install.ps1 - Windows installation script
  • Check for PowerShell 5.1+ or PowerShell Core 7+
  • Check for Node.js/npm (Claude Code CLI dependency)
  • Check for Git for Windows
  • Check for Windows Terminal (optional, recommended)
  • Provide installation instructions for missing dependencies
• Add dependency check to file:windows/ralph_loop.ps1 startup

3.2 JSON Processing on Windows

• Primary: Use PowerShell native JSON (ConvertFrom-Json, ConvertTo-Json)
• Fallback: Detect and use jq if installed (Git for Windows includes it)
• Create file:windows/lib/JsonUtils.psm1 with unified interface:
  • Get-JsonField -Path $file -Field "status"
  • Set-JsonField -Path $file -Field "status" -Value "running"
  • Auto-detect available tool (PowerShell native vs jq)

3.3 Timeout Command Equivalent

• Use PowerShell Start-Job with timeout:

  $job = Start-Job -ScriptBlock { claude-code ... }
  Wait-Job $job -Timeout $timeoutSeconds
  if ($job.State -eq 'Running') { Stop-Job $job; Remove-Job $job }

• Create file:windows/lib/TimeoutUtils.psm1 wrapping this pattern
• Maintain same timeout behavior as Unix version (default 15 minutes)

Phase 4: Installation & Setup

4.1 Windows Installation Script

• Create file:windows/install.ps1 with installation logic:
  • Create $env:USERPROFILE\.ralph directory
  • Copy PowerShell scripts to $env:USERPROFILE\.ralph\windows
  • Copy library modules to $env:USERPROFILE\.ralph\lib
  • Copy templates to $env:USERPROFILE\.ralph\templates
  • Add $env:USERPROFILE\.ralph\windows to PATH (user environment variable)
  • Create PowerShell profile entry for auto-loading Ralph functions
• Add uninstall functionality: file:windows/uninstall.ps1

4.2 Cross-Platform Installation Wrapper

• Update file:install.sh to detect Windows (Git Bash/WSL) and delegate:

  if [[ "$os_type" == "MINGW"* || "$os_type" == "MSYS"* ]]; then
      powershell -ExecutionPolicy Bypass -File ./windows/install.ps1
  else
      # Existing Unix installation
  fi

• Create file:README-WINDOWS.md with Windows-specific instructions

4.3 Project Setup on Windows

• Create file:windows/setup.ps1 - Port file:setup.sh
  • Create file:.ralph/ directory structure
  • Generate file:.ralph/PROMPT.md, file:.ralph/fix_plan.md, file:.ralph/AGENT.md
  • Create file:.ralphrc with Windows-compatible paths
  • Initialize Git repository if not exists
• Ensure templates work on Windows (line endings, paths)

Phase 5: Testing Infrastructure

5.1 PowerShell Testing Framework

• Choose Pester (PowerShell native testing framework) as BATS equivalent
• Create file:windows/tests/Ralph.Tests.ps1 - Main test suite
• Port critical tests from file:tests/unit/ and file:tests/integration/:
  • CLI parsing tests → file:windows/tests/CliParsing.Tests.ps1
  • JSON parsing tests → file:windows/tests/JsonParsing.Tests.ps1
  • Session management tests → file:windows/tests/SessionManagement.Tests.ps1
  • Circuit breaker tests → file:windows/tests/CircuitBreaker.Tests.ps1
  • Installation tests → file:windows/tests/Installation.Tests.ps1

5.2 Test Helpers and Mocks

• Create file:windows/tests/TestHelpers.psm1 - Port file:tests/helpers/test_helper.bash
  • Mock file system operations
  • Mock Claude CLI responses
  • Create temporary test directories
  • Assert functions: Assert-FileExists, Assert-JsonValid, etc.
• Aim for 80%+ test coverage of Windows-specific code

5.3 Cross-Platform Test Suite

• Create file:tests/cross-platform/ directory for tests that run on both platforms
• Use conditional execution based on platform detection
• Test platform abstraction layer thoroughly
• Ensure consistent behavior across Windows/Unix

Phase 6: CI/CD Integration

6.1 GitHub Actions Windows Runners

• Update file:.github/workflows/test.yml to add Windows job:

  test-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PowerShell
        uses: actions/setup-powershell@v1
      - name: Install dependencies
        run: |
          choco install nodejs git
          npm install -g @anthropic-ai/claude-code
      - name: Run Windows tests
        run: |
          cd windows
          Invoke-Pester -Path tests/ -Output Detailed

• Add matrix strategy to test on: ubuntu-latest, macos-latest, windows-latest

6.2 Windows-Specific CI Checks

• Test installation script: file:windows/install.ps1
• Test core loop execution: file:windows/ralph_loop.ps1
• Test monitoring dashboard: file:windows/ralph_monitor.ps1
• Verify Windows Terminal integration (if available)
• Check PowerShell module loading and function exports

6.3 Cross-Platform Integration Tests

• Create file:tests/integration/test_cross_platform.bats (or .ps1)
• Test that platform detection works correctly
• Test that abstraction layer delegates properly
• Verify consistent behavior across platforms
• Test installation on all platforms

Phase 7: Documentation

7.1 Windows User Documentation

• Create file:docs/windows/README.md - Windows-specific guide
  • Installation instructions (PowerShell, dependencies)
  • Windows Terminal setup and configuration
  • Differences from Unix version (if any)
  • Troubleshooting common Windows issues
  • PowerShell execution policy setup
• Create file:docs/windows/INSTALLATION.md - Detailed installation guide
• Create file:docs/windows/TROUBLESHOOTING.md - Windows-specific issues

7.2 Update Main Documentation

• Update file:README.md with Windows support section:
  • Add Windows to system requirements
  • Add Windows installation instructions
  • Add Windows Terminal to monitoring section
  • Update dependency list (PowerShell 5.1+, Windows Terminal optional)
• Update file:CONTRIBUTING.md with Windows development setup
• Update file:TESTING.md with Pester testing instructions

7.3 Platform Abstraction Documentation

• Create file:docs/architecture/platform-abstraction.md
  • Explain the abstraction layer design
  • Document platform-specific implementations
  • Provide guidelines for adding new platform support
  • Include architecture diagrams (Mermaid)

7.4 Migration Guide

• Create file:docs/windows/MIGRATION.md for WSL users
  • How to migrate from WSL to native Windows
  • Differences in behavior and configuration
  • Path translation guide (WSL paths vs Windows paths)

Phase 8: Polish & Validation

8.1 Windows-Specific Features

• Add Windows notification support using PowerShell:

  New-BurntToastNotification -Text "Ralph completed loop #5"

• Add Windows Terminal theme/color scheme for Ralph
• Create Windows-specific examples in file:examples/windows/

8.2 Performance Optimization

• Profile PowerShell script performance
• Optimize JSON parsing (native vs jq)
• Optimize file I/O operations
• Ensure monitoring dashboard refresh is smooth

8.3 User Experience

• Add progress indicators for long operations
• Improve error messages with Windows-specific guidance
• Add colored output using PowerShell Write-Host -ForegroundColor
• Create Windows installer (optional): MSI or Chocolatey package

8.4 Final Validation

• Test on Windows 10 and Windows 11
• Test with PowerShell 5.1 and PowerShell Core 7+
• Test with and without Windows Terminal
• Test with Git Bash, CMD, and PowerShell
• Verify all 452 tests pass on Windows (or equivalent Pester tests)

Architecture Diagram

graph TD
    A[User Command: ralph --monitor] --> B{Platform Detection}
    B -->|Windows| C[windows/ralph_loop.ps1]
    B -->|Unix| D[ralph_loop.sh]
    
    C --> E[PowerShell Libraries]
    D --> F[Bash Libraries]
    
    E --> G[CircuitBreaker.psm1]
    E --> H[EnableCore.psm1]
    E --> I[JsonUtils.psm1]
    
    F --> J[circuit_breaker.sh]
    F --> K[enable_core.sh]
    F --> L[json_utils.sh]
    
    C --> M{Monitoring?}
    D --> M
    
    M -->|Yes, Windows| N[Windows Terminal Split-Pane]
    M -->|Yes, Unix| O[tmux Split-Pane]
    M -->|No| P[Single Pane Execution]
    
    N --> Q[ralph_monitor.ps1]
    O --> R[ralph_monitor.sh]
    
    C --> S[Claude Code CLI]
    D --> S
    
    S --> T[.ralph/ Project Files]
    
    style C fill:#0078D4
    style D fill:#4EAA25
    style N fill:#0078D4
    style O fill:#4EAA25

Loading

File Structure

ralph-claude-code/
├── windows/                          # Windows-specific implementations
│   ├── install.ps1                   # Windows installation script
│   ├── uninstall.ps1                 # Windows uninstallation script
│   ├── ralph_loop.ps1                # Core loop (PowerShell)
│   ├── ralph_monitor.ps1             # Monitoring dashboard (PowerShell)
│   ├── ralph_terminal.ps1            # Windows Terminal integration
│   ├── setup.ps1                     # Project setup (PowerShell)
│   ├── ralph_enable.ps1              # Enable wizard (PowerShell)
│   ├── ralph.cmd                     # CMD wrapper
│   ├── ralph-monitor.cmd             # CMD wrapper
│   ├── lib/                          # PowerShell modules
│   │   ├── CircuitBreaker.psm1
│   │   ├── EnableCore.psm1
│   │   ├── JsonUtils.psm1
│   │   ├── TimeoutUtils.psm1
│   │   └── PlatformUtils.psm1
│   └── tests/                        # Pester tests
│       ├── Ralph.Tests.ps1
│       ├── CliParsing.Tests.ps1
│       ├── JsonParsing.Tests.ps1
│       ├── CircuitBreaker.Tests.ps1
│       └── TestHelpers.psm1
├── lib/                              # Shared/Unix libraries
│   ├── platform_utils.sh             # NEW: Platform detection
│   ├── platform_interface.sh         # NEW: Abstraction interface
│   ├── json_utils.sh                 # NEW: JSON abstraction
│   ├── circuit_breaker.sh            # Existing
│   ├── enable_core.sh                # Existing
│   └── date_utils.sh                 # Enhanced for Windows
├── docs/
│   ├── windows/                      # NEW: Windows documentation
│   │   ├── README.md
│   │   ├── INSTALLATION.md
│   │   ├── TROUBLESHOOTING.md
│   │   └── MIGRATION.md
│   └── architecture/
│       └── platform-abstraction.md   # NEW: Architecture docs
├── .github/workflows/
│   └── test.yml                      # Enhanced with Windows runners
├── README.md                         # Updated with Windows support
└── README-WINDOWS.md                 # NEW: Windows quick start

Testing Strategy

Test Category	Unix (BATS)	Windows (Pester)	Target Coverage
CLI Parsing	file:tests/unit/test_cli_parsing.bats	file:windows/tests/CliParsing.Tests.ps1	100%
JSON Handling	file:tests/unit/test_json_parsing.bats	file:windows/tests/JsonParsing.Tests.ps1	100%
Circuit Breaker	file:tests/unit/test_exit_detection.bats	file:windows/tests/CircuitBreaker.Tests.ps1	100%
Installation	file:tests/integration/test_installation.bats	file:windows/tests/Installation.Tests.ps1	100%
Platform Abstraction	file:tests/cross-platform/	file:tests/cross-platform/	100%
Total	452 tests	~300 tests	80%+

Dependencies

Windows Requirements

• PowerShell 5.1+ or PowerShell Core 7+ (built-in on Windows 10/11)
• Node.js 18+ and npm (for Claude Code CLI)
• Git for Windows (includes Git Bash, optional jq)
• Windows Terminal (optional, recommended for monitoring)
• Pester 5.0+ (for testing, install via Install-Module -Name Pester)

Unix Requirements (Unchanged)

• Bash 4.0+
• jq
• tmux
• git
• coreutils
• Node.js/npm

Risk Mitigation

1. Backward Compatibility: All Unix functionality remains unchanged; Windows is additive
2. Testing Coverage: Aim for 80%+ test coverage on Windows before release
3. Gradual Rollout: Mark Windows support as "beta" initially (v0.12.0-beta)
4. Documentation: Comprehensive Windows docs to reduce support burden
5. Community Feedback: Solicit early feedback from Windows users via GitHub Discussions

Success Criteria

• Ralph installs successfully on Windows 10/11
• Core loop executes and completes tasks on Windows
• Windows Terminal monitoring works with split-pane view
• 80%+ of Unix tests have Windows equivalents (Pester)
• CI/CD passes on Windows runners
• Documentation covers Windows installation and usage
• No regressions in Unix functionality
• Performance comparable to Unix version (±20%)

Import In IDE

🤖 Prompt for AI Agents

## Observations

Ralph is a bash-based autonomous development loop for Claude Code with 452 passing tests and a modular architecture. The codebase already shows cross-platform awareness (file:lib/date_utils.sh handles macOS/Linux differences). Core dependencies include bash, jq, tmux, git, and coreutils. The architecture is well-structured with library modules (file:lib/circuit_breaker.sh, file:lib/enable_core.sh) and comprehensive BATS testing. PR #86 proposed ~1000 lines of Windows implementation including PowerShell/CMD wrappers and Windows Terminal monitoring.

## Approach

The implementation will follow a **platform abstraction layer** strategy rather than full rewrites. Create a thin abstraction layer that detects the OS and delegates to platform-specific implementations (bash for Unix, PowerShell for Windows). This preserves the existing Unix codebase while adding Windows support through parallel implementations. The approach prioritizes: (1) Platform detection and abstraction, (2) Windows equivalents for core scripts, (3) Dependency management, (4) Testing infrastructure, (5) CI/CD integration, and (6) Documentation.

## Implementation Plan

### Phase 1: Platform Abstraction Foundation

**1.1 Create Platform Detection Module**
- Create file:lib/platform_utils.sh (or .ps1 wrapper) to detect OS (Windows/Linux/macOS)
- Implement `get_platform()` function returning: `windows`, `linux`, `macos`
- Implement `get_shell_type()` returning: `bash`, `powershell`, `cmd`
- Implement `get_multiplexer()` returning: `tmux`, `windows-terminal`, `none`
- Add platform-specific path utilities: `normalize_path()`, `get_home_dir()`, `get_temp_dir()`

**1.2 Create Platform Abstraction Interface**
- Design file:lib/platform_interface.sh with function signatures for:
  - `platform_run_command()` - Execute commands cross-platform
  - `platform_get_json_tool()` - Return jq path or Windows equivalent
  - `platform_get_timeout_cmd()` - Return timeout/gtimeout/Windows equivalent
  - `platform_setup_monitoring()` - Setup tmux or Windows Terminal
  - `platform_get_timestamp()` - Cross-platform timestamp generation
- Document the interface contract in file:docs/platform-abstraction.md

**1.3 Extend Existing Cross-Platform Utilities**
- Enhance file:lib/date_utils.sh to support Windows (PowerShell `Get-Date`)
- Add Windows detection: `if [[ "$os_type" == "MINGW"* || "$os_type" == "MSYS"* ]]`
- Create file:lib/json_utils.sh to abstract jq vs Windows alternatives (PowerShell `ConvertFrom-Json`)

### Phase 2: Windows Core Implementation

**2.1 PowerShell Core Scripts**
- Create file:windows/ralph_loop.ps1 - PowerShell equivalent of file:ralph_loop.sh
  - Port core loop logic: rate limiting, session management, Claude CLI execution
  - Use PowerShell native JSON handling (`ConvertFrom-Json`, `ConvertTo-Json`)
  - Implement timeout using `Start-Job` with `-Timeout` parameter
  - Handle Windows paths with `Join-Path` and `Resolve-Path`
- Create file:windows/ralph_monitor.ps1 - PowerShell monitoring dashboard
  - Use PowerShell console formatting (`Write-Host` with colors)
  - Implement refresh loop with `Start-Sleep`
  - Read status from file:.ralph/status.json using `Get-Content | ConvertFrom-Json`

**2.2 Windows Terminal Integration**
- Create file:windows/ralph_terminal.ps1 for split-pane monitoring
  - Use Windows Terminal CLI: `wt.exe` with split-pane arguments
  - Example: `wt -w 0 split-pane -H powershell -NoExit -Command ".\ralph_monitor.ps1"`
  - Implement `--monitor` flag to launch split-pane view
  - Add fallback to separate windows if Windows Terminal not available
- Document Windows Terminal setup in file:docs/windows-terminal-setup.md

**2.3 PowerShell Library Modules**
- Create file:windows/lib/CircuitBreaker.psm1 - Port file:lib/circuit_breaker.sh
  - Use PowerShell classes for state management
  - Store state in file:.ralph/.circuit_breaker_state as JSON
  - Implement same thresholds: `CB_NO_PROGRESS_THRESHOLD=3`, etc.
- Create file:windows/lib/EnableCore.psm1 - Port file:lib/enable_core.sh
  - Project detection using PowerShell file system cmdlets
  - Template generation with here-strings (`@" ... "@`)
  - Safe file operations with `Test-Path`, `New-Item`

**2.4 CMD Wrapper Scripts (Optional)**
- Create file:windows/ralph.cmd - Thin wrapper calling PowerShell
  ```cmd
  @echo off
  powershell -ExecutionPolicy Bypass -File "%~dp0ralph_loop.ps1" %*
  ```
- Create file:windows/ralph-monitor.cmd, file:windows/ralph-setup.cmd similarly
- Enables users to run `ralph` from CMD without typing `powershell`

### Phase 3: Dependency Management

**3.1 Windows Dependency Detection**
- Create file:windows/install.ps1 - Windows installation script
  - Check for PowerShell 5.1+ or PowerShell Core 7+
  - Check for Node.js/npm (Claude Code CLI dependency)
  - Check for Git for Windows
  - Check for Windows Terminal (optional, recommended)
  - Provide installation instructions for missing dependencies
- Add dependency check to file:windows/ralph_loop.ps1 startup

**3.2 JSON Processing on Windows**
- Primary: Use PowerShell native JSON (`ConvertFrom-Json`, `ConvertTo-Json`)
- Fallback: Detect and use jq if installed (Git for Windows includes it)
- Create file:windows/lib/JsonUtils.psm1 with unified interface:
  - `Get-JsonField -Path $file -Field "status"`
  - `Set-JsonField -Path $file -Field "status" -Value "running"`
  - Auto-detect available tool (PowerShell native vs jq)

**3.3 Timeout Command Equivalent**
- Use PowerShell `Start-Job` with timeout:
  ```powershell
  $job = Start-Job -ScriptBlock { claude-code ... }
  Wait-Job $job -Timeout $timeoutSeconds
  if ($job.State -eq 'Running') { Stop-Job $job; Remove-Job $job }
  ```
- Create file:windows/lib/TimeoutUtils.psm1 wrapping this pattern
- Maintain same timeout behavior as Unix version (default 15 minutes)

### Phase 4: Installation & Setup

**4.1 Windows Installation Script**
- Create file:windows/install.ps1 with installation logic:
  - Create `$env:USERPROFILE\.ralph` directory
  - Copy PowerShell scripts to `$env:USERPROFILE\.ralph\windows`
  - Copy library modules to `$env:USERPROFILE\.ralph\lib`
  - Copy templates to `$env:USERPROFILE\.ralph\templates`
  - Add `$env:USERPROFILE\.ralph\windows` to PATH (user environment variable)
  - Create PowerShell profile entry for auto-loading Ralph functions
- Add uninstall functionality: file:windows/uninstall.ps1

**4.2 Cross-Platform Installation Wrapper**
- Update file:install.sh to detect Windows (Git Bash/WSL) and delegate:
  ```bash
  if [[ "$os_type" == "MINGW"* || "$os_type" == "MSYS"* ]]; then
      powershell -ExecutionPolicy Bypass -File ./windows/install.ps1
  else
      # Existing Unix installation
  fi
  ```
- Create file:README-WINDOWS.md with Windows-specific instructions

**4.3 Project Setup on Windows**
- Create file:windows/setup.ps1 - Port file:setup.sh
  - Create file:.ralph/ directory structure
  - Generate file:.ralph/PROMPT.md, file:.ralph/fix_plan.md, file:.ralph/AGENT.md
  - Create file:.ralphrc with Windows-compatible paths
  - Initialize Git repository if not exists
- Ensure templates work on Windows (line endings, paths)

### Phase 5: Testing Infrastructure

**5.1 PowerShell Testing Framework**
- Choose Pester (PowerShell native testing framework) as BATS equivalent
- Create file:windows/tests/Ralph.Tests.ps1 - Main test suite
- Port critical tests from file:tests/unit/ and file:tests/integration/:
  - CLI parsing tests → file:windows/tests/CliParsing.Tests.ps1
  - JSON parsing tests → file:windows/tests/JsonParsing.Tests.ps1
  - Session management tests → file:windows/tests/SessionManagement.Tests.ps1
  - Circuit breaker tests → file:windows/tests/CircuitBreaker.Tests.ps1
  - Installation tests → file:windows/tests/Installation.Tests.ps1

**5.2 Test Helpers and Mocks**
- Create file:windows/tests/TestHelpers.psm1 - Port file:tests/helpers/test_helper.bash
  - Mock file system operations
  - Mock Claude CLI responses
  - Create temporary test directories
  - Assert functions: `Assert-FileExists`, `Assert-JsonValid`, etc.
- Aim for 80%+ test coverage of Windows-specific code

**5.3 Cross-Platform Test Suite**
- Create file:tests/cross-platform/ directory for tests that run on both platforms
- Use conditional execution based on platform detection
- Test platform abstraction layer thoroughly
- Ensure consistent behavior across Windows/Unix

### Phase 6: CI/CD Integration

**6.1 GitHub Actions Windows Runners**
- Update file:.github/workflows/test.yml to add Windows job:
  ```yaml
  test-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PowerShell
        uses: actions/setup-powershell@v1
      - name: Install dependencies
        run: |
          choco install nodejs git
          npm install -g @anthropic-ai/claude-code
      - name: Run Windows tests
        run: |
          cd windows
          Invoke-Pester -Path tests/ -Output Detailed
  ```
- Add matrix strategy to test on: `ubuntu-latest`, `macos-latest`, `windows-latest`

**6.2 Windows-Specific CI Checks**
- Test installation script: file:windows/install.ps1
- Test core loop execution: file:windows/ralph_loop.ps1
- Test monitoring dashboard: file:windows/ralph_monitor.ps1
- Verify Windows Terminal integration (if available)
- Check PowerShell module loading and function exports

**6.3 Cross-Platform Integration Tests**
- Create file:tests/integration/test_cross_platform.bats (or .ps1)
- Test that platform detection works correctly
- Test that abstraction layer delegates properly
- Verify consistent behavior across platforms
- Test installation on all platforms

### Phase 7: Documentation

**7.1 Windows User Documentation**
- Create file:docs/windows/README.md - Windows-specific guide
  - Installation instructions (PowerShell, dependencies)
  - Windows Terminal setup and configuration
  - Differences from Unix version (if any)
  - Troubleshooting common Windows issues
  - PowerShell execution policy setup
- Create file:docs/windows/INSTALLATION.md - Detailed installation guide
- Create file:docs/windows/TROUBLESHOOTING.md - Windows-specific issues

**7.2 Update Main Documentation**
- Update file:README.md with Windows support section:
  - Add Windows to system requirements
  - Add Windows installation instructions
  - Add Windows Terminal to monitoring section
  - Update dependency list (PowerShell 5.1+, Windows Terminal optional)
- Update file:CONTRIBUTING.md with Windows development setup
- Update file:TESTING.md with Pester testing instructions

**7.3 Platform Abstraction Documentation**
- Create file:docs/architecture/platform-abstraction.md
  - Explain the abstraction layer design
  - Document platform-specific implementations
  - Provide guidelines for adding new platform support
  - Include architecture diagrams (Mermaid)

**7.4 Migration Guide**
- Create file:docs/windows/MIGRATION.md for WSL users
  - How to migrate from WSL to native Windows
  - Differences in behavior and configuration
  - Path translation guide (WSL paths vs Windows paths)

### Phase 8: Polish & Validation

**8.1 Windows-Specific Features**
- Add Windows notification support using PowerShell:
  ```powershell
  New-BurntToastNotification -Text "Ralph completed loop #5"
  ```
- Add Windows Terminal theme/color scheme for Ralph
- Create Windows-specific examples in file:examples/windows/

**8.2 Performance Optimization**
- Profile PowerShell script performance
- Optimize JSON parsing (native vs jq)
- Optimize file I/O operations
- Ensure monitoring dashboard refresh is smooth

**8.3 User Experience**
- Add progress indicators for long operations
- Improve error messages with Windows-specific guidance
- Add colored output using PowerShell `Write-Host -ForegroundColor`
- Create Windows installer (optional): MSI or Chocolatey package

**8.4 Final Validation**
- Test on Windows 10 and Windows 11
- Test with PowerShell 5.1 and PowerShell Core 7+
- Test with and without Windows Terminal
- Test with Git Bash, CMD, and PowerShell
- Verify all 452 tests pass on Windows (or equivalent Pester tests)

## Architecture Diagram

```mermaid
graph TD
    A[User Command: ralph --monitor] --> B{Platform Detection}
    B -->|Windows| C[windows/ralph_loop.ps1]
    B -->|Unix| D[ralph_loop.sh]
    
    C --> E[PowerShell Libraries]
    D --> F[Bash Libraries]
    
    E --> G[CircuitBreaker.psm1]
    E --> H[EnableCore.psm1]
    E --> I[JsonUtils.psm1]
    
    F --> J[circuit_breaker.sh]
    F --> K[enable_core.sh]
    F --> L[json_utils.sh]
    
    C --> M{Monitoring?}
    D --> M
    
    M -->|Yes, Windows| N[Windows Terminal Split-Pane]
    M -->|Yes, Unix| O[tmux Split-Pane]
    M -->|No| P[Single Pane Execution]
    
    N --> Q[ralph_monitor.ps1]
    O --> R[ralph_monitor.sh]
    
    C --> S[Claude Code CLI]
    D --> S
    
    S --> T[.ralph/ Project Files]
    
    style C fill:#0078D4
    style D fill:#4EAA25
    style N fill:#0078D4
    style O fill:#4EAA25
```

## File Structure

```
ralph-claude-code/
├── windows/                          # Windows-specific implementations
│   ├── install.ps1                   # Windows installation script
│   ├── uninstall.ps1                 # Windows uninstallation script
│   ├── ralph_loop.ps1                # Core loop (PowerShell)
│   ├── ralph_monitor.ps1             # Monitoring dashboard (PowerShell)
│   ├── ralph_terminal.ps1            # Windows Terminal integration
│   ├── setup.ps1                     # Project setup (PowerShell)
│   ├── ralph_enable.ps1              # Enable wizard (PowerShell)
│   ├── ralph.cmd                     # CMD wrapper
│   ├── ralph-monitor.cmd             # CMD wrapper
│   ├── lib/                          # PowerShell modules
│   │   ├── CircuitBreaker.psm1
│   │   ├── EnableCore.psm1
│   │   ├── JsonUtils.psm1
│   │   ├── TimeoutUtils.psm1
│   │   └── PlatformUtils.psm1
│   └── tests/                        # Pester tests
│       ├── Ralph.Tests.ps1
│       ├── CliParsing.Tests.ps1
│       ├── JsonParsing.Tests.ps1
│       ├── CircuitBreaker.Tests.ps1
│       └── TestHelpers.psm1
├── lib/                              # Shared/Unix libraries
│   ├── platform_utils.sh             # NEW: Platform detection
│   ├── platform_interface.sh         # NEW: Abstraction interface
│   ├── json_utils.sh                 # NEW: JSON abstraction
│   ├── circuit_breaker.sh            # Existing
│   ├── enable_core.sh                # Existing
│   └── date_utils.sh                 # Enhanced for Windows
├── docs/
│   ├── windows/                      # NEW: Windows documentation
│   │   ├── README.md
│   │   ├── INSTALLATION.md
│   │   ├── TROUBLESHOOTING.md
│   │   └── MIGRATION.md
│   └── architecture/
│       └── platform-abstraction.md   # NEW: Architecture docs
├── .github/workflows/
│   └── test.yml                      # Enhanced with Windows runners
├── README.md                         # Updated with Windows support
└── README-WINDOWS.md                 # NEW: Windows quick start
```

## Testing Strategy

| Test Category | Unix (BATS) | Windows (Pester) | Target Coverage |
|--------------|-------------|------------------|-----------------|
| CLI Parsing | file:tests/unit/test_cli_parsing.bats | file:windows/tests/CliParsing.Tests.ps1 | 100% |
| JSON Handling | file:tests/unit/test_json_parsing.bats | file:windows/tests/JsonParsing.Tests.ps1 | 100% |
| Circuit Breaker | file:tests/unit/test_exit_detection.bats | file:windows/tests/CircuitBreaker.Tests.ps1 | 100% |
| Installation | file:tests/integration/test_installation.bats | file:windows/tests/Installation.Tests.ps1 | 100% |
| Platform Abstraction | file:tests/cross-platform/ | file:tests/cross-platform/ | 100% |
| **Total** | **452 tests** | **~300 tests** | **80%+** |

## Dependencies

### Windows Requirements
- **PowerShell 5.1+** or **PowerShell Core 7+** (built-in on Windows 10/11)
- **Node.js 18+** and **npm** (for Claude Code CLI)
- **Git for Windows** (includes Git Bash, optional jq)
- **Windows Terminal** (optional, recommended for monitoring)
- **Pester 5.0+** (for testing, install via `Install-Module -Name Pester`)

### Unix Requirements (Unchanged)
- Bash 4.0+
- jq
- tmux
- git
- coreutils
- Node.js/npm

## Risk Mitigation

1. **Backward Compatibility**: All Unix functionality remains unchanged; Windows is additive
2. **Testing Coverage**: Aim for 80%+ test coverage on Windows before release
3. **Gradual Rollout**: Mark Windows support as "beta" initially (v0.12.0-beta)
4. **Documentation**: Comprehensive Windows docs to reduce support burden
5. **Community Feedback**: Solicit early feedback from Windows users via GitHub Discussions

## Success Criteria

- [ ] Ralph installs successfully on Windows 10/11
- [ ] Core loop executes and completes tasks on Windows
- [ ] Windows Terminal monitoring works with split-pane view
- [ ] 80%+ of Unix tests have Windows equivalents (Pester)
- [ ] CI/CD passes on Windows runners
- [ ] Documentation covers Windows installation and usage
- [ ] No regressions in Unix functionality
- [ ] Performance comparable to Unix version (±20%)

---

Execution Information

Branch: main
Commit: 48ba86a

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#108 - Add timeout command support for macOS [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[psmux]

psmux maintainer here. This is a well-structured plan, but I wanted to suggest an approach that could dramatically reduce the scope of the Windows porting effort.

The core problem

Ralph depends on tmux for session management (detach/reattach, split panes, monitoring). The plan proposes building an entire Windows Terminal integration from scratch with PowerShell, which is a massive amount of work (8 phases, ~30+ new files).

Simpler alternative: psmux as a drop-in tmux replacement

psmux is a native Windows terminal multiplexer (written in Rust) that implements 76 tmux-compatible commands and ships a tmux.exe alias. This means Ralph's existing tmux commands would work on Windows without rewriting them.

What psmux provides that maps directly to Ralph's needs:

Ralph requirement	tmux command (existing)	Works with psmux?
Session management	tmux new-session -d -s ralph	Yes
Monitoring dashboard	tmux split-window	Yes
Send commands to pane	tmux send-keys -t ralph "cmd" Enter	Yes
Capture output	tmux capture-pane -t ralph -p	Yes
Check session alive	tmux has-session -t ralph	Yes
Kill session	tmux kill-session -t ralph	Yes
List sessions	tmux list-sessions	Yes
Detach/reattach	tmux detach / tmux attach -t ralph	Yes

What this means for the plan

Instead of 8 phases of porting, the Windows support path could be:

1. Phase 1: Add psmux to install instructions (one-liner: winget install psmux)
2. Phase 2: Test existing Ralph scripts work via Git Bash or WSL on Windows with psmux providing the tmux layer
3. Phase 3: Fix any small incompatibilities (path separators, shell detection)
4. Phase 4: Document

The jq dependency can be handled by Git for Windows (which includes jq) or by adding it to the install prerequisites.

Install

winget install psmux

Also: cargo install psmux, scoop install psmux, choco install psmux

Current version: v0.4.10. Reads .tmux.conf, supports tmux themes, full mouse, session persistence, 126+ format variables.

This wouldn't cover every edge case in the plan (Windows notifications, Pester tests, etc.), but it would get Ralph working on Windows with a fraction of the effort, by leveraging the existing tmux-based codebase instead of rewriting it in PowerShell.