Windows (Git Bash) Platform Guide

This tutorial uses Windows + Git Bash as the primary platform. This page covers all Windows-specific configuration tips and common issues.

Environment Setup

Required Software

# 1. Git for Windows (includes Git Bash)
# Download: https://gitforwindows.org/
# During installation, check "Git Bash Here" and "Use Git from the Windows Command Line"

# 2. Node.js 18+
# Download: https://nodejs.org/
# The LTS version is recommended

# 3. Claude Code CLI
npm install -g @anthropic-ai/claude-code

Optional Tools

# jq - JSON processing tool (needed for the Hooks chapter)
# Option 1: Via Chocolatey
choco install jq

# Option 2: Direct download
# Download jq-win64.exe from https://jqlang.github.io/jq/download/
# Rename it to jq.exe and place it in a directory on your PATH

# Python 3.10+ (needed for the Agent SDK chapter)
# Download: https://www.python.org/downloads/

Git Bash Gotchas

Path Formats

Git Bash uses Unix-style paths, but there are a few cases to watch out for:

# Paths in Git Bash
~/.claude/settings.json           # Equivalent to C:/Users/<username>/.claude/settings.json

# When referencing paths in CLAUDE.md, use forward slashes
src/components/**/*.tsx            # Correct
src\components\**\*.tsx            # Wrong — don't use backslashes

# Paths in settings.json
"file_path": "src/utils/helper.ts" # Correct

Shell Config Files

# Git Bash loading order:
# 1. ~/.bash_profile (login shell)
# 2. ~/.bashrc (interactive shell)

# Recommended: source ~/.bashrc from ~/.bash_profile
echo 'if [ -f ~/.bashrc ]; then source ~/.bashrc; fi' >> ~/.bash_profile

# Setting environment variables
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Line Ending Issues

# Git config: prevent CRLF from breaking hook scripts
git config --global core.autocrlf input

# If a hook script errors with "/bin/bash^M: bad interpreter"
# Convert the line endings with dos2unix
dos2unix .claude/hooks/*.sh
# Or use sed
sed -i 's/\r$//' .claude/hooks/*.sh

Windows-specific Notes by Chapter

Ch5 Hooks — Notification Sounds

# Play a notification sound on Windows (inside a hook script)
powershell.exe -Command "[System.Media.SystemSounds]::Asterisk.Play()"

# Or play a custom audio file via PowerShell
powershell.exe -Command "(New-Object Media.SoundPlayer 'C:/path/to/sound.wav').PlaySync()"

Ch5 Hooks — Script Execution

# Hook scripts in Git Bash need a bash shebang
#!/bin/bash

# Make sure scripts have execute permissions
chmod +x .claude/hooks/*.sh

# If using PowerShell as a hook handler,
# set it up in settings.json like this:
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "powershell.exe -File .claude/hooks/lint.ps1"
      }]
    }]
  }
}

Ch9 Agent Teams — Display Mode

# Windows doesn't natively support tmux, so Agent Teams can only run in in-process mode
# This means all teammate output appears in the same terminal

# Alternative 1: Use Windows Terminal tabs
# Alternative 2: Use WSL2 + tmux
wsl --install
# Install tmux inside WSL
sudo apt install tmux

Ch10 Permissions — Managed Policy Paths

# Managed policy paths on Windows
# C:\Program Files\ClaudeCode\managed-settings.json
# C:\Program Files\ClaudeCode\managed-settings.d\*.json
# C:\Program Files\ClaudeCode\CLAUDE.md

# Admin privileges are required to write to this directory

Troubleshooting

Q: Claude Code won't start in Git Bash

# Check that Node.js is on your PATH
node --version
npm --version

# Check that Claude Code installed correctly
claude --version

# If you get "command not found", check the npm global install directory
npm config get prefix
# Make sure the bin/ subdirectory of that path is on your PATH

Q: Hook scripts throw errors

# 1. Check line endings
file .claude/hooks/your-hook.sh
# If it shows "CRLF", convert to LF
sed -i 's/\r$//' .claude/hooks/your-hook.sh

# 2. Check execute permissions
chmod +x .claude/hooks/your-hook.sh

# 3. Check the shebang line
head -1 .claude/hooks/your-hook.sh
# Should be #!/bin/bash

Q: $CLAUDE_PROJECT_DIR path format

# In Git Bash, this variable uses Unix-style paths
echo $CLAUDE_PROJECT_DIR
# Output: /d/projects/my-project

# If you need to pass it to a Windows program, you may need to convert it
# cygpath -w "$CLAUDE_PROJECT_DIR"
# Output: D:\projects\my-project

Q: PowerShell Tool Support

# Claude Code supports using PowerShell as an alternative to the Bash tool
# Set this environment variable to enable it
export CLAUDE_CODE_USE_POWERSHELL_TOOL=1

# This makes Claude use PowerShell instead of bash for command execution
# Useful when you need native Windows commands