{"id":51457201,"url":"https://github.com/fnclaude/pathfix","last_synced_at":"2026-07-06T01:30:30.994Z","repository":{"id":350380010,"uuid":"1206559711","full_name":"fnclaude/pathfix","owner":"fnclaude","description":"Claude Code hook that transparently converts Windows paths to POSIX in Bash commands — eliminating retry loops and saving tokens","archived":false,"fork":false,"pushed_at":"2026-07-02T03:23:47.000Z","size":124,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T05:15:42.527Z","etag":null,"topics":["ai-coding","claude-code","claude-code-plugin","developer-tools","git-bash","hooks","path-normalization","token-optimization","windows"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fnclaude.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"fnrhombus","buy_me_a_coffee":"fnrhombus"}},"created_at":"2026-04-10T03:12:21.000Z","updated_at":"2026-07-02T03:23:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fnclaude/pathfix","commit_stats":null,"previous_names":["fnrhombus/claude-code-pathfix","fnclaude/pathfix"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fnclaude/pathfix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnclaude%2Fpathfix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnclaude%2Fpathfix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnclaude%2Fpathfix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnclaude%2Fpathfix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fnclaude","download_url":"https://codeload.github.com/fnclaude/pathfix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnclaude%2Fpathfix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35175118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","claude-code","claude-code-plugin","developer-tools","git-bash","hooks","path-normalization","token-optimization","windows"],"created_at":"2026-07-06T01:30:30.179Z","updated_at":"2026-07-06T01:30:30.962Z","avatar_url":"https://github.com/fnclaude.png","language":"JavaScript","funding_links":["https://github.com/sponsors/fnrhombus","https://buymeacoffee.com/fnrhombus"],"categories":[],"sub_categories":[],"readme":"# claude-code-pathfix\n\n**Stop burning tokens on Windows path errors.**\n\n[![npm version](https://img.shields.io/npm/v/claude-code-pathfix)](https://www.npmjs.com/package/claude-code-pathfix)\n[![license](https://img.shields.io/npm/l/claude-code-pathfix)](./LICENSE)\n\nEvery 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.\n\n**`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.\n\n## The problem\n\nClaude Code runs Bash (Git Bash / MSYS2) on Windows, but the AI constantly generates Windows-style paths:\n\n```bash\n# What Claude generates\ncat D:\\Users\\Tom\\.claude\\settings.json\ngit -C C:\\dev\\myproject status\nls \"C:\\Program Files\\Git\\bin\"\n\n# What Git Bash actually needs\ncat /d/Users/Tom/.claude/settings.json\ngit -C /c/dev/myproject status\nls \"/c/Program Files/Git/bin\"\n```\n\nEach failure triggers a retry loop:\n\n1. Command fails → error message (tokens spent)\n2. Claude reasons about the error (more tokens spent)\n3. Claude retries with a corrected path (even more tokens)\n4. Sometimes repeats 3-4 times before succeeding\n\nThis 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.\n\n## The fix\n\nInstall `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.\n\n```\nBefore: 3-4 attempts per path error × multiple errors per session = hundreds of wasted tokens\nAfter:  zero failures, zero retries, zero wasted tokens\n```\n\n## Prior art\n\nThe 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.\"*\n\n`claude-code-pathfix` takes this further:\n\n| | netnerds.net approach | claude-code-pathfix |\n|---|---|---|\n| **Mechanism** | Block the command, force a retry | Transparently rewrite the command |\n| **Retries needed** | 1 (Claude must resubmit) | 0 (fixed before execution) |\n| **Tokens saved** | ~60% of retry cost | ~100% of retry cost |\n| **Claude awareness** | Claude sees the block, reasons about it | Claude never knows — command just works |\n| **Scope** | PowerShell commands | All Bash commands |\n\nThe 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.\n\n## Install\n\n### Option 1: Claude Code plugin (recommended)\n\nInside Claude Code, run:\n\n```\n/plugin marketplace add fnrhombus/claude-plugins\n/plugin install claude-code-pathfix@fnrhombus-plugins\n```\n\nDone. The hook is registered automatically — no `settings.json` edits required. Uninstall with `/plugin uninstall claude-code-pathfix@fnrhombus-plugins`.\n\n\u003e 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.\n\n### Option 2: npm + settings.json\n\nAdd this to your Claude Code settings (`~/.claude/settings.json`):\n\n```jsonc\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"npx -y claude-code-pathfix\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n`npx` downloads and caches the package automatically on first run — no global install needed.\n\nOr, have Claude Code configure itself:\n\n```bash\nclaude -p --allowedTools \"Edit(~/.claude/settings.json)\" \\\n  \"Add a PreToolUse hook to your user settings.json: matcher 'Bash', type 'command', command 'npx -y claude-code-pathfix'\"\n```\n\n## What it converts\n\n| Input | Output |\n|---|---|\n| `D:\\Users\\Tom\\file.txt` | `/d/Users/Tom/file.txt` |\n| `C:\\dev\\myproject\\src\\index.ts` | `/c/dev/myproject/src/index.ts` |\n| `\"C:\\Program Files\\Git\\bin\"` | `\"/c/Program Files/Git/bin\"` |\n| `E:\\data\\export\\` | `/e/data/export/` |\n\n### What it doesn't touch\n\n- Paths that are already POSIX (`/d/Users/Tom/...`)\n- Relative paths with backslashes (`src\\file.ts`) — see tip below\n- URLs (`https://example.com`)\n- Escape sequences (`\\n`, `\\t`)\n- Non-path backslash usage (`grep 'foo\\|bar'`)\n\n\u003e **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`:\n\u003e\n\u003e ```\n\u003e Always use absolute paths in shell commands.\n\u003e ```\n\n## Escape hatch\n\nIf a specific command needs its Windows paths left alone (e.g., passing a path to a Windows-native tool), prefix it with `⟪!⟫`:\n\n```bash\n⟪!⟫somecommand C:\\Users\\Tom\\file.txt\n```\n\nThe 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.\n\n## Cross-platform safe\n\n**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.\n\n## Performance\n\nThe 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.\n\n## How it works\n\n1. Claude Code's `PreToolUse` event fires before every Bash command\n2. `claude-code-pathfix` reads the command from stdin\n3. A two-pass regex converts Windows absolute paths to POSIX format:\n   - Pass 1: quoted paths (handles spaces in paths like `\"C:\\Program Files\\...\"`)\n   - Pass 2: unquoted paths\n4. If any paths were converted, the fixed command is returned via `updatedInput`\n5. If nothing changed, the hook exits silently (no output = no modification)\n\n## Requirements\n\n- **Claude Code** v2.0.10+ (for `updatedInput` hook support)\n- **Node.js** 20+\n- **Windows** with Git Bash or MSYS2\n\n## Support\n\nIf you find this project useful, consider supporting its development:\n\n- **[GitHub Sponsors](https://github.com/sponsors/fnrhombus)** — Monthly sponsorship with public recognition\n- **[Buy Me a Coffee](https://buymeacoffee.com/fnrhombus)** — One-time or recurring donations\n\nYour support helps maintain and improve this project!\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnclaude%2Fpathfix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnclaude%2Fpathfix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnclaude%2Fpathfix/lists"}