ralph-loop plugin: Windows compatibility issue - stop-hook.sh cannot execute

[bkerf]

Bug Description

The ralph-loop plugin fails on Windows because its stop hook is a bash script (.sh) that cannot execute natively on Windows.

Environment

• OS: Windows 10/11
• Claude Code Version: Latest
• Plugin: ralph-loop@claude-plugins-official

Problem

When a Claude Code session ends, the plugin's Stop hook is triggered automatically:

File: plugins/cache/claude-plugins-official/ralph-loop/.../hooks/hooks.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
          }
        ]
      }
    ]
  }
}

Since stop-hook.sh is a bash script, it cannot run on Windows without Git Bash, WSL, or similar tools installed. This causes errors or unexpected behavior when the session ends.

Expected Behavior

Official plugins should support cross-platform execution by:

1. Providing both .sh (Unix) and .ps1/.bat (Windows) versions of hooks
2. Or using a cross-platform scripting solution (e.g., Node.js scripts)

Suggested Fix

Add Windows-compatible hook scripts alongside the existing bash scripts:

• stop-hook.sh → for macOS/Linux
• stop-hook.ps1 or stop-hook.bat → for Windows

The hooks.json should conditionally use the appropriate script based on the platform.

Workaround

Users can disable the plugin in settings.json:

"ralph-loop@claude-plugins-official": false

Additional Context

This affects all Windows users who enable the ralph-loop plugin. The plugin is listed as an official Anthropic plugin, so cross-platform support should be expected.

[github-actions]

Found 2 possible duplicate issues:

1. Ralph Loop plugin: stop-hook.sh fails on Windows - cat command not found #16560
2. Ralph Loop plugin: stop-hook.sh fails on Windows - cat command not found #16559

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[longzhang83]

Complete Windows Fix for Ralph Loop Plugin

I've successfully fixed the Ralph Loop plugin on Windows 11. Here's the complete solution.

Environment

• OS: Windows 11
• • Terminal: Windows Terminal + PowerShell
• • • Git Bash: D:\Program Files\Git\usr\bin\bash.exe

Issues Encountered

1. VSCode opens .sh files instead of executing - Windows doesn't know how to execute .sh files
2. 2. cat: command not found - PATH doesn't include Git Bash's /usr/bin
3. 3. sed, grep, awk, jq, perl not found - Same PATH issue
4. 4. jq: command not found - jq is not installed by default
5. 5. File encoding issues - BOM causes #!/bin/bash to fail

Solution

Step 1: Install jq

Invoke-WebRequest -Uri "https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-windows-amd64.exe" -OutFile "C:\Program Files\Git\usr\bin\jq.exe"

Step 2: Modify hooks.json

Location: %USERPROFILE%\.claude\plugins\cache\claude-plugins-official\ralph-loop\<hash>\hooks.json

{
  "description": "Ralph Loop plugin stop hook for self-referential loops",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
           "command": "\"D:\\Program Files\\Git\\usr\\bin\\bash.exe\" ${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
          }
        ]
      }
    ]
  }
}

Step 3: Modify stop-hook.sh

Add these lines right after #!/bin/bash:

# Windows Git Bash compatibility
export PATH="/usr/bin:/bin:/mingw64/bin:$PATH"
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Also replace all rm "$RALPH_STATE_FILE" with rm -f "$RALPH_STATE_FILE".

Related Issues

• [BUG] Hook .sh scripts open in VSCode instead of executing on Windows Terminal/PowerShell #9758 - Hook .sh scripts open in VSCode
• • [Ralph Wiggum Plugin] Windows 11 Compatibility Fixes for Stop Hook #16377 - Windows 11 Compatibility Fixes
• • • Ralph Loop plugin: stop-hook.sh fails on Windows - cat command not found #16560 - cat command not found
      Hope this helps other Windows users! 🎉

[oinani0721]

For anyone encountering this issue, I've posted a complete Windows 11 fix in #9758 that addresses:

• PATH inheritance for Git Bash subprocess
• UTF-8 encoding for non-ASCII paths
• cygpath conversion for Windows paths
• Correct exit codes for continuation
• Plugin cache conflicts

See: #9758 (comment)

Related: #16377 #14817 #16560

[flyfoxai]

✅ Complete Windows Fix Available

Hi @bkerf and everyone following this issue,

I've created a comprehensive fix for the Windows compatibility issues with the Ralph Wiggum plugin. This addresses both the stop-hook execution problem and additional Windows-specific issues.

🔧 What's Fixed

Issue 1: Stop Hook Execution ✅

• Created native PowerShell version: hooks/stop-hook.ps1
• Updated hooks/hooks.json with platform-specific hooks
• Windows uses PowerShell, macOS/Linux use Bash
• No more popup windows or execution errors

Issue 2: Argument Parsing ✅

• Created PowerShell version: scripts/setup-ralph-loop.ps1
• Fixed "command not found" errors with command-line flags
• Native PowerShell parameter parsing
• Support for Chinese characters and special characters

📦 Repository & Installation

Repository: https://github.com/flyfoxai/ralph-wiggum-windows-fix

Quick Installation:

cd C:\Users\<YourUsername>\.claude\plugins\marketplaces\claude-code-plugins\plugins\
git clone https://github.com/flyfoxai/ralph-wiggum-windows-fix.git ralph-wiggum

Then restart Claude Code.

🧪 Testing & Verification

The fix has been thoroughly tested:

• ✅ 5 complete iterations of the Ralph loop
• ✅ 100% success rate across all tests
• ✅ 0 errors, 0 popup windows
• ✅ Edge cases tested: Long Chinese text, special characters, concurrent operations

Full test reports available in the repository:

• VERIFICATION-REPORT.md
• FINAL-REPORT.md
• WINDOWS-FIXES.md

🤝 Contributing Back

I'm happy to contribute these fixes back to the official repository. The changes are:

• Non-invasive (adds PowerShell scripts alongside existing Bash scripts)
• Platform-specific (doesn't affect macOS/Linux functionality)
• Well-tested and documented

Would the maintainers be open to a PR? I can prepare one if needed.

📋 Technical Details

Modified Files:

• hooks/hooks.json - Added platform detection
• hooks/stop-hook.ps1 - New PowerShell stop hook
• scripts/setup-ralph-loop.ps1 - New PowerShell setup script
• commands/ralph-loop.md - Updated to use PowerShell on Windows

Key Improvements:

• Native PowerShell execution (no Git Bash dependency)
• Proper UTF-8 encoding handling
• Robust argument parsing
• Platform-agnostic hook configuration

Let me know if you have any questions or need help with installation!

[flyfoxai]

✅ Update: All Windows Issues Now Fixed

I've just pushed the missing critical files that complete the Windows fix:

What Was Missing

My initial push was incomplete - it only included the argument parsing fix (setup-ralph-loop.ps1) but was missing the stop-hook fix (stop-hook.ps1).

Now Complete ✅

The repository now includes all necessary files:

1. ✅ hooks/stop-hook.ps1 - PowerShell stop hook (prevents VSCode popup)
2. ✅ hooks/hooks.json - Platform-specific hook configuration
3. ✅ scripts/setup-ralph-loop.ps1 - PowerShell setup script (argument parsing)
4. ✅ commands/ralph-loop.md - Updated command configuration

Verification Against Community Requirements

Based on the Windows issues reported by the community, here's the complete status:

Issue	Required	Status
Script opens in VSCode	❌ No	✅ Fixed
Hook executes silently	✅ Yes	✅ Fixed
ralph-loop iteration	✅ Works	✅ Fixed
Non-ASCII paths	✅ Correct	✅ Fixed
bash commands found	✅ All work	✅ Fixed

Installation

Same as before - just clone or pull the latest version:

cd C:\Users\<YourUsername>\.claude\plugins\marketplaces\claude-code-plugins\plugins\
git clone https://github.com/flyfoxai/ralph-wiggum-windows-fix.git ralph-wiggum
# Or if already cloned: cd ralph-wiggum && git pull

Then restart Claude Code.

Testing

The stop-hook.ps1 has been tested and verified to:

• ✅ Parse JSON input correctly
• ✅ Read and update state files
• ✅ Handle UTF-8 content
• ✅ Return proper JSON responses
• ✅ Execute silently without popups

Sorry for the confusion with the incomplete initial push. Everything is now complete and working!