🚨 CRITICAL GUIDELINES Windows File Path Requirements
MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes () in file paths, NOT forward slashes (/).
Examples:
❌ WRONG: D:/repos/project/file.tsx ✅ CORRECT: D:\repos\project\file.tsx
This applies to:
Edit tool file_path parameter Write tool file_path parameter All file operations on Windows systems Documentation Guidelines
NEVER create new documentation files unless explicitly requested by the user.
Priority: Update existing README.md files rather than creating new documentation Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise Style: Documentation should be concise, direct, and professional - avoid AI-generated tone User preference: Only create additional .md files when user specifically asks for documentation Windows Path Troubleshooting for Claude Code 🚨 CRITICAL: Always Use Backslashes on Windows for File Paths
MANDATORY: When using Edit, Write, or Read tools on Windows, you MUST use backslashes () in file paths, NOT forward slashes (/).
The Rule
Windows File Path Requirements:
✅ CORRECT: D:\repos\project\file.tsx ❌ WRONG: D:/repos/project/file.tsx
This applies to:
Edit tool file_path parameter Write tool file_path parameter Read tool file_path parameter All file operations on Windows systems Why This Matters
Common error message when using forward slashes on Windows:
Error: ENOENT: no such file or directory
Root cause:
Windows native file system uses backslashes () as path separators Forward slashes (/) work in some Windows contexts but NOT in Claude Code file tools Git Bash displays paths with forward slashes but Windows APIs require backslashes Claude Code's Read/Write/Edit tools use Windows native APIs that expect backslashes 🔍 Common Windows Path Issues in Claude Code Issue 1: Forward Slashes in Tool Calls
Symptom:
Edit tool fails with "file not found" or "no such file or directory"
Cause: Using forward slashes copied from Git Bash output:
Git Bash shows:
/s/repos/claude-plugin-marketplace/file.tsx
Incorrect usage:
Edit(file_path="/s/repos/myproject/file.tsx")
Correct usage:
Edit(file_path="S:\repos\myproject\file.tsx")
Solution steps:
Identify the Windows drive letter (e.g., /s/ → S:) Replace forward slashes with backslashes Add drive letter with colon Use absolute Windows path format Issue 2: Git Bash MINGW Path Format
Symptom: Paths like /s/repos/ or /c/Users/ don't work in Edit/Write/Read tools
MINGW path format explained:
Git Bash uses POSIX-style paths on Windows Drive letters are represented as /c/, /d/, /s/, etc. These are MINGW virtual paths, not Windows paths Claude Code tools need Windows-native paths
Conversion table:
Git Bash (MINGW) Windows Native /c/Users/name/ C:\Users\name\ /d/repos/project/ D:\repos\project\ /s/work/code/ S:\work\code\ /mnt/c/Windows/ C:\Windows\
Conversion algorithm:
Extract drive letter from first path segment (e.g., /s/ → S) Add colon to drive letter (e.g., S → S:) Replace remaining forward slashes with backslashes Combine: S: + \repos\project\file.tsx Issue 3: Relative Paths in Git Bash
Symptom: Relative paths from Git Bash don't resolve correctly in Claude Code tools
Cause: Git Bash current working directory uses MINGW format, but Claude Code tools use Windows format
Example scenario:
In Git Bash:
pwd
Shows: /s/repos/my-project
User provides relative path:
./src/components/Button.tsx
Problem: Claude Code can't resolve ./src/ from MINGW /s/repos/my-project
Solution:
Get the full Windows path from Git Bash: pwd -W
Shows: S:/repos/my-project (Windows format with forward slashes)
Convert to proper Windows path: S:\repos\my-project Append relative path with backslashes: S:\repos\my-project\src\components\Button.tsx Issue 4: Environment Variable Expansion
Symptom: Paths with environment variables like $HOME or %USERPROFILE% fail
Git Bash environment variables:
echo $HOME
Shows: /c/Users/username (MINGW format)
Windows environment variables:
echo %USERPROFILE%
Shows: C:\Users\username (Windows format)
Best practice:
Avoid environment variables in file paths for Claude Code tools Use absolute Windows paths instead If user provides $HOME, ask them to run echo $HOME and convert the result Issue 5: Spaces in File Paths
Symptom: Paths with spaces break or cause "file not found" errors
Correct handling:
✅ CORRECT: Edit(file_path="C:\Program Files\My App\config.json") ✅ CORRECT: Edit(file_path="D:\My Documents\project\file.txt")
Notes:
Do NOT add quotes around the path in the parameter The tool call itself handles escaping Spaces are fine in Windows paths when using backslashes Issue 6: UNC Network Paths
Symptom: Network paths like \server\share\file.txt fail
Windows UNC format:
\server\share\folder\file.txt
Git Bash representation:
//server/share/folder/file.txt
Correct usage in Claude Code:
Edit(file_path="\\server\share\folder\file.txt")
Note: Backslashes must be doubled in some contexts due to escaping, but Claude Code tools handle this automatically.
🔧 Path Detection and Conversion Algorithm
When a user provides a file path, follow this decision tree:
Step 1: Identify Path Format
MINGW Path (Git Bash):
Starts with / followed by single letter and / (e.g., /c/, /s/) Example: /s/repos/project/file.tsx Action: Convert to Windows format
Windows Path:
Starts with drive letter and colon (e.g., C:, D:) Uses backslashes or forward slashes Example: S:\repos\project\file.tsx or S:/repos/project/file.tsx Action: Ensure backslashes are used
Relative Path:
Starts with ./ or ../ or just filename Example: ./src/components/Button.tsx Action: Request full path from user or detect current directory
UNC Path:
Starts with \ or // Example: \server\share\file.txt Action: Ensure backslashes are used Step 2: Conversion Process
For MINGW paths (/x/...):
Input: /s/repos/myproject/src/components/Button.tsx
Process: 1. Extract drive letter: "s" 2. Uppercase: "S" 3. Add colon: "S:" 4. Replace remaining slashes: \repos\myproject\src\components\Button.tsx 5. Combine: S:\repos\myproject\src\components\Button.tsx
Output: S:\repos\myproject\src\components\Button.tsx
For Windows paths with forward slashes (X:/...):
Input: S:/repos/project/file.tsx
Process: 1. Detect drive letter already present: "S:" 2. Replace forward slashes with backslashes: \repos\project\file.tsx 3. Combine: S:\repos\project\file.tsx
Output: S:\repos\project\file.tsx
For relative paths:
Input: ./src/components/Button.tsx Current directory (from user or detection): S:\repos\my-project
Process: 1. Remove ./ prefix 2. Replace forward slashes: src\components\Button.tsx 3. Combine with current directory: S:\repos\my-project\src\components\Button.tsx
Output: S:\repos\my-project\src\components\Button.tsx
🛠️ Interactive Path Fixing Workflow
When you encounter a file path error on Windows:
Step 1: Detect the Error
Error indicators:
"ENOENT: no such file or directory" "file not found" Edit/Write/Read tool failure User mentions "Windows" or "Git Bash" Step 2: Analyze the Path
Ask yourself:
Was the path provided by the user in MINGW format? Does the path use forward slashes? Is it a relative path? Did I receive the path from a Git Bash command output? Step 3: Request Clarification (If Needed)
If the path is ambiguous, ask:
I see you're working on Windows with Git Bash. To ensure I use the correct path format, could you run this command and share the output?
pwd -W
This will give me the Windows-formatted path.
Step 4: Convert and Retry
Conversion template:
I'll convert the path from Git Bash format to Windows format: - Git Bash: /s/repos/project/file.tsx - Windows: S:\repos\project\file.tsx
Retrying with the correct Windows path...
Step 5: Verify Success
After conversion, verify the operation succeeded and explain what was fixed:
✅ Successfully edited the file using the Windows path format (S:\repos...).
Note: On Windows with Git Bash, always use backslashes () in file paths for Claude Code's Edit/Write/Read tools, even though Git Bash displays paths with forward slashes (/).
📋 Troubleshooting Checklist
When file operations fail on Windows:
Check path separator: Are backslashes () used instead of forward slashes (/)? Check drive letter format: Is it C: not /c/? Check MINGW conversion: Did you convert /x/path to X:\path? Check relative vs absolute: Is the path absolute starting with drive letter? Check environment variables: Did you expand $HOME or %USERPROFILE%? Check spaces: Are spaces in the path handled correctly? Check UNC paths: Are network paths using \server\share format? Check file existence: Does the file actually exist at that path? 🎯 Quick Reference: Path Conversion Examples Context Path Format Claude Code Tool Format Git Bash pwd /s/repos/project S:\repos\project Git Bash relative ./src/file.tsx S:\repos\project\src\file.tsx Windows Explorer S:\repos\project\file.tsx S:\repos\project\file.tsx ✅ Windows with / S:/repos/project/file.tsx S:\repos\project\file.tsx MINGW full path /c/Users/name/file.txt C:\Users\name\file.txt Network share (Git Bash) //server/share/file.txt \server\share\file.txt WSL path /mnt/c/repos/project C:\repos\project 🚀 Best Practices for Windows File Operations 1. Always Convert Paths Proactively
Don't wait for errors - If you see a path that looks like MINGW format, convert it immediately:
User provides: /s/repos/project/file.tsx You think: "This is MINGW format, I need to convert it to S:\repos\project\file.tsx" You do: Convert before calling Edit/Write/Read tool
- Use pwd -W in Git Bash
When you need current directory on Windows:
Instead of:
pwd # Shows: /s/repos/project (MINGW format)
Use:
pwd -W # Shows: S:/repos/project (Windows format with /)
Then convert the forward slashes to backslashes.
- Communicate Path Format Changes
Always explain when you convert paths:
I'll convert the Git Bash path to Windows format for the Edit tool: - From: /s/repos/project/file.tsx - To: S:\repos\project\file.tsx
This helps users understand the requirement and learn for future interactions.
- Validate Before Tool Use
Before calling Edit/Write/Read tools on Windows:
Pre-flight checklist: ✅ Path starts with drive letter and colon (e.g., C:, S:) ✅ Path uses backslashes () not forward slashes (/) ✅ Path is absolute, not relative ✅ No MINGW format (no /c/, /s/, etc.)
- Handle User-Provided Paths Carefully
User might provide paths in various formats:
Copy-pasted from Git Bash (MINGW format) Copy-pasted from Windows Explorer (Windows format) Typed manually (could be either) From command output (varies by tool)
Always detect and convert as needed.
🐛 Common Error Messages and Solutions Error: "ENOENT: no such file or directory"
Most likely cause: Forward slashes instead of backslashes
Solution:
Check if path uses forward slashes Convert to backslashes Verify drive letter format Retry operation Error: "Invalid file path"
Most likely cause: MINGW path format
Solution:
Detect /x/ pattern at start Convert to X: format Replace all forward slashes with backslashes Retry operation Error: "Access denied" or "Permission denied"
Most likely cause: Path is correct but permissions issue
Solution:
Verify file exists and is accessible Check if file is locked by another process Verify user has read/write permissions Consider running Git Bash as administrator Error: "File not found" but path looks correct
Possible causes:
Path has hidden characters (copy-paste issue) File extension is hidden in Windows Path has trailing spaces Case sensitivity (some tools are case-sensitive)
Solution:
Ask user to run ls -la in Git Bash to verify exact filename Check for file extensions Trim whitespace from path Match exact case of filename 📚 Platform-Specific Knowledge Windows File System Characteristics
Path characteristics:
Drive letters: A-Z (typically C: for system, D-Z for additional drives) Path separator: Backslash () Case insensitive: File.txt same as file.txt Special characters: Avoid < > : " | ? * in filenames Maximum path length: 260 characters (legacy limit, can be increased) Git Bash on Windows
Git Bash is a POSIX-compatible environment:
Uses MINGW (Minimalist GNU for Windows) Translates POSIX paths to Windows paths internally Commands like ls, pwd, cd use POSIX format Native Windows programs need Windows format paths
Key insight: Git Bash displays and accepts POSIX paths, but Windows APIs (used by Claude Code) require Windows paths.
WSL (Windows Subsystem for Linux)
WSL path mounting:
Windows drives mounted at /mnt/c/, /mnt/d/, etc. WSL path: /mnt/c/Users/name/project Windows path: C:\Users\name\project
Conversion:
Replace /mnt/x/ with X: Replace forward slashes with backslashes 🎓 Teaching Users
When explaining path issues to users, use this template:
I encountered a path format issue. Here's what happened:
The Problem: Claude Code's file tools (Edit, Write, Read) on Windows require paths in Windows native format with backslashes (), but Git Bash displays paths in POSIX format with forward slashes (/).
The Path Formats: - Git Bash shows: /s/repos/project/file.tsx - Windows needs: S:\repos\project\file.tsx
The Solution:
I've converted your path to Windows format. For future reference, when working
with Claude Code on Windows with Git Bash:
1. Use backslashes () in file paths
2. Use drive letter format (C:, D:, S:) not MINGW format (/c/, /d/, /s/)
3. Run pwd -W in Git Bash to get Windows-formatted paths
The Fix: ✅ Now using: S:\repos\project\file.tsx
🔍 Advanced Scenarios Scenario 1: Mixed Path Contexts
User is working with both WSL and Git Bash:
Ask which environment they're in Use appropriate conversion Document the choice Scenario 2: Symbolic Links
Windows symbolic links:
mklink /D C:\link C:\target
Handling:
Follow the link to actual path Use actual path in tool calls Inform user if link resolution needed Scenario 3: Docker Volumes
Docker volume mounts on Windows:
docker run -v C:\repos:/app
Path translation:
Outside container: C:\repos\file.txt Inside container: /app/file.txt Use context-appropriate format ✅ Success Criteria
You've successfully handled Windows paths when:
✅ All Edit/Write/Read tool calls use backslashes on Windows ✅ MINGW paths are converted before tool use ✅ Relative paths are resolved to absolute Windows paths ✅ User understands why conversion was necessary ✅ File operations succeed without path-related errors ✅ Path format is consistent throughout the session 🆘 When to Use This Skill
PROACTIVELY apply this knowledge when:
User mentions they're on Windows User mentions Git Bash or MINGW You see paths starting with /c/, /s/, etc. Edit/Write/Read tool fails with "file not found" User provides paths with forward slashes on Windows You need to read/edit/write files on Windows system
This skill is CRITICAL for Windows users - Path format errors are the #1 cause of file operation failures on Windows with Git Bash.