Add Docker support for Windows and cross-platform execution

.dockerignore

@@ -0,0 +1,34 @@
+# Git
+.git
+
+# Node modules
+node_modules/
+
+# Ralph state files (rebuilt at runtime)
+.ralph/.call_count
+.ralph/.last_reset
+.ralph/.exit_signals
+.ralph/.response_analysis
+.ralph/.circuit_breaker_state
+.ralph/.circuit_breaker_history
+.ralph/.json_parse_result
+.ralph/.last_output_length
+.ralph/.ralph_session
+.ralph/.ralph_session_history
+.ralph/.claude_session_id
+.ralph/status.json
+.ralph/logs/
+
+# Coverage and test artifacts
+coverage/
+*.log
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo

.gitattributes

@@ -0,0 +1,21 @@
+# Force LF line endings for all shell scripts and test files
+# Prevents Windows CRLF corruption of bash scripts
+*.sh text eol=lf
+*.bats text eol=lf
+*.bash text eol=lf
+
+# Docker files
+Dockerfile text eol=lf
+docker-compose.yml text eol=lf
+docker-entrypoint.sh text eol=lf
+
+# Keep markdown and other text files as auto
+*.md text
+*.yml text
+*.yaml text
+*.json text
+
+# Binary files
+*.png binary
+*.jpg binary
+*.gif binary

.github/workflows/docker.yml

@@ -0,0 +1,51 @@
+name: Docker Build
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'Dockerfile'
+      - 'docker/**'
+      - '.dockerignore'
+      - 'install.sh'
+      - 'lib/**'
+      - 'ralph_loop.sh'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'Dockerfile'
+      - 'docker/**'
+      - '.dockerignore'
+      - 'install.sh'
+      - 'lib/**'
+      - 'ralph_loop.sh'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Build Docker image
+      run: docker build -t ralph-claude-code:test .
+
+    - name: Verify Ralph is installed
+      run: docker run --rm ralph-claude-code:test ralph --help
+
+    - name: Verify dependencies
+      run: |
+        docker run --rm ralph-claude-code:test bash -c '
+          echo "=== Checking dependencies ==="
+          bash --version | head -1
+          node --version
+          npm --version
+          jq --version
+          git --version
+          tmux -V
+          timeout --version | head -1
+          echo "=== All dependencies OK ==="
+        '
+
+    - name: Run tests inside Docker
+      run: docker run --rm ralph-claude-code:test bash -c 'cd /opt/ralph-claude-code && npm test'

.gitignore

@@ -45,6 +45,9 @@ target/
 *.swp
 *.swo
 
+# Docker
+docker/tmp/
+
 # Claude Code local settings
 .claude/settings.local.json
 

CLAUDE.md

@@ -330,6 +330,34 @@ After installation, the following global commands are available:
 - `ralph-enable` - Interactive wizard to enable Ralph in existing projects
 - `ralph-enable-ci` - Non-interactive version for CI/automation
 
+## Docker Support
+
+Ralph can run inside a Docker container for Windows users or containerized workflows.
+
+### Docker Files
+- **`Dockerfile`** - Debian slim image with all Ralph dependencies (bash, jq, git, tmux, Node.js 20, Claude Code CLI)
+- **`docker-compose.yml`** - Compose configuration with volume mounts and API key passthrough
+- **`docker/docker-entrypoint.sh`** - Entrypoint handling UID/GID remapping and git safe.directory
+- **`docker/ralph-docker`** - Bash convenience wrapper for `docker run`
+- **`docker/ralph-docker.ps1`** - PowerShell convenience wrapper for Windows
+- **`.dockerignore`** - Build context exclusions
+- **`.gitattributes`** - Forces LF line endings for shell scripts (prevents Windows CRLF corruption)
+
+### Docker Commands
+```bash
+# Build image
+docker build -t ralph-claude-code .
+
+# Run Ralph
+docker run -it --rm -e ANTHROPIC_API_KEY="$KEY" -v "$(pwd):/workspace" ralph-claude-code ralph --monitor
+
+# Run tests inside container
+docker run --rm ralph-claude-code bash -c 'cd /opt/ralph-claude-code && npm test'
+```
+
+### CI Workflow
+`.github/workflows/docker.yml` verifies the Docker image builds and all tests pass inside the container.
+
 ## Integration Points
 
 Ralph integrates with:
@@ -338,6 +366,7 @@ Ralph integrates with:
 - **Git**: Expects projects to be git repositories
 - **jq**: For JSON processing of status and exit signals
 - **GitHub Actions**: CI/CD pipeline for automated testing
+- **Docker**: Container-based execution for Windows and cross-platform support
 - **Standard Unix tools**: bash, grep, date, etc.
 
 ## Exit Conditions and Thresholds

Dockerfile

@@ -0,0 +1,46 @@
+FROM debian:bookworm-slim
+
+# System dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    bash \
+    jq \
+    git \
+    tmux \
+    coreutils \
+    curl \
+    ca-certificates \
+    gosu \
+    procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 20 LTS
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Claude Code CLI globally
+RUN npm install -g @anthropic-ai/claude-code
+
+# Create ralph user
+RUN groupadd -g 1000 ralph \
+    && useradd -m -u 1000 -g ralph -s /bin/bash ralph
+
+# Copy Ralph source
+COPY . /opt/ralph-claude-code/
+
+# Install Ralph as the ralph user
+USER ralph
+RUN cd /opt/ralph-claude-code && bash install.sh
+ENV PATH="/home/ralph/.local/bin:${PATH}"
+
+# Switch back to root for entrypoint (handles UID remapping)
+USER root
+
+# Copy entrypoint
+COPY docker/docker-entrypoint.sh /usr/local/bin/
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+WORKDIR /workspace
+
+ENTRYPOINT ["docker-entrypoint.sh"]
+CMD ["ralph", "--help"]

README.md

@@ -248,6 +248,36 @@ To completely remove Ralph from your system:
 curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash
 ```
 
+## Docker Setup (Windows & Cross-Platform)
+
+Ralph can run inside a Docker container, which is the recommended approach for **Windows** users. It also works on Linux and macOS.
+
+```bash
+# 1. Build the image (one time)
+docker build -t ralph-claude-code .
+
+# 2. Run Ralph in your project
+cd /path/to/your-project
+docker run -it --rm \
+  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
+  -v "$(pwd):/workspace" \
+  ralph-claude-code \
+  ralph --monitor
+```
+
+**Windows PowerShell:**
+```powershell
+docker run -it --rm `
+  -e ANTHROPIC_API_KEY="$env:ANTHROPIC_API_KEY" `
+  -v "${PWD}:/workspace" `
+  ralph-claude-code `
+  ralph --monitor
+```
+
+Convenience wrapper scripts are available in `docker/` (bash and PowerShell).
+
+> See [Docker Setup Guide](docs/user-guide/04-docker-setup.md) for full documentation including Docker Compose, file permissions, git integration, and troubleshooting.
+
 ## Understanding Ralph Files
 
 After running `ralph-enable` or `ralph-import`, you'll have a `.ralph/` directory with several files. Here's what each file does and whether you need to edit it:

docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  ralph:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: ralph-claude-code:latest
+    container_name: ralph
+    stdin_open: true
+    tty: true
+    working_dir: /workspace
+    environment:
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - RALPH_UID=${RALPH_UID:-1000}
+      - RALPH_GID=${RALPH_GID:-1000}
+    volumes:
+      - ./:/workspace
+      # Optional: mount git config for commits
+      # - ~/.gitconfig:/home/ralph/.gitconfig:ro
+      # Optional: mount SSH keys for git push
+      # - ~/.ssh:/home/ralph/.ssh:ro
+    command: ["ralph", "--help"]

docker/docker-entrypoint.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+
+# Default UID/GID matching typical Linux/macOS user
+RALPH_UID=${RALPH_UID:-1000}
+RALPH_GID=${RALPH_GID:-1000}
+
+# Remap ralph user UID/GID to match host user (avoids file permission issues on bind mounts)
+if [ "$(id -u ralph)" != "$RALPH_UID" ] || [ "$(id -g ralph)" != "$RALPH_GID" ]; then
+    groupmod -g "$RALPH_GID" ralph 2>/dev/null || true
+    usermod -u "$RALPH_UID" -g "$RALPH_GID" -d /home/ralph ralph 2>/dev/null || true
+    chown -R ralph:ralph /home/ralph 2>/dev/null || true
+fi
+
+# Git safe.directory for mounted workspace
+gosu ralph git config --global --add safe.directory /workspace 2>/dev/null || true
+
+# Warn if API key is missing
+if [ -z "$ANTHROPIC_API_KEY" ]; then
+    echo "WARNING: ANTHROPIC_API_KEY is not set. Ralph will not be able to call Claude."
+    echo "Set it with: docker run -e ANTHROPIC_API_KEY=your-key ..."
+    echo ""
+fi
+
+# Execute command as ralph user
+exec gosu ralph "$@"

docker/ralph-docker

@@ -0,0 +1,45 @@
+#!/bin/bash
+# ralph-docker - Convenience wrapper for running Ralph in Docker
+#
+# Usage:
+#   ./docker/ralph-docker [ralph-options]
+#
+# Examples:
+#   ./docker/ralph-docker --help
+#   ./docker/ralph-docker --monitor
+#   ./docker/ralph-docker --live --verbose
+#
+# Environment:
+#   ANTHROPIC_API_KEY  Required. Your Anthropic API key.
+#   RALPH_IMAGE        Optional. Docker image name (default: ralph-claude-code:latest)
+
+set -e
+
+IMAGE_NAME="${RALPH_IMAGE:-ralph-claude-code:latest}"
+
+if [ -z "$ANTHROPIC_API_KEY" ]; then
+    echo "Error: ANTHROPIC_API_KEY environment variable is not set."
+    echo "Export it first: export ANTHROPIC_API_KEY=sk-ant-..."
+    exit 1
+fi
+
+EXTRA_VOLUMES=()
+
+# Mount git config if available
+if [ -f "$HOME/.gitconfig" ]; then
+    EXTRA_VOLUMES+=(-v "$HOME/.gitconfig:/home/ralph/.gitconfig:ro")
+fi
+
+# Mount SSH keys if available
+if [ -d "$HOME/.ssh" ]; then
+    EXTRA_VOLUMES+=(-v "$HOME/.ssh:/home/ralph/.ssh:ro")
+fi
+
+docker run -it --rm \
+    -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
+    -e RALPH_UID="$(id -u)" \
+    -e RALPH_GID="$(id -g)" \
+    -v "$(pwd):/workspace" \
+    "${EXTRA_VOLUMES[@]}" \
+    "$IMAGE_NAME" \
+    ralph "$@"

docker/ralph-docker.ps1

@@ -0,0 +1,40 @@
+# ralph-docker.ps1 - Convenience wrapper for running Ralph in Docker on Windows
+#
+# Usage:
+#   .\docker\ralph-docker.ps1 [ralph-options]
+#
+# Examples:
+#   .\docker\ralph-docker.ps1 --help
+#   .\docker\ralph-docker.ps1 --monitor
+#   .\docker\ralph-docker.ps1 --live --verbose
+#
+# Environment:
+#   ANTHROPIC_API_KEY  Required. Your Anthropic API key.
+#   RALPH_IMAGE        Optional. Docker image name (default: ralph-claude-code:latest)
+
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$RalphArgs
+)
+
+$ImageName = if ($env:RALPH_IMAGE) { $env:RALPH_IMAGE } else { "ralph-claude-code:latest" }
+
+if (-not $env:ANTHROPIC_API_KEY) {
+    Write-Error "ANTHROPIC_API_KEY environment variable is not set."
+    Write-Host 'Set it first: $env:ANTHROPIC_API_KEY = "sk-ant-..."'
+    exit 1
+}
+
+$DockerArgs = @(
+    "run", "-it", "--rm",
+    "-e", "ANTHROPIC_API_KEY=$env:ANTHROPIC_API_KEY",
+    "-v", "${PWD}:/workspace",
+    $ImageName,
+    "ralph"
+)
+
+if ($RalphArgs) {
+    $DockerArgs += $RalphArgs
+}
+
+& docker @DockerArgs