fix(ralph-loop): add cross-platform support using Node.js launcher

[neilmcguire]

Summary

Adds true cross-platform support for the ralph-loop plugin by introducing Node.js launchers that detect the platform at runtime and invoke the appropriate native script (PowerShell on Windows, Bash on Unix/macOS).

Problem

The current ralph-loop plugin only works on Unix/macOS systems. Windows users cannot use the plugin because:

1. Windows cannot directly execute .sh files
2. The hook and setup commands are passed to the OS which doesn't know how to handle bash scripts

There are currently 4 open PRs attempting to fix this (#89, #99, #124, #127), but each has limitations.

Why This Approach is Superior

Comparison with Existing PRs

Approach	Windows Native	Unix Works	Zero Dependencies	Single Config
PR #89 (prefix bash)	No (requires Git Bash)	Yes	No	Yes
PR #99 (PowerShell only)	Yes	BREAKS	Yes	No
This PR (Node.js launcher)	Yes	Yes	Yes	Yes

Why Node.js?

1. Zero additional dependencies - Claude Code is a Node.js application. Every user who can run Claude Code already has Node.js installed. Unlike PR fix(ralph-wiggum): Add Windows compatibility for stop hook #89 which requires Git Bash/WSL, this works out of the box.

2. Doesn't break Unix - PR feat(ralph-wiggum): Add Windows PowerShell support #99 changes hooks.json to call PowerShell directly, which breaks Unix/macOS entirely. Our approach keeps the existing bash scripts working.

3. Better than Python - Other official plugins (hookify, security-guidance) use python3 for cross-platform hooks, but Python is not guaranteed on Windows. Node.js is guaranteed because Claude Code requires it.

4. Single configuration - One hooks.json and one command file works on all platforms. No need for platform-specific plugin versions.

5. Native execution - Windows users get native PowerShell (fast, full Windows API access). Unix users get native bash (no changes to existing behavior).

Architecture

hooks/
├── hooks.json                  (calls Node.js launcher)
├── stop-hook-launcher.js       (cross-platform router, ~50 lines)
├── stop-hook.ps1               (Windows native, ~190 lines)
└── stop-hook.sh                (Unix native, unchanged)

scripts/
├── setup-ralph-loop-launcher.js (cross-platform router, ~50 lines)
├── setup-ralph-loop.ps1         (Windows native, ~210 lines)
└── setup-ralph-loop.sh          (Unix native, unchanged)

The launchers are minimal and simply detect os.platform() then spawn the appropriate script.

Changes

File	Change
hooks/hooks.json	Updated command to use Node.js launcher
hooks/stop-hook-launcher.js	New - Cross-platform launcher
hooks/stop-hook.ps1	New - Windows PowerShell implementation
commands/ralph-loop.md	Updated command to use Node.js launcher
scripts/setup-ralph-loop-launcher.js	New - Cross-platform launcher
scripts/setup-ralph-loop.ps1	New - Windows PowerShell implementation

Testing

Tested on Windows 11 with PowerShell 5.1 using this test command:

/ralph-loop:ralph-loop "Append the current iteration number to test-iterations.txt. Read the file first, then append the next number. Output <promise>DONE</promise> when it contains 1 through 5." --max-iterations 5 --completion-promise "DONE"

Results:

• Iteration 1: Created file, added "1"
• Iteration 2: Stop hook intercepted exit, appended "2"
• Iteration 3: Stop hook intercepted exit, appended "3"
• Iteration 4: Stop hook intercepted exit, appended "4"
• Iteration 5: Stop hook intercepted exit, appended "5", detected <promise>DONE</promise>, loop completed

Final file contents:

1
2
3
4
5

Test Case	Result
Loop activation (/ralph-loop)	Pass
State file creation	Pass
Stop hook intercepts exit	Pass
Prompt fed back correctly	Pass
Iteration counter updates	Pass
Max iterations limit	Pass
Completion promise detection	Pass
CRLF/LF line ending handling	Pass

Compatibility

• Windows 10/11 with PowerShell 5.1+
• macOS (unchanged behavior)
• Linux (unchanged behavior)

Security

• No use of Invoke-Expression or eval
• Proper JSON escaping via ConvertTo-Json
• -ExecutionPolicy Bypass only for the specific script, not system-wide
• No command injection vulnerabilities

[github-actions]

Thanks for your interest! This repo only accepts contributions from Anthropic team members. If you'd like to submit a plugin to the marketplace, please submit your plugin here.

[reisen7]

perfect fix，ty ！！！