Fix Windows/PowerShell invocation of superpowers-codex

[arittr]

Windows doesn't respect shebangs, so directly invoking the extensionless
superpowers-codex script triggers an "Open with" dialog. Prefix all
invocations with node (harmless on Unix, required on Windows) and add
a .cmd wrapper for manual invocation on Windows.

Fixes #285, #243

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated installation, bootstrap, and skill invocation instructions to use Node.js-based commands across all documentation and reference files.

• New Features

  • Added Windows command script wrapper to support running Codex CLI operations on Windows systems.

[arittr]

This change is part of the following stack:

• Fix Windows/PowerShell invocation of superpowers-codex #427 ◀

_{Change managed by git-spice.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates command invocations across installation and documentation files to explicitly use Node.js when running the superpowers-codex tool, and adds a Windows batch file wrapper for improved cross-platform compatibility.

Changes

Cohort / File(s)	Summary
Installation Instructions .codex/INSTALL.md, .codex/superpowers-bootstrap.md	Updated bootstrap and skill-calling commands from direct shell invocation to Node.js invocation. Changed ~/.codex/superpowers/.codex/superpowers-codex to node ~/.codex/superpowers/.codex/superpowers-codex across multiple instruction sections.
Windows Support .codex/superpowers-codex.cmd	Added new Windows batch script wrapper that invokes the Node.js-based tool with argument forwarding, enabling Windows command-line compatibility.
User Documentation docs/README.codex.md	Updated user-facing documentation examples and usage instructions to consistently show Node.js invocation for find-skills, use-skill, and bootstrap commands.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

• .codex/superpowers-codex not support powershell env (windows + powershell env) #285 – The changes directly address PowerShell/Windows environment compatibility by adding a Windows batch wrapper and explicitly using Node.js invocation, which resolves the reported issue with running superpowers-codex in PowerShell environments.

Poem

🐰 A Node script wrapped for Windows cheer,
Commands now dance where shells once feared,
Cross-platform magic, simple and clear,
No more PowerShell tears, just Node.js here! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: fixing Windows/PowerShell invocation of superpowers-codex, which aligns with all the modifications across multiple files.
Linked Issues check	✅ Passed	The PR addresses issue #285 by prefixing invocations with 'node' to bypass Windows shebang handling issues, adding a .cmd wrapper, and updating documentation—all meeting the requirement for PowerShell/Windows compatibility.
Out of Scope Changes check	✅ Passed	All changes are scoped to Windows/PowerShell invocation fixes: updating script invocations with 'node' prefix, adding a .cmd wrapper, and updating documentation to reflect the changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/windows-powershell-invocation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.codex/superpowers-codex.cmd:
- Line 1: The .codex/superpowers-codex.cmd file currently uses Unix line endings
(LF) which breaks Windows batch parsing; convert this file to Windows CRLF line
endings so the single line "@node "%~dp0superpowers-codex" %*" is terminated
with CRLF—either run a line-ending conversion (e.g., unix2dos or sed adding \r)
on .codex/superpowers-codex.cmd or add a .gitattributes entry ("*.cmd text
eol=crlf") and commit so Git normalizes future commits.

🧹 Nitpick comments (1)

docs/README.codex.md (1)

53-54: Optional: Consider the markdownlint warnings.

The static analysis tool flagged missing language specifiers for the fenced code blocks on these lines. However, these blocks appear to contain natural language instructions for Codex (e.g., "Run node ...") rather than executable code, so leaving them untagged may be intentional. If you want to address the linter warnings, you could add a language tag like text or plaintext, but this is purely stylistic.

📝 Optional: Add language specifiers

-```
+```text
 Run node ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming

```diff
-```
+```text
 Run node ~/.codex/superpowers/.codex/superpowers-codex bootstrap

</details>


Also applies to: 59-60

</blockquote></details>

</blockquote></details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Critical: Convert to Windows line endings (CRLF).

The batch file currently uses Unix line endings (LF), which can cause script malfunction on Windows due to the batch parser's sensitivity to line endings. This can result in GOTO/CALL label parsing failures and unexpected behavior.

🔧 Fix line endings

Convert the file to Windows line endings (CRLF). You can use:

#!/bin/bash
# Convert line endings to CRLF
unix2dos .codex/superpowers-codex.cmd
# Or if unix2dos is not available:
sed -i 's/$/\r/' .codex/superpowers-codex.cmd

Alternatively, configure git to handle line endings automatically:

#!/bin/bash
# Add .gitattributes entry for .cmd files
echo "*.cmd text eol=crlf" >> .gitattributes

🧰 Tools

🪛 Blinter (1.0.112)

[error] 1-1: Unix line endings detected. Explanation: Batch file uses Unix line endings (LF-only) which can cause GOTO/CALL label parsing failures and script malfunction due to Windows batch parser 512-byte boundary bugs. Recommendation: Convert file to Windows line endings (CRLF). Use tools like dos2unix, notepad++, or configure git with 'git config core.autocrlf true'. Context: File uses Unix line endings (LF-only) - 1 LF sequences found

(E018)

🤖 Prompt for AI Agents

In @.codex/superpowers-codex.cmd at line 1, The .codex/superpowers-codex.cmd
file currently uses Unix line endings (LF) which breaks Windows batch parsing;
convert this file to Windows CRLF line endings so the single line "@node
"%~dp0superpowers-codex" %*" is terminated with CRLF—either run a line-ending
conversion (e.g., unix2dos or sed adding \r) on .codex/superpowers-codex.cmd or
add a .gitattributes entry ("*.cmd text eol=crlf") and commit so Git normalizes
future commits.