win-hooks

"Linux? Nah. WinUX!"

Don't let Windows kill your vibe coding flow.

Every Claude Code / Codex plugin assumes you're on macOS or Linux.
On Windows, your sessions start with a wall of red hook errors.
win-hooks fixes that. Automatically. Every session.

---

The Problem

You install a Claude Code / Codex plugin, start a session, and see errors like:

SessionStart hook error: /bin/bash: command not found
PreToolUse hook error: scripts/check.sh: No such file or directory
PostToolUse hook error: semgrep: command not found

The plugin may be fine on macOS or Linux, but its hooks assume Unix tools, .sh scripts, or shell paths that Windows does not run directly.

Quick Start

Claude Code

Paste once:

claude plugin marketplace add LilMGenius/win-hooks && claude plugin install win-hooks

That is the setup. No config, no flags, no manual patching.

Codex

Paste once:

codex plugin marketplace add LilMGenius/win-hooks && codex plugin add win-hooks@win-hooks

Codex uses its native commandWindows field, so the original cross-platform command stays intact.

CLI (npm)

Want a one-shot fix, or to run it in CI, without installing the plugin? Run it directly:

npx @lilmgenius/win-hooks         # repair installed Claude Code AND Codex plugin hooks
npx @lilmgenius/win-hooks status  # show the last repair result

Windows only. It uses the same runtimes as the plugin — Git for Windows (Bash) and Node.js. Installed as a plugin, win-hooks also runs automatically every session; the CLI is for when you'd rather trigger it yourself.

What win-hooks Fixes

win-hooks scans your installed Claude Code / Codex plugins and repairs Windows-incompatible hook commands before they keep breaking your session.

It handles the common failure modes:

• .sh scripts called directly from Windows
• missing Unix-only commands such as semgrep or shellcheck
• bare node, python, python3, npx, or npm commands that work in Git Bash but fail through Windows hook dispatch
• Windows backslash paths inside hook commands
• UTF-8 BOM, CRLF, invalid JSON, missing wrappers, and broken wrapper files
• python3 hooks blocked by the Microsoft Store Python alias

Original plugin files are backed up where hooks are patched, and already-compatible plugins are skipped.

How It Stays Fixed

win-hooks runs automatically at session start.

Claude Code pipeline:

flowchart LR
    A[scan plugins] --> B[patch hooks.json] --> C[normalize settings.json] --> D["verify & auto-repair"]

Loading

Codex pipeline:

flowchart LR
    A[scan plugins] --> B["add commandWindows wrappers"] --> C["verify & auto-repair"]

Loading

Plugin updates are covered too. If an update replaces a repaired hook with a fresh broken one, win-hooks re-patches it at the next session start.

It also checks again on your next prompt after a plugin update. Use /reload-plugins when you want the repaired hook config loaded without starting a new session.

Check Status

The normal path is silent, so win-hooks writes a small heartbeat log:

tail -n 5 ~/.claude/win-hooks/last-run.log
tail -n 5 ~/.codex/win-hooks/last-run.log

• phase=done means the self-heal completed.
• a lone phase=start means the run was cut off mid-way and should retry next session.
• no file means it has not dispatched yet.

You can also run:

/win-hooks:status

Commands

Command	Description
/win-hooks:status	Show the current compatibility status of installed plugin hooks.
/win-hooks:fix	Manually run the repair pipeline. Normally you should not need this.

Requirements

• Windows 10/11
• Claude Code / Codex
• Git for Windows
• Node.js available on PATH

Claude Code already provides the Node.js runtime used by the Claude-side patch/verify flow. The Codex flow also uses node in scripts/codex-find-incompatible and scripts/codex-verify. Git for Windows provides the Bash runtime used to execute repaired hooks.

Technical Notes

For Claude Code, win-hooks creates a dedicated _hooks/ directory inside each patched plugin. The original hook target stays untouched, and hooks.json points at a Windows-safe wrapper.

plugin/
├── hooks/
│   ├── hooks.json
│   └── hooks.json.bak
├── _hooks/
│   ├── run-hook.cmd
│   └── <wrapper>
└── scripts/
    └── setup.sh

The wrapper entry point is a polyglot .cmd file: Windows runs the batch portion, while Bash can run the shell portion. That keeps one repaired hook path usable across both Windows dispatch and Bash execution.

For Codex, win-hooks creates _codex_hooks/ and adds commandWindows to incompatible hook entries:

plugin/
├── .codex-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── hooks.json.codex-win-hooks.bak
└── _codex_hooks/
    ├── run-hook.cmd
    └── <wrapper>

Codex keeps using the original command on macOS/Linux. On Windows it uses the generated commandWindows wrapper.

Contributors can read CLAUDE.md for the internal scanner, patcher, verifier, and case notes.