Try free

Last updated 13 October 2026

Claude Code cannot read local files

The agent operates from a specific working directory

Claude Code reports a file does not exist even when you can see it in your editor. This usually happens because the agent is working from a root directory that differs from your mental model of the project. If you started the session in a subdirectory, the agent might not have the correct context for relative paths. Use the command claude from the true root of your repository to ensure the agent has a clear view of the entire tree.

Check if the file is truly accessible to the user running the terminal. If you are using a virtual file system or a containerized environment, the path the agent sees might not match your host OS. The agent uses tools like Bash and Read to interact with your disk. If these tools return an error, the agent concludes the file is missing rather than recognizing a permission issue. Ensure the terminal has the necessary access rights to the folders you are working in.

Permission modes dictate how the agent uses tools

The agent operates under specific permission modes that dictate what it can do without your input. If you are in plan mode, the agent might only describe what it wants to do without actually invoking the Read tool to see the file content. Use Shift+Tab to cycle through modes like default or acceptEdits to ensure the agent has the necessary authority to examine your source code. You can see the current mode in the interface while the session is active.

You can also check your settings.json file inside the .claude folder. Look for the permissions section to see if certain tools are restricted. If the Read tool is denied for specific paths, the agent will act as if those files are inaccessible. Modifying these settings allows the agent to fetch the data it needs to assist with your task. You can also use /config inside a session to inspect how these permissions are currently applied to your environment.

Ignore files and search limits hide valid paths

Claude Code respects your .gitignore file by default. If the file you want it to read is listed in your ignore rules, the agent will skip it during its discovery phase. This is common with configuration files that contain secrets or large build artifacts. If you need the agent to analyze a file that is currently ignored, you must temporarily remove it from the ignore list or explicitly tell the agent to use the Read tool on that specific path using a direct instruction.

The agent also uses the Glob and Grep tools to find files. These tools might fail to find your file if it is located in a deeply nested directory that exceeds the default search depth of the agent. If the agent cannot find a file through search, try providing the exact path in your prompt. This helps the agent bypass the search logic and go directly to the target file without relying on automated discovery which can sometimes be limited by project size.

Project instructions guide the discovery process

The CLAUDE.md file in your project root is the best place to define how paths should be handled. If your project has a non-standard structure, such as a monorepo with multiple packages, the agent might get lost. Write specific instructions in CLAUDE.md to explain where important files are located and how the agent should navigate the directory tree. This file acts as a permanent guide that the agent reads at the start of the session.

You can also place a CLAUDE.md file in a subdirectory to provide localized context. This is useful for large projects where different modules have different conventions. When the agent enters that directory, it reads the local instructions. This ensures the agent uses the correct path resolution logic for that specific part of the code base. Using instructions effectively reduces the time the agent spends searching for files that are already known to you.

Terminal commands help verify what the agent sees

If the agent insists a file does not exist, use the Bash tool yourself or ask the agent to run a simple list command. Seeing the output of a directory listing helps you and the agent align on the current state of the file system. If the file appears in the list but the agent cannot read it, the problem is likely related to file encoding or a lock held by another process. The agent relies on these tool outputs to build its understanding of your workspace.

Sometimes the issue is as simple as a typo in the file name or an incorrect case in a case-sensitive file system. Since the agent relies on the tools you provide, any mismatch in the environment will lead to a failure. Running claude doctor can help identify issues with the environment that might be affecting the ability of the agent to interact with your files. It checks for common installation problems and configuration errors that might block file access.

Managing multiple project contexts across sessions

When you work on multiple projects or different branches of the same project, file paths can become confusing. If you switch folders and run claude --continue, the agent might still be operating with the context of a different directory. It is better to use claude --resume to pick the specific session that matches your current working directory to avoid path conflicts. This ensures the history and file paths are consistent with your current task.

For developers managing several distinct tasks at once, adhdTerminal provides a way to keep these contexts separate. It runs Claude Code sessions in side-by-side tiles, where each tile corresponds to a specific project folder. This prevents you from accidentally asking the agent to read a file that only exists in another branch or repository. Each tile maintains its own view of the file system, which reduces the chance of path resolution errors because each session is tied to a unique visual space.

Context window and memory limits affect visibility

The agent has a limited context window that fills up as it reads files and stores conversation history. If you have asked the agent to read many large files, it might eventually drop older information to make room for new data. Use the /compact command to summarize the session and free up space. This ensures the agent retains the most relevant information about your project structure without losing track of the files it has already processed.

If the agent seems to have forgotten a file it read earlier, you can use the /memory command to see what it currently remembers. This gives you insight into the internal state of the agent. If the file is missing from memory, you will need to ask the agent to read it again. Keeping your sessions focused on specific tasks helps prevent the context window from becoming a bottleneck for file access and overall performance during long coding sessions.

Global configuration and local overrides

Your user settings in ~/.claude/settings.json apply to every project you work on. If you have a global setting that restricts file access, it will affect every session. Check your home directory for any CLAUDE.md or settings files that might be imposing strict limits on the agent. These global instructions are powerful but can cause unexpected behavior if you forget they are there. They are the first place to look for system wide file reading issues.

If you need to override project settings for your local machine only, use the .claude/settings.local.json file. This file is for your own untracked overrides. It is a good place to put path configurations that are specific to your local development environment. This keeps your project repository clean while giving you the flexibility to fix path resolution issues on your own machine without affecting other developers on your team.

Troubleshooting while away from the terminal

When you are away from your desk, you might need to check if a task has finished or if the agent is stuck on a file error. The adhdTerminal iPhone app mirrors your wall of tiles over an end to end encrypted link. You can see if a specific session is waiting for your input because it could not find a file. This allows you to provide the correct path or a new instruction from your phone without needing to be at your computer.

Being able to send a prompt to the agent from your mobile device means you can resolve path issues without being tied to your workstation. If the agent reports a missing file while you are out, you can quickly type the correct location or tell it to skip that file. This keeps your development process moving forward even when you are not actively sitting at your computer. The app ensures you are always informed about the status of your background coding tasks.

Questions people ask

Can Claude Code access files outside the current project root?

The agent is generally restricted to the directory where you started the session to prevent unauthorized access. If you need it to see files in a sibling folder, you should start the session from a common parent directory. This allows the agent to use the Glob and Read tools across the entire relevant directory tree.

Why does the agent say a file is empty when I know it has content?

This often happens when the agent does not have permission to read the file or if the file is locked by another application. Use the Bash tool to run a command like cat on the file to see if the terminal itself can access the content. If the Bash tool fails to show content, you must resolve the file permissions in your operating system.

How do I make the agent ignore specific large directories to save context?

You should add those directories to your .gitignore file or configure the ignore settings in .claude/settings.json. This prevents the agent from wasting context space scanning files that are not relevant to your current coding tasks. Reducing the search space also makes the Glob and Grep tools much more efficient during file discovery.

Read next

More on when it goes wrong·All posts