Try free

Last updated 13 October 2026

Repair Claude Code paths on Windows

Windows file paths often break the agent logic

Windows developers frequently encounter errors where the agent cannot find a file that clearly exists in the directory. This usually happens because the underlying tools like Glob or Grep receive paths with backslashes that they interpret as escape characters. If the agent tries to run a Read tool on a path like src\components\Button.tsx, the tool might fail because it expects the forward slash common in Unix environments. You see a message saying the file does not exist even when you are looking at it in your editor.

This mismatch between the Windows file system and the expectations of the coding agent is a common cause of friction. It often leads to the agent repeatedly trying to find a file and failing until it exhausts its attempts. Understanding that the agent prefers forward slashes is the first step toward a stable configuration. You must ensure that the shell environment does not mangle these strings before they reach the agent core.

Absolute paths and drive letters require care

Drive letters introduce another layer of complexity for the toolset. When the agent tries to use an absolute path starting with C:\, the colon and the backslash can confuse the shell interface that the agent uses to execute commands. It is often better to run the command claude from the root folder of your project to ensure all paths stay relative. Relative paths are less likely to trigger drive letter parsing errors in the Read or Write tools.

If you must use absolute paths, try to use the forward slash format even on Windows, as the internal logic usually handles this better than the native Windows format. This small change in how you think about paths can prevent many execution errors. The agent will typically follow the pattern it sees in the current working directory, so starting in the correct root is essential for its path discovery logic.

Adjusting settings for path reliability

You can influence how the agent handles permissions and file access through the .claude/settings.json file in your repo root. If you find that specific folders are consistently causing path resolution issues, you can explicitly manage them by excluding them from the search space. The agent respects your .gitignore file, so ensure that any problematic system directories or build artifacts are excluded there. This prevents the Glob tool from scanning deep into Windows-specific folders that might contain incompatible path strings.

You can also define custom permissions in this file to allow or deny the agent access to sensitive system paths. This gives you granular control over what the agent can see and modify. By setting the permissions field correctly in settings.json, you prevent the agent from wandering into system-level directories where Windows path syntax is more likely to cause a crash or an infinite loop during a recursive search.

The choice of terminal shell matters

The choice of terminal shell matters significantly for how paths are passed to the agent. Running the tool inside PowerShell often handles path strings differently than the standard Windows Command Prompt or a bash-like environment. If you see errors related to how arguments are passed to tools, try switching your shell to see if the behavior improves. You can use the /terminal-setup command inside a session to see if the current configuration supports the features the agent needs to resolve files correctly.

Some shells might auto-convert slashes in a way that helps or hinders the agent. Testing different terminal environments is a key part of setting up a stable workflow on Windows. Many developers find that Git Bash or the Windows Terminal with a clean profile provides the most consistent results. If you encounter strange character encoding in paths, check if your shell is using UTF-8, as non-standard characters in file names can also trigger path resolution failures.

Instructions in CLAUDE.md provide a workaround

Your CLAUDE.md file is the best place to give the agent permanent instructions about your Windows environment. You can add a section telling the agent to always use forward slashes for the Edit and Write tools. This helps the agent avoid the habit of using Windows-style backslashes which can lead to errors during tool execution. Explicitly stating that the project lives on a specific drive can also help when the agent needs to reason about the file system.

When the agent reads this file at the start of a session, it gains a better understanding of the local constraints. You should also list common file paths in this file using forward slashes to set a clear example for the agent to follow. This document acts as a persistent memory for the project, ensuring that every time you run claude --continue, the agent remembers the specific pathing rules required for your Windows setup.

Diagnostic commands reveal environment mismatches

When path errors persist despite your best efforts, use the claude doctor command from your terminal. This command checks the health of your installation and can identify issues with how your path environment variables are set up. Inside an active session, the /status command shows you what the agent currently thinks about the project. If the agent is trying to write to a path that looks corrupted or includes illegal characters, these diagnostic tools are the first step to seeing what the agent sees.

It allows you to verify that the agent has correctly identified the root of your project and has the necessary permissions. These internal checks are vital for debugging silent failures in file access. If the doctor command reports issues with tool availability, it might be because Windows has not added the necessary binary folders to your system PATH. Ensuring that the agent can find its own sub-tools is a prerequisite for successful file system operations.

Managing Windows path quirks across multiple projects

Managing Windows path quirks across multiple projects can be a mental burden. If you work on several repositories, each might have its own path resolution quirks depending on whether it uses WSL or native Windows. Managing these separate sessions in standard terminal windows becomes messy when you have to remember which environment needs which fix. This is where adhdTerminal provides a cleaner workflow by letting you run these sessions side by side as tiles.

You can name a tile for a specific project and see at a glance if the agent is stuck on a file error or waiting for your input. Each tile has a colour and a number to help you keep track of different repo structures. This tiled view makes it much easier to monitor several agents without losing context. If one project requires a specific terminal setup for paths, you can keep that session open and isolated from your other work in its own dedicated tile on the wall.

Global settings for consistent Windows behavior

For fixes that you want to apply to every project on your machine, edit the settings.json file located in your user profile directory at ~/.claude/settings.json. You can set default permission modes here, such as acceptEdits or plan, to control how much autonomy the agent has over your file system. If you find that the agent often fails to find its own configuration, ensure that your HOME environment variable is correctly set in Windows so it can locate the .claude directory.

The native adhdTerminal app can also help here by providing a consistent interface for these sessions across your Windows or macOS machines. Keeping your global settings clean ensures that every new session starts with the best possible path configuration. This saves time whenever you initialize a new project folder with the /init command. By centralizing your path preferences, you reduce the likelihood of encountering the same Windows-specific errors across different development environments.

Questions people ask

Why does Claude Code use forward slashes on Windows?

The agent relies on a toolset that follows Unix conventions for file paths. Forward slashes are generally safer because they do not act as escape characters in shell commands. Using them prevents the agent from misinterpreting a directory name as a special character sequence.

How do I stop the agent from looking in the wrong drive?

Always start the agent by running the command claude from the specific project directory you want to work in. If the agent still tries to access other drives, add a rule to your CLAUDE.md file that restricts its scope. You can also use the .gitignore file to block access to paths outside your project root.

Can I change the default path behavior for all my projects?

Yes, you can modify the global configuration file located at ~/.claude/settings.json in your user directory. Adding path preferences or tool permissions here will apply to every session you start on that computer. This is useful for setting a consistent environment across different terminal emulators.

Read next

More on when it goes wrong·All posts