Claude Code with Windows PowerShell: every quirk we've hit, and the fix

I run Claude Code on Windows 11 daily. It works well. It also has a dozen platform-specific paper cuts that no Mac-focused tutorial mentions. Here they all are, with the fix.

1. The “Use Unix commands” default

By default, Claude sometimes assumes a bash/Linux shell. On Windows you’ll see it propose ls, cat, export VAR=..., none of which work in PowerShell.

Fix: Add this to your project CLAUDE.md (or your global ~/.claude/CLAUDE.md):

Shell: PowerShell on Windows. Use PowerShell syntax:
- $env:VAR not $VAR
- Get-ChildItem (alias: gci, ls), but prefer Get-ChildItem for scripts
- Backtick for line continuation, not backslash
- Use forward slashes in paths where possible (Node tools accept them)
- /dev/null equivalent: $null
- 2>&1 works the same

Done. Claude shifts immediately and stays shifted.

2. OneDrive path issues

If your dev folder lives under C:\Users\you\OneDrive\Documents\, you’ll hit two problems:

1. Files-on-demand thrashing. Some tools (Prettier, ESLint) hammer files repeatedly and OneDrive Files-On-Demand fights back, slowing things to a crawl.
2. Path length limits. Long node_modules trees + a OneDrive prefix breaks the 260-char path limit on older Windows.

Fix: Move active dev work to C:\dev\ or C:\Users\you\code\. Reserve OneDrive for documents you actually want synced. Or, if you must keep dev work in OneDrive, disable Files-On-Demand: Right-click OneDrive tray icon → Settings → Sync and backup → uncheck “Save space and download files as you use them.”

3. PowerShell hook command quoting

Hooks defined in .claude/settings.json are shell commands. The quoting that works on macOS bash doesn’t always work in PowerShell. Example:

{
 "command": "echo \"Today is $(date '+%Y-%m-%d')\""
}

PowerShell parses this differently. The $(...) is PowerShell’s own subexpression operator and date is an alias for Get-Date.

Fix: Write hooks in pure PowerShell syntax if you’re on Windows, or invoke through bash -c if you have Git Bash installed:

{
 "command": "powershell -NoProfile -Command \"echo ('Today is ' + (Get-Date -Format 'yyyy-MM-dd'))\""
}

Verbose but reliable. Project the .claude/settings.json into a per-platform variant if your team is mixed Mac + Windows.

4. Environment variables that “don’t persist”

You set $env:ANTHROPIC_API_KEY in one PowerShell session. Open a new one. Gone.

Fix: Set persistent environment variables in Windows settings: search “environment variables” in the Start menu, edit user-level variables. Or, for the Anthropic API key specifically, use setx:

setx ANTHROPIC_API_KEY "sk-ant-..."

Then restart PowerShell. New sessions see the variable.

5. npm global install permission errors

npm install -g @anthropic-ai/claude-code

…throws an EACCES or “elevation required” error.

Fix: Don’t run PowerShell as admin. Instead, set npm’s prefix to a user-owned folder:

mkdir "$env:USERPROFILE\.npm-global"
npm config set prefix "$env:USERPROFILE\.npm-global"

Then add $env:USERPROFILE\.npm-global to your PATH (Windows Settings → System → About → Advanced system settings → Environment Variables). New PowerShell sessions see it.

6. Antivirus slowing every file read

Windows Defender (or whatever AV you have) inspects every file Claude reads. On a large repo, this adds ~50-200ms per read.

Fix: Add your dev folder to Defender’s exclusion list. Settings → Privacy & security → Windows Security → Virus & threat protection → Manage settings → Exclusions → Add → Folder. Pick C:\dev\ or wherever you keep code.

This is not turning off antivirus, it just exempts your code folder from real-time scanning, the same way developer machines have done for 20 years. Don’t exempt your Downloads folder.

7. Line endings in committed files

Claude writes files with the line endings of the OS, which on Windows is CRLF. Your team on macOS sees CRLF in diffs and panics.

Fix: Set git’s autocrlf in your repo’s .gitattributes:

* text=auto eol=lf
*.md text eol=lf
*.json text eol=lf
*.ts text eol=lf
*.astro text eol=lf

Now everything lands in LF on disk, regardless of the OS the author was on.

8. Long path support

Some PowerShell + Node combos still respect the 260-character path limit by default, even though Windows 10/11 supports longer paths if you enable them.

Fix: Enable long paths once:

# Run as Admin once
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

And in git:

git config --system core.longpaths true

Reboot. Paths up to 32k chars now work.

9. Claude Code’s “edit a file” sometimes fails silently on locked files

Excel, Word and OneNote lock files open. If Claude tries to edit quote-template.xlsx while you have it open, the write silently fails.

Fix: Close the file before asking Claude to edit it. Or, prompt Claude to copy first: “Make a copy of quote-template.xlsx as quote-2026-05-18.xlsx, then edit the copy.”

10. Powershell execution policy blocking scripts

Out of the box, PowerShell refuses to run unsigned .ps1 scripts. Some Claude Code tools and hooks rely on running PowerShell scripts.

Fix: Set your execution policy to RemoteSigned for the current user:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Local scripts now run; downloaded scripts still need signing or to be unblocked. Safe for normal use.

11. Slow Claude Code startup the first time per day

The first claude of the day takes 3-5 seconds. Subsequent ones launch instantly. This is Node startup + npm resolution + Anthropic cold cache.

Fix: Nothing to fix, but if it bugs you, run claude once when you open your terminal in the morning. Stays warm for the day.

12. The Windows Terminal vs PowerShell ISE vs VS Code Terminal dilemma

Three good options:

• Windows Terminal (the new one in Settings → “Terminal” by default in Win11). Best for power use, tabbed sessions, good Unicode support.
• PowerShell directly. Works fine, less polished.
• VS Code integrated terminal. Best if you live in VS Code. Pairs naturally with Claude Code’s VS Code extension.

We use Windows Terminal day-to-day with PowerShell 7. Install it once, set as default. The improvements over the old console are substantial.

When to give up and use WSL

If you need a Linux-only tool (some Python packages, certain DevOps tooling), use WSL. Don’t fight Windows when there’s a real Linux-only dependency. Claude Code runs inside WSL2 cleanly. Just be aware:

• File operations across the WSL/Windows boundary are slow. Keep your code on the WSL filesystem (/home/you/) not on /mnt/c/.
• VS Code’s WSL extension handles the editor side gracefully.
• Anthropic billing is identical regardless of host OS.

CLAUDE.md template for Windows

If you don’t have a CLAUDE.md shape, here’s the one we use as a starting point for every Windows project:

# Project
{name + 1-sentence purpose}

# Environment
- OS: Windows 11
- Shell: PowerShell 7 (pwsh). Bash is also available via Git Bash.
- Node: 22 LTS
- Dev folder: C:\dev\{this-repo}\

# Shell rules
- Use PowerShell syntax: $env:VAR, Get-ChildItem, backtick for line continuation
- Forward slashes in JS/TS path strings; Windows accepts them
- `Out-Null` not `> /dev/null`

# Locale + voice
- Australian English (organised, colour, centre, analysed)
- AUD pricing
- DD/MM/YYYY dates
- No em dashes, use en dashes or commas

# Project-specific
{add as you go}

That single file removes 80% of Windows-specific friction with Claude.