its-consulting/ralph-claude-code
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Compare commits

base: its-consulting:claude/windows-compatibility-EwHYT
Branches Tags
its-consulting:main
its-consulting:claude/windows-compatibility-EwHYT
..
compare: its-consulting:main
Branches Tags
its-consulting:claude/windows-compatibility-EwHYT
its-consulting:main

No commits in common. "claude/windows-compatibility-EwHYT" and "main" have entirely different histories.
claude/win ... main

13 changed files with 0 additions and 543 deletions
Download patch file Download diff file Expand all files Collapse all files

34
.dockerignore
View file

@ -1,34 +0,0 @@
# 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

21
.gitattributes vendored
View file

@ -1,21 +0,0 @@
# 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

51
.github/workflows/docker.yml vendored
View file

@ -1,51 +0,0 @@
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'

3
.gitignore vendored
View file

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

29
CLAUDE.md
View file

@ -330,34 +330,6 @@ 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:
@ -366,7 +338,6 @@ 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

46
Dockerfile
View file

@ -1,46 +0,0 @@
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"]

30
README.md
View file

@ -248,36 +248,6 @@ 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:

21
docker-compose.yml
View file

@ -1,21 +0,0 @@
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"]

26
docker/docker-entrypoint.sh
View file

@ -1,26 +0,0 @@
#!/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 "$@"

45
docker/ralph-docker
View file

@ -1,45 +0,0 @@
#!/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 "$@"

40
docker/ralph-docker.ps1
View file

@ -1,40 +0,0 @@
# 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

194
docs/user-guide/04-docker-setup.md
View file

@ -1,194 +0,0 @@
# Docker Setup (Windows & Cross-Platform)
Ralph runs natively on Linux and macOS. For **Windows** users (or anyone who prefers containerized execution), Ralph can run inside a Docker container with full functionality.
## Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows/macOS) or Docker Engine (Linux)
- Windows users: Docker Desktop must use the **WSL 2 backend** (default on modern installations)
- **Docker Desktop must be running** before executing any `docker` commands. Look for the Docker whale icon in your system tray (Windows) or menu bar (macOS).
- Your `ANTHROPIC_API_KEY`
## Quick Start
### 1. Build the image
From the Ralph repository root:
```bash
docker build -t ralph-claude-code .
```
### 2. Run Ralph in your project
```bash
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
cd C:\path\to\your-project
docker run -it --rm `
-e ANTHROPIC_API_KEY="$env:ANTHROPIC_API_KEY" `
-v "${PWD}:/workspace" `
ralph-claude-code `
ralph --monitor
```
## Using Docker Compose
The repository includes a `docker-compose.yml` for convenience:
```bash
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
# Run Ralph
docker compose run --rm ralph ralph --monitor
```
To customize, edit `docker-compose.yml`. Uncomment the volume mounts for git config and SSH keys if you need git push from inside the container:
```yaml
volumes:
- ./:/workspace
- ~/.gitconfig:/home/ralph/.gitconfig:ro
- ~/.ssh:/home/ralph/.ssh:ro
```
## Convenience Wrapper Scripts
The `docker/` directory contains wrapper scripts that handle volume mounts, UID mapping, and API key forwarding automatically:
**Linux/macOS/WSL:**
```bash
./docker/ralph-docker --monitor
./docker/ralph-docker --live --verbose
```
**Windows PowerShell:**
```powershell
.\docker\ralph-docker.ps1 --monitor
.\docker\ralph-docker.ps1 --live --verbose
```
## File Permissions (UID/GID Mapping)
When Docker mounts your project directory, files created inside the container need to have the correct ownership on the host. The container supports `RALPH_UID` and `RALPH_GID` environment variables:
```bash
docker run -it --rm \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
-e RALPH_UID="$(id -u)" \
-e RALPH_GID="$(id -g)" \
-v "$(pwd):/workspace" \
ralph-claude-code \
ralph --monitor
```
The wrapper scripts (`docker/ralph-docker`) set these automatically.
## Git Integration
To enable git commits and pushes from inside the container, mount your git configuration:
```bash
docker run -it --rm \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
-v "$(pwd):/workspace" \
-v "$HOME/.gitconfig:/home/ralph/.gitconfig:ro" \
-v "$HOME/.ssh:/home/ralph/.ssh:ro" \
ralph-claude-code \
ralph --monitor
```
## Running Tests Inside Docker
```bash
# Run all tests
docker run --rm ralph-claude-code bash -c 'cd /opt/ralph-claude-code && npm test'
# Run specific test suite
docker run --rm ralph-claude-code bash -c 'cd /opt/ralph-claude-code && npm run test:unit'
```
## Windows-Specific Notes
### Line Endings
The repository includes a `.gitattributes` file that forces LF line endings for all shell scripts. This prevents Windows' CRLF line endings from corrupting bash scripts. If you clone the repository on Windows, this is handled automatically.
If you encounter `\r` errors when running scripts, ensure `.gitattributes` is respected:
```bash
git config core.autocrlf input
git rm --cached -r .
git reset --hard
```
### Volume Mount Performance
For best performance on Windows, store your projects in the WSL 2 filesystem rather than the Windows filesystem:
```
# Faster (WSL filesystem)
\\wsl$\Ubuntu\home\user\my-project
# Slower (Windows filesystem mounted in WSL)
/mnt/c/Users/user/my-project
```
### PowerShell Environment Variables
```powershell
# Set API key for current session
$env:ANTHROPIC_API_KEY = "sk-ant-..."
# Or persist across sessions
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")
```
## Troubleshooting
### "error during connect: docker daemon is not running"
Docker Desktop is not started. On Windows, launch Docker Desktop from the Start menu and wait until the whale icon in the system tray shows "Docker Desktop is running". On macOS, launch it from Applications. On Linux, start the daemon with `sudo systemctl start docker`.
### "ANTHROPIC_API_KEY is not set"
The container warns if no API key is provided. Pass it with `-e ANTHROPIC_API_KEY=...`.
### Permission denied on mounted files
Set `RALPH_UID` and `RALPH_GID` to match your host user (see File Permissions section above).
### tmux not working
Ensure you run the container with `-it` flags (interactive + TTY). Without TTY, tmux cannot create sessions. Use `ralph` without `--monitor` in non-interactive environments.
### Container can't access the network
Docker Desktop may need network access enabled. Check Docker Desktop settings and firewall rules.
## What's in the Container
The Docker image includes all Ralph dependencies:
| Component | Version |
|-----------|---------|
| Debian | bookworm-slim |
| Bash | 5.2+ |
| Node.js | 20 LTS |
| jq | Latest |
| Git | Latest |
| tmux | Latest |
| GNU coreutils | Latest |
| Claude Code CLI | Latest |

3
docs/user-guide/README.md
View file

@ -13,9 +13,6 @@ Learn which files Ralph creates, which ones you should customize, and how they w
### [Writing Effective Requirements](03-writing-requirements.md)
Best practices for writing PROMPT.md, when to use specs/, and how fix_plan.md evolves during development. Includes good and bad examples.
### [Docker Setup (Windows & Cross-Platform)](04-docker-setup.md)
Run Ralph inside a Docker container on Windows, Linux, or macOS. Includes Docker Compose setup, file permissions, git integration, and troubleshooting.
## Example Projects
Check out the [examples/](../../examples/) directory for complete, realistic project configurations: