Windows Installation Guide¶

This guide walks you through installing and using PortableRalph on Windows.

Prerequisites¶

Required Software¶

Windows 10/11 (64-bit)
Git for Windows - Download
Claude Code CLI - Installation Guide

Optional But Recommended¶

Windows Terminal - Microsoft Store
Visual Studio Code - Download
WSL2 (Windows Subsystem for Linux) - For best compatibility

Installation Methods¶

Method 1: WSL2 (Recommended)¶

WSL2 provides the best compatibility with Ralph's bash scripts.

Step 1: Install WSL2¶

Open PowerShell as Administrator:

# Enable WSL
wsl --install

# Restart computer when prompted

After restart:

# Install Ubuntu
wsl --install -d Ubuntu

# Launch Ubuntu
wsl

Step 2: Install Ralph in WSL¶

Inside the WSL Ubuntu terminal:

# Update package list
sudo apt update
sudo apt install -y curl git

# Install Claude CLI
curl -fsSL https://claude.ai/download/cli/install.sh | bash

# Install Ralph
curl -fsSL https://raw.githubusercontent.com/aaron777collins/portableralph/master/install.sh | bash

# Configure shell
echo 'alias ralph="$HOME/ralph/ralph.sh"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
ralph --version

Step 3: Access Windows Files¶

WSL can access Windows files:

# Windows C: drive is at /mnt/c/
cd /mnt/c/Users/YourUsername/Projects

# Run Ralph on Windows files
ralph ./plan.md

Access WSL files from Windows: - Open File Explorer - Type \\wsl$\Ubuntu\home\yourusername in address bar

Method 2: Git Bash (Native Windows)¶

Git Bash provides a Unix-like environment on Windows.

Step 1: Install Git for Windows¶

Download from git-scm.com
Run installer
Important: Select "Use Git and optional Unix tools from the Command Prompt"
Complete installation

Step 2: Install Ralph¶

Open Git Bash:

# Install Claude CLI (follow official docs for Windows)
# Then install Ralph

cd ~
git clone https://github.com/aaron777collins/portableralph.git ralph
chmod +x ~/ralph/*.sh

# Add to PATH
echo 'export PATH="$HOME/ralph:$PATH"' >> ~/.bashrc
echo 'alias ralph="~/ralph/ralph.sh"' >> ~/.bashrc
source ~/.bashrc

# Verify
ralph --version

Step 3: Handle Line Endings¶

Windows uses CRLF, Unix uses LF. Configure git:

# Configure git to handle line endings
cd ~/ralph
git config core.autocrlf input

# Convert existing files
find ~/ralph -name "*.sh" -exec dos2unix {} \;

If dos2unix isn't available:

# Install via Git Bash package manager
pacman -S dos2unix

# Or manually fix line endings
sed -i 's/\r$//' ~/ralph/*.sh

Method 3: PowerShell (Enhanced Support)¶

Ralph now includes enhanced PowerShell support with cross-platform compatibility utilities.

Step 1: Enable Linux-like Commands¶

# Install Scoop (package manager)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# Install Unix tools
scoop install git curl grep sed

Step 2: Install Ralph¶

# Clone repository
cd $HOME
git clone https://github.com/aaron777collins/portableralph.git ralph

# Create PowerShell wrapper
New-Item -Path "$HOME\ralph\ralph.ps1" -ItemType File -Force

Add to ralph.ps1:

#!/usr/bin/env pwsh
# Ralph PowerShell wrapper

$RalphDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$BashScript = Join-Path $RalphDir "ralph.sh"

# Run with Git Bash
& "C:\Program Files\Git\bin\bash.exe" $BashScript $args

Step 3: Add to PATH¶

# Add to PowerShell profile
$ProfilePath = $PROFILE.CurrentUserAllHosts
if (-not (Test-Path $ProfilePath)) {
    New-Item -Path $ProfilePath -ItemType File -Force
}

Add-Content $ProfilePath @"
# Ralph alias
function ralph { & `$HOME\ralph\ralph.ps1 @args }
"@

# Reload profile
. $PROFILE

Step 4: PowerShell Compatibility Utilities¶

Ralph includes lib/compat-utils.ps1 with cross-platform functions:

# Import compatibility utilities
. "$HOME\ralph\lib\compat-utils.ps1"

# Available functions:
Get-UnixPath              # Convert Windows path to Unix path
Get-WindowsPath           # Convert Unix path to Windows path
Test-CommandExists        # Check if command is available
Invoke-SafeCommand        # Execute command with error handling
Get-RalphConfig           # Read Ralph configuration
Set-RalphConfig           # Update Ralph configuration
Test-RalphDependencies    # Verify all dependencies installed

Example Usage:

# Convert paths for WSL
$unixPath = Get-UnixPath "C:\Users\name\project"
# Returns: /mnt/c/Users/name/project

# Check dependencies
if (Test-RalphDependencies) {
    Write-Host "All dependencies installed"
}

# Safe command execution
Invoke-SafeCommand "git status" -WorkingDirectory $ProjectPath

Configuration¶

Environment Variables¶

Ralph uses ~/.ralph.env for configuration. On Windows:

WSL: ~/.ralph.env = /home/username/.ralph.env
Git Bash: ~/.ralph.env = C:\Users\Username\.ralph.env
PowerShell: ~/.ralph.env = C:\Users\Username\.ralph.env

Creating Configuration¶

# Run setup wizard
ralph notify setup

# Or create manually
cat > ~/.ralph.env << 'EOF'
# Ralph Configuration
export RALPH_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
export RALPH_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
export RALPH_AUTO_COMMIT="true"
EOF

chmod 600 ~/.ralph.env

Loading Configuration¶

WSL/Git Bash:

echo 'source ~/.ralph.env' >> ~/.bashrc
source ~/.bashrc

PowerShell (Enhanced):

# Import compatibility utilities
. "$HOME\ralph\lib\compat-utils.ps1"

# Load Ralph configuration
$config = Get-RalphConfig

# Access configuration values
Write-Host "Slack webhook: $($config.RALPH_SLACK_WEBHOOK_URL)"

# Or convert to environment variables:
Get-Content $HOME\.ralph.env | ForEach-Object {
    if ($_ -match '^export\s+([^=]+)="([^"]*)"') {
        [Environment]::SetEnvironmentVariable($matches[1], $matches[2], "User")
    }
}

# Using the new config command (PowerShell support)
ralph config commit on    # Enable auto-commit
ralph config commit off   # Disable auto-commit
ralph config commit status # Check status

Cross-Platform Path Handling¶

Ralph's PowerShell utilities handle path conversions automatically:

# Import utilities
. "$HOME\ralph\lib\compat-utils.ps1"

# Windows to Unix path (for WSL)
$unixPath = Get-UnixPath "C:\Users\name\project\plan.md"
# Result: /mnt/c/Users/name/project/plan.md

# Unix to Windows path
$winPath = Get-WindowsPath "/mnt/c/Users/name/project"
# Result: C:\Users\name\project

# Normalize path for current platform
$normalized = Normalize-RalphPath "C:\Users\name\project"
# On Windows: C:\Users\name\project
# On WSL: /mnt/c/Users/name/project

PowerShell Config Command¶

The config command now works in PowerShell:

# Check auto-commit status
ralph config commit status

# Enable auto-commit
ralph config commit on

# Disable auto-commit
ralph config commit off

# View all configuration
ralph config show

New PowerShell Features¶

Platform Detection¶

# Import utilities
. "$HOME\ralph\lib\compat-utils.ps1"

# Detect platform
$platform = Get-RalphPlatform
# Returns: "Windows", "WSL", "Linux", "macOS"

# Check if running in WSL
if (Test-IsWSL) {
    Write-Host "Running in WSL environment"
}

Process Management¶

# Check if Ralph is running
$isRunning = Test-RalphProcess
if ($isRunning) {
    Write-Host "Ralph is currently running"
}

# Start Ralph in background
Start-RalphBackground -PlanFile "plan.md" -MaxIterations 20

# Stop Ralph process
Stop-RalphProcess -Graceful

Dependency Checking¶

# Verify all dependencies
if (Test-RalphDependencies -Verbose) {
    Write-Host "All dependencies satisfied"
} else {
    Write-Host "Missing dependencies - run setup"
}

# Check specific dependency
if (Test-CommandExists "git") {
    Write-Host "Git is installed"
}

Configuration Management¶

# Get configuration value
$webhookUrl = Get-RalphConfigValue "RALPH_SLACK_WEBHOOK_URL"

# Set configuration value
Set-RalphConfigValue "RALPH_AUTO_COMMIT" "true"

# Validate configuration
if (Test-RalphConfig) {
    Write-Host "Configuration is valid"
}

Common Windows-Specific Issues¶

Issue 1: Line Ending Errors¶

Symptoms:

bash: '\r': command not found

Cause: Windows CRLF line endings in bash scripts.

Solution:

# Convert all scripts to Unix line endings
cd ~/ralph
find . -name "*.sh" -exec sed -i 's/\r$//' {} \;

# Or use dos2unix
find . -name "*.sh" -exec dos2unix {} \;

# Prevent future issues
git config --global core.autocrlf input

Issue 2: Permission Denied¶

Symptoms:

Permission denied: ~/ralph/ralph.sh

Solution:

# Make scripts executable
chmod +x ~/ralph/*.sh

# Verify permissions
ls -la ~/ralph/*.sh

Issue 3: Path Issues¶

Symptoms:

Error: Plan file not found: C:\Users\...\plan.md

Cause: Mixing Windows and Unix paths.

Solution:

# Use Unix-style paths in WSL/Git Bash
ralph ./plan.md              # Good
ralph /c/Users/me/plan.md   # Good (Git Bash)
ralph C:\Users\me\plan.md   # Bad - don't use Windows paths

# In WSL, convert paths:
cd /mnt/c/Users/YourName/Projects
ralph ./plan.md

Issue 4: Claude CLI Not Found¶

Symptoms:

claude: command not found

Solution:

# Verify Claude is installed
which claude

# If not found, check PATH
echo $PATH

# Add Claude to PATH (adjust path as needed)
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Issue 5: Antivirus Blocking¶

Symptoms: Scripts hang or fail with access denied.

Cause: Windows Defender or antivirus blocking bash scripts.

Solution:

Add exclusion for ~/ralph directory:
Open Windows Security
Virus & threat protection
Manage settings
Add exclusion → Folder
Select C:\Users\YourName\ralph or WSL path
Or temporarily disable real-time protection (not recommended)

Issue 6: Unicode/Encoding Issues¶

Symptoms:

Invalid character in file

Solution:

# Set UTF-8 encoding
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Add to ~/.bashrc
echo 'export LANG=en_US.UTF-8' >> ~/.bashrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.bashrc

PowerShell:

# Set UTF-8 encoding for PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8

# Add to PowerShell profile
Add-Content $PROFILE @"
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8
"@

Issue 7: PowerShell Execution Policy¶

Symptoms:

cannot be loaded because running scripts is disabled on this system

Solution:

# Check current policy
Get-ExecutionPolicy

# Set policy for current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Verify
Get-ExecutionPolicy -List

Issue 8: Git Bash vs PowerShell Path Differences¶

Symptoms: Paths work in Git Bash but not PowerShell or vice versa.

Solution:

# Use the compatibility utilities
. "$HOME\ralph\lib\compat-utils.ps1"

# Normalize paths for current environment
$normalizedPath = Normalize-RalphPath $yourPath

# Or convert explicitly
$unixPath = Get-UnixPath "C:\Users\name\project"
$winPath = Get-WindowsPath "/mnt/c/Users/name/project"

Windows Terminal Setup¶

For the best experience, use Windows Terminal.

Install Windows Terminal¶

# Install from Microsoft Store
# Or via winget:
winget install Microsoft.WindowsTerminal

Configure for WSL¶

Open Windows Terminal
Click ▼ (dropdown) → Settings
Add new profile:

{
    "guid": "{YOUR-GUID}",
    "name": "Ralph (WSL)",
    "commandline": "wsl.exe ~",
    "hidden": false,
    "startingDirectory": "\\\\wsl$\\Ubuntu\\home\\yourusername",
    "colorScheme": "One Half Dark"
}

Configure for Git Bash¶

{
    "guid": "{YOUR-GUID}",
    "name": "Ralph (Git Bash)",
    "commandline": "C:\\Program Files\\Git\\bin\\bash.exe -i -l",
    "icon": "C:\\Program Files\\Git\\mingw64\\share\\git\\git-for-windows.ico",
    "startingDirectory": "%USERPROFILE%"
}

VS Code Integration¶

Install VS Code Extensions¶

WSL Extension - Work with WSL projects
GitLens - Git integration
Remote - SSH - Remote development

Open WSL Projects¶

# In WSL terminal
cd /mnt/c/Users/YourName/Projects/myproject
code .

VS Code will: - Open in Windows - Access files via WSL - Run terminals in WSL - Use WSL for git operations

Configure Terminal¶

Add to .vscode/settings.json:

{
    "terminal.integrated.defaultProfile.windows": "Git Bash",
    "terminal.integrated.profiles.windows": {
        "Git Bash": {
            "path": "C:\\Program Files\\Git\\bin\\bash.exe",
            "args": ["-i", "-l"]
        }
    }
}

Performance Optimization¶

WSL2 Performance¶

Store files in WSL filesystem:

# Fast
cd ~/projects
ralph ./plan.md

# Slow (crosses filesystem boundary)
cd /mnt/c/Users/me/projects
ralph ./plan.md

Increase WSL memory:

Create C:\Users\YourName\.wslconfig:

[wsl2]
memory=8GB
processors=4

Disable Windows Defender for WSL:

Add-MpPreference -ExclusionProcess wsl.exe

Git Bash Performance¶

Disable antivirus for Git directory:
Add C:\Program Files\Git to exclusions
Use SSD for repositories:
Store projects on SSD, not HDD

Troubleshooting Windows Issues¶

Enable Bash Debugging¶

# Add to top of ralph.sh temporarily
set -x  # Print commands
set -v  # Print input lines

# Run Ralph
ralph ./plan.md plan 2>&1 | tee debug.log

Check File Permissions¶

# List permissions
ls -la ~/ralph

# Fix if needed
chmod -R u+rwx ~/ralph

Verify Dependencies¶

# Check all required tools
command -v git && echo "Git: OK" || echo "Git: MISSING"
command -v claude && echo "Claude: OK" || echo "Claude: MISSING"
command -v curl && echo "curl: OK" || echo "curl: MISSING"
command -v jq && echo "jq: OK" || echo "jq: MISSING (optional)"

Network Issues¶

# Test connectivity
curl -I https://api.github.com

# If behind proxy
export http_proxy="http://proxy.company.com:8080"
export https_proxy="http://proxy.company.com:8080"

Migration from Linux/Mac¶

Transferring Configuration¶

From Linux/Mac:

# Copy config
scp ~/.ralph.env windows-machine:/mnt/c/Users/YourName/

On Windows (WSL):

cp /mnt/c/Users/YourName/.ralph.env ~/.ralph.env
chmod 600 ~/.ralph.env

Path Translation¶

Linux/Mac	Windows (WSL)	Windows (Git Bash)
`/home/user/project`	`/home/user/project`	`/c/Users/user/project`
`~/ralph`	`~/ralph`	`~/ralph`
`/tmp`	`/tmp`	`/tmp` (temporary)

Docker Alternative¶

If native installation is problematic, use Docker:

Install Docker Desktop¶

Download from docker.com
Enable WSL2 backend
Start Docker Desktop

Create Dockerfile¶

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    curl \
    git \
    ca-certificates

# Install Claude CLI
RUN curl -fsSL https://claude.ai/download/cli/install.sh | bash

# Install Ralph
RUN curl -fsSL https://raw.githubusercontent.com/aaron777collins/portableralph/master/install.sh | bash -s -- --headless

# Set up environment
ENV PATH="/root/ralph:${PATH}"

WORKDIR /workspace

ENTRYPOINT ["/root/ralph/ralph.sh"]

Build and Use¶

# Build image
docker build -t ralph .

# Run Ralph
docker run -v ${PWD}:/workspace ralph plan.md

# With environment variables
docker run -v ${PWD}:/workspace `
    -e RALPH_SLACK_WEBHOOK_URL="https://..." `
    ralph plan.md build 20

Best Practices for Windows¶

Use WSL2 when possible - Best compatibility
Store repos in WSL filesystem - Better performance
Use Windows Terminal - Better experience
Keep Git Bash updated - Latest features
Configure line endings - Prevent issues
Use environment variables - Not hardcoded paths
Regular updates - Keep Ralph updated
Use PowerShell compatibility utilities - For cross-platform scripts
Normalize paths - Use Get-UnixPath/Get-WindowsPath helpers
Test in both environments - Verify Git Bash and PowerShell compatibility

Getting Help¶

Windows-Specific Resources¶

WSL Documentation: docs.microsoft.com/wsl
Git for Windows: gitforwindows.org
Windows Terminal: github.com/microsoft/terminal

Community Support¶

GitHub Issues: Tag with windows label
Discord: #windows channel (if available)

Reporting Windows Issues¶

Include in issue reports:

# System info
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"

# WSL version (if applicable)
wsl --version

# Git Bash version
bash --version

# Ralph version
ralph --version

Windows Installation Guide¶

Prerequisites¶

Required Software¶

Optional But Recommended¶

Installation Methods¶

Method 1: WSL2 (Recommended)¶

Step 1: Install WSL2¶

Step 2: Install Ralph in WSL¶

Step 3: Access Windows Files¶

Method 2: Git Bash (Native Windows)¶

Step 1: Install Git for Windows¶

Step 2: Install Ralph¶

Step 3: Handle Line Endings¶

Method 3: PowerShell (Enhanced Support)¶

Step 1: Enable Linux-like Commands¶

Step 2: Install Ralph¶

Step 3: Add to PATH¶

Step 4: PowerShell Compatibility Utilities¶

Configuration¶

Environment Variables¶

Creating Configuration¶

Loading Configuration¶

Cross-Platform Path Handling¶

PowerShell Config Command¶

New PowerShell Features¶

Platform Detection¶

Process Management¶

Dependency Checking¶

Configuration Management¶

Common Windows-Specific Issues¶

Issue 1: Line Ending Errors¶

Issue 2: Permission Denied¶

Issue 3: Path Issues¶

Issue 4: Claude CLI Not Found¶

Issue 5: Antivirus Blocking¶

Issue 6: Unicode/Encoding Issues¶

Issue 7: PowerShell Execution Policy¶

Issue 8: Git Bash vs PowerShell Path Differences¶

Windows Terminal Setup¶

Install Windows Terminal¶

Configure for WSL¶

Configure for Git Bash¶

VS Code Integration¶

Install VS Code Extensions¶

Open WSL Projects¶

Configure Terminal¶

Performance Optimization¶

WSL2 Performance¶

Git Bash Performance¶

Troubleshooting Windows Issues¶

Enable Bash Debugging¶

Check File Permissions¶

Verify Dependencies¶

Network Issues¶

Migration from Linux/Mac¶

Transferring Configuration¶

Path Translation¶

Docker Alternative¶

Install Docker Desktop¶

Create Dockerfile¶

Build and Use¶

Best Practices for Windows¶

Getting Help¶

Windows-Specific Resources¶

Community Support¶

Reporting Windows Issues¶

See Also¶