claudetools/.claude/memory/feedback_windows_bash_mapping.md

Windows Bash Command Mapping (Git Bash vs WSL stub)

The Issue

On Windows machines (especially when the AI tool runs in PowerShell context), the bash command often resolves to the WSL stub at C:\Users\...\WindowsApps\bash.exe instead of the required Git for Windows / MSYS bash.

This breaks the entire ClaudeTools harness:

• .claude/scripts/vault.sh, sync.sh, check-messages.sh, etc. expect GNU bash features, /d/claudetools style paths, etc.
• Hooks and commands invoke bash -c '...'.
• self-check expects: bash present (GNU bash, version 5.2.37(1)-release (x86_64-pc-msys))

Symptoms: "Windows Subsystem for Linux has no installed distributions." or scripts failing with path/quoting issues.

The Fix

Prepend Git Bash directories to $env:Path so plain bash resolves to the correct one:

$gitBin = "C:\Program Files\Git\bin"
$gitUsrBin = "C:\Program Files\Git\usr\bin"
if ((Test-Path $gitBin) -and ((Get-Command bash -ErrorAction SilentlyContinue).Source -notlike '*Git*bin*bash.exe')) {
    $env:Path = "$gitBin;$gitUsrBin;" + ($env:Path -replace [regex]::Escape("$gitBin;"), '' -replace [regex]::Escape("$gitUsrBin;"), '')
}

After this:

• Get-Command bash returns C:\Program Files\Git\bin\bash.exe
• bash --version shows the MSYS version
• Plain invocations like bash .claude/scripts/vault.sh list work.

Project Helper

Use the reusable script:

. .claude/scripts/ensure-git-bash.ps1

It contains the logic above (idempotent, with verbose/warning).

Persistence

The user's PowerShell profile ($PROFILE) sources/contains the remap logic so it applies on shell startup.

See: .claude/scripts/ensure-git-bash.ps1 (the helper) and the profile for the exact code.

For AI Sessions (Grok or Claude)

• At the start of any command involving bash/harness scripts, ensure the mapping (source the ps1 or run the snippet).
• In Grok: the .grok/skills/windows-bash/SKILL.md (if present) and this memory entry will be available.
• Always prefer explicit full path "C:\Program Files\Git\bin\bash.exe" .claude/scripts/vault.sh ... for critical one-off calls if the env isn't trusted yet.
• Git Bash terminals (launched directly) already have the correct bash.

Related

• See the backslash hook for another Git Bash gotcha: .claude/hooks/block-backslash-winpath.sh
• SSH: always use system OpenSSH (C:\Windows\System32\OpenSSH\ssh.exe), never Git's ssh.
• Profile and PATH ordering is the standard way; do not remove the WindowsApps stub.

This was fixed during a session on GURU-5070 to make Grok tool calls reliable with the harness. Add similar entries for other machine-specific env quirks.