https://github.com/fnclaude/pathfix
Claude Code hook that transparently converts Windows paths to POSIX in Bash commands — eliminating retry loops and saving tokens
https://github.com/fnclaude/pathfix
ai-coding claude-code claude-code-plugin developer-tools git-bash hooks path-normalization token-optimization windows
Last synced: 3 days ago
JSON representation
Claude Code hook that transparently converts Windows paths to POSIX in Bash commands — eliminating retry loops and saving tokens
- Host: GitHub
- URL: https://github.com/fnclaude/pathfix
- Owner: fnclaude
- License: mit
- Created: 2026-04-10T03:12:21.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-07-02T03:23:47.000Z (7 days ago)
- Last Synced: 2026-07-02T05:15:42.527Z (6 days ago)
- Topics: ai-coding, claude-code, claude-code-plugin, developer-tools, git-bash, hooks, path-normalization, token-optimization, windows
- Language: JavaScript
- Size: 121 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# claude-code-pathfix
**Stop burning tokens on Windows path errors.**
[](https://www.npmjs.com/package/claude-code-pathfix)
[](./LICENSE)
Every time Claude Code generates a Bash command on Windows, there's a coin flip: will it use `D:\Users\Tom\file.txt` or `/d/Users/Tom/file.txt`? The wrong one fails, Claude reasons about the error, retries, sometimes fails again — and you pay for every token.
**`claude-code-pathfix` makes the problem disappear.** It's a zero-config [PreToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks) that silently rewrites Windows paths to POSIX format before Bash commands execute. No errors. No retries. No wasted tokens.
## The problem
Claude Code runs Bash (Git Bash / MSYS2) on Windows, but the AI constantly generates Windows-style paths:
```bash
# What Claude generates
cat D:\Users\Tom\.claude\settings.json
git -C C:\dev\myproject status
ls "C:\Program Files\Git\bin"
# What Git Bash actually needs
cat /d/Users/Tom/.claude/settings.json
git -C /c/dev/myproject status
ls "/c/Program Files/Git/bin"
```
Each failure triggers a retry loop:
1. Command fails → error message (tokens spent)
2. Claude reasons about the error (more tokens spent)
3. Claude retries with a corrected path (even more tokens)
4. Sometimes repeats 3-4 times before succeeding
This is **the most common source of wasted tokens on Windows.** There are [15+ open issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue+windows+path) about it in the Claude Code repo.
## The fix
Install `claude-code-pathfix` and add two lines to your settings. Every Bash command is silently intercepted, paths are converted, and the corrected command executes on the first try.
```
Before: 3-4 attempts per path error × multiple errors per session = hundreds of wasted tokens
After: zero failures, zero retries, zero wasted tokens
```
## Prior art
The blog post [*Fixing Claude Code's PowerShell Problem with Hooks*](https://blog.netnerds.net/2026/02/claude-code-powershell-hooks/) pioneered the idea of using hooks to catch Windows path errors. That approach **blocks** commands with bad paths and forces Claude to retry with the correct format — a "block-and-correct" pattern. The author reported going from *"three attempts per PowerShell operation"* to *"zero failures."*
`claude-code-pathfix` takes this further:
| | netnerds.net approach | claude-code-pathfix |
|---|---|---|
| **Mechanism** | Block the command, force a retry | Transparently rewrite the command |
| **Retries needed** | 1 (Claude must resubmit) | 0 (fixed before execution) |
| **Tokens saved** | ~60% of retry cost | ~100% of retry cost |
| **Claude awareness** | Claude sees the block, reasons about it | Claude never knows — command just works |
| **Scope** | PowerShell commands | All Bash commands |
The key difference: blocking still costs a round-trip. Claude sees the error, thinks about it, and resubmits — that's tokens spent on reasoning about a problem that could have been silently fixed. `claude-code-pathfix` uses Claude Code's [`updatedInput`](https://docs.anthropic.com/en/docs/claude-code/hooks) feature (shipped in v2.0.10) to rewrite the command in-flight. The AI never sees an error because there isn't one.
## Install
### Option 1: Claude Code plugin (recommended)
Inside Claude Code, run:
```
/plugin marketplace add fnrhombus/claude-plugins
/plugin install claude-code-pathfix@fnrhombus-plugins
```
Done. The hook is registered automatically — no `settings.json` edits required. Uninstall with `/plugin uninstall claude-code-pathfix@fnrhombus-plugins`.
> The marketplace at [`fnrhombus/claude-plugins`](https://github.com/fnrhombus/claude-plugins) auto-discovers every `fnrhombus` plugin tagged with the `claude-code-plugin` topic, so adding it once gives you access to all of them.
### Option 2: npm + settings.json
Add this to your Claude Code settings (`~/.claude/settings.json`):
```jsonc
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "npx -y claude-code-pathfix"
}
]
}
]
}
}
```
`npx` downloads and caches the package automatically on first run — no global install needed.
Or, have Claude Code configure itself:
```bash
claude -p --allowedTools "Edit(~/.claude/settings.json)" \
"Add a PreToolUse hook to your user settings.json: matcher 'Bash', type 'command', command 'npx -y claude-code-pathfix'"
```
## What it converts
| Input | Output |
|---|---|
| `D:\Users\Tom\file.txt` | `/d/Users/Tom/file.txt` |
| `C:\dev\myproject\src\index.ts` | `/c/dev/myproject/src/index.ts` |
| `"C:\Program Files\Git\bin"` | `"/c/Program Files/Git/bin"` |
| `E:\data\export\` | `/e/data/export/` |
### What it doesn't touch
- Paths that are already POSIX (`/d/Users/Tom/...`)
- Relative paths with backslashes (`src\file.ts`) — see tip below
- URLs (`https://example.com`)
- Escape sequences (`\n`, `\t`)
- Non-path backslash usage (`grep 'foo\|bar'`)
> **Tip:** This hook can only reliably detect Windows paths that start with a drive letter (`C:\...`). Relative paths with backslashes (`src\components\App.tsx`) are ambiguous in bash and can't be safely distinguished from escape sequences. To get the most out of this hook, add the following to your project's `CLAUDE.md`:
>
> ```
> Always use absolute paths in shell commands.
> ```
## Escape hatch
If a specific command needs its Windows paths left alone (e.g., passing a path to a Windows-native tool), prefix it with `⟪!⟫`:
```bash
⟪!⟫somecommand C:\Users\Tom\file.txt
```
The prefix is stripped before execution — the command runs as `somecommand C:\Users\Tom\file.txt` with no path conversion. No restart or settings change needed.
## Cross-platform safe
**If your Claude Code settings are symlinked across Windows and WSL** (a common setup), `claude-code-pathfix` detects the platform at startup and silently exits on non-Windows systems. It will never interfere with native Linux or macOS Bash commands.
## Performance
The hook is a tiny Node.js script built on [`@fnrhombus/claude-code-hooks`](https://github.com/fnclaude/hooks), a strongly-typed wrapper for the Claude Code hook API. It starts in under 20ms — compared to 200-500ms for hooks that spawn a Bash subshell ([#34457](https://github.com/anthropics/claude-code/issues/34457)). You won't notice it's there.
## How it works
1. Claude Code's `PreToolUse` event fires before every Bash command
2. `claude-code-pathfix` reads the command from stdin
3. A two-pass regex converts Windows absolute paths to POSIX format:
- Pass 1: quoted paths (handles spaces in paths like `"C:\Program Files\..."`)
- Pass 2: unquoted paths
4. If any paths were converted, the fixed command is returned via `updatedInput`
5. If nothing changed, the hook exits silently (no output = no modification)
## Requirements
- **Claude Code** v2.0.10+ (for `updatedInput` hook support)
- **Node.js** 20+
- **Windows** with Git Bash or MSYS2
## Support
If you find this project useful, consider supporting its development:
- **[GitHub Sponsors](https://github.com/sponsors/fnrhombus)** — Monthly sponsorship with public recognition
- **[Buy Me a Coffee](https://buymeacoffee.com/fnrhombus)** — One-time or recurring donations
Your support helps maintain and improve this project!
## License
MIT