Try free

Last updated 13 October 2026

Fix Claude Code symlink reading errors

The nature of symlink errors in the agent console

You might encounter a situation where the agent tells you a file does not exist, even though you can see it in your terminal. This discrepancy often happens because of how symbolic links are handled by the tools inside Claude Code. When you use the command claude to start a session, the agent creates a map of your project. If it encounters a symbolic link that points to a location outside the current directory, it might treat the link as a broken path to maintain a security sandbox.

The agent relies on tools like Read and Glob to interact with your files. These tools are designed to respect the boundaries of your project root. If a symlink points to a file that is not part of the current repo, the agent may report that it cannot find the target. This behavior prevents the agent from accidentally reading or modifying sensitive system files that were not intended to be part of the coding session. You can identify this issue if the agent successfully lists the link using the Bash tool but fails to open it with the Read tool.

You can check if the agent is struggling with your filesystem structure by running the /doctor command within your session. This internal diagnostic check looks for common issues with permissions and environment setup. If the agent has insufficient permissions to follow links, the /doctor command will often highlight these gaps. You should also verify that the link is not pointing to a location that requires administrative privileges that the terminal session does not possess.

Ignore files and their impact on path visibility

Claude Code respects your .gitignore file and other ignore patterns by default. If your symbolic link points to a directory or a file that is listed in your ignore configuration, the Glob tool will not see it. This is a common source of frustration when developers link to a node-modules folder or a build directory that they have excluded from version control. The agent assumes that if a file is ignored by git, it should also be ignored during the coding task to avoid cluttering the context window.

To fix this, you can check your local settings in .claude/settings.json or your global settings in ~/.claude/settings.json. Look for the permissions section to see if there are specific rules blocking certain paths. You do not need to remove the item from .gitignore if you want to keep your repo clean. Instead, you can explicitly tell the agent to look at a specific path by using the /add-dir command. This command forces the agent to include a directory in its current context even if it was previously hidden by ignore rules.

If the agent still fails to resolve the link, you should check for a .claude/settings.local.json file. This file holds overrides that apply only to your local machine and are not tracked by the repository. It is a good place to put paths that are specific to your local development environment. By adding the target of your symlinks to the local settings, you allow the agent to follow those paths without affecting how other developers interact with the same project.

Project instructions for link handling

The CLAUDE.md file is your primary tool for guiding the agent on how to handle project-specific quirks. If your project relies heavily on symbolic links, you should document this in the root CLAUDE.md file. Provide a section that explains which directories are linked and where their actual targets reside. This gives the agent a mental model of the filesystem that goes beyond what it can discover through simple directory traversal.

You can also create a subdirectory CLAUDE.md if the symlink issues are limited to a specific part of your project tree. The agent reads these files to understand the local context. For example, if you have a library folder that links to a shared internal repo, tell the agent in the CLAUDE.md file to use the Bash tool to verify the contents of that folder before it attempts to use the Read tool. This proactive instruction prevents the agent from getting stuck in a loop of file-not-found errors.

Another useful strategy is to define custom slash commands in the .claude/commands folder. You can create a markdown file that defines a command specifically for resolving project links. When you run this custom command, it can trigger a sequence of Bash and Glob operations that verify the integrity of your symlinks. This approach automates the troubleshooting process and ensures the agent always has an up-to-date view of the linked files.

Verifying links with the Bash tool

The Bash tool is the most direct way to debug symlink issues because it interacts with the underlying operating system shell. If the agent is confused about a file, you can prompt it to run a command like ls -l on the specific path. This forces the agent to see the output from the shell, which includes the link target. Once the agent sees the link target in the shell output, it often realizes that the file is actually available.

Sometimes the agent tries to use the Edit or Write tool on a symbolic link directly. This can fail if the tool expects a regular file rather than a link. If you see the agent struggling to modify a file, check if it is trying to overwrite the link itself instead of the target file. You can tell the agent to find the real path of the link using the shell and then perform the edit on that absolute path. This bypasses the ambiguity that symlinks can introduce for the agent tools.

If the symlink is broken, the agent will see a red highlight or a missing file error in the shell output. You can then use the agent to fix the link. Ask it to use the Bash tool to remove the broken link and create a new one using the correct relative path. Relative paths are always better than absolute paths because they are more likely to work across different developer environments and within the agent's restricted view of the filesystem.

Managing session context with adhdTerminal

When you are dealing with complex filesystem issues, your conversation history can quickly become cluttered with error messages and shell output. This is where adhdTerminal becomes a useful part of your workflow. You can run many Claude Code sessions side by side on a single wall. Each session is a tile that you can name and color. You might have one tile dedicated to fixing the symlink structure of your project while another tile focuses on the actual feature code you are writing.

The wall in adhdTerminal shows you the last exchanges of each conversation at a glance. If the session dedicated to symlink repair is waiting for your input, you will see it immediately. This allows you to maintain focus on your main task while the agent works on the infrastructure in a separate tile. Because the tiles reopen in the same place after a restart, you do not lose your progress if you need to reboot your machine or move to a different workspace.

Using adhdTerminal also gives you a visual indicator of which sessions are idle and which are working. If an agent gets stuck in a loop trying to read a broken link, you will see the activity indicator on the tile. You can then quickly jump into that tile, press Escape to interrupt the agent, and provide a corrective prompt. This multi-session approach prevents a single filesystem error from blocking your entire development process.

Relative versus absolute paths in configuration

Absolute paths are a frequent cause of failure for Claude Code. If a symbolic link points to /Users/yourname/projects/my-file.txt, the agent will fail if it is running on a different machine or if the project is mounted in a different location. Even within the same machine, the agent might have trouble resolving absolute paths if they fall outside the root directory it was initialized in. You should always convert these to relative paths like ../../my-file.txt whenever possible.

You can use the Grep and Glob tools to search your entire project for absolute symlinks. Ask the agent to find any link that starts with a forward slash and replace it with a relative path. This makes the project more portable and much easier for the agent to navigate. The agent is specifically optimized to understand the hierarchy of the current working directory, and relative paths fit perfectly into that model.

If you must use paths that sit outside your project root, consider using the MCP server configuration. You can run claude mcp to manage servers that provide the agent with access to external filesystems or specialized tools. An MCP server can be configured in .mcp.json to handle the resolution of external links in a way that the standard file tools cannot. This is a more structured way to give the agent access to shared libraries or global configuration files.

Permission modes and tool access

The permission mode you are using affects how the agent interacts with symbolic links. There are four modes: default, acceptEdits, plan, and bypassPermissions. You can cycle through these modes using Shift+Tab inside a session. If you are in plan mode, the agent will describe what it intends to do with a file before it tries to read it. This is helpful for debugging symlink issues because you can see if the agent is planning to use the wrong path before it actually fails.

In bypassPermissions mode, the agent has more freedom to execute tools without asking for your approval every time. While this can speed up your work, it also means the agent might spend more credits trying to resolve a broken link if it gets stuck. You should use the /cost and /usage commands regularly to monitor your spend if you are letting the agent perform large-scale filesystem repairs. If the agent is failing repeatedly to read a link, it will still consume tokens for every attempt.

You can also restrict or allow specific tools in your .claude/settings.json file under the permissions key. If you find that the agent is consistently failing to use the Read tool on links, you might want to ensure that the Bash tool is fully enabled. The Bash tool serves as a reliable fallback for any operation where the higher-level coding tools struggle with filesystem abstraction. Giving the agent the ability to use standard shell commands is often the fastest way to resolve path ambiguity.

Persistence and session recovery

If you resolve a symlink issue and want to ensure the agent remembers the fix, use the /memory command. This allows the agent to store important project details so they persist across different parts of the conversation. You can also use /compact to summarize the session once the links are fixed. This frees up space in the context window while keeping the essential information about your filesystem structure available for future prompts.

When you start a new session using claude --continue, the agent carries on with the most recent context. If that context includes the successful resolution of your symlinks, the agent will be much more efficient. If you need to jump back to an older session where you had a specific filesystem configuration, use claude --resume to see a list of earlier sessions. This history is vital when you are working on complex refactors that involve moving linked directories around.

The adhdTerminal app makes this persistence even more powerful by mirroring your wall to a free iPhone app. The link is end to end encrypted, allowing you to check on the status of a long-running filesystem task from your phone. You can even send a prompt or the next task to the agent while you are away from your desk. This ensures that your Claude Code sessions remain productive even when you are not actively sitting at your computer to monitor the terminal output.

Questions people ask

Why does Claude Code say a file is missing when I can see it in my repo?

This usually happens because the file is a symbolic link pointing to a location outside the project root or it is being ignored by your .gitignore file. The agent respects security boundaries and version control rules, which can make certain links invisible to its Read and Glob tools. You can fix this by adding the path to your CLAUDE.md instructions or using the /add-dir command.

Can I force the agent to follow a specific symlink that it is ignoring?

Yes, you can use the Bash tool to read the file manually or provide explicit instructions in your .claude/settings.json file. You can also tell the agent the exact target path of the link so it can use the Read tool on the actual file instead of the link. Mentioning the link in the root CLAUDE.md file is the best way to ensure the agent understands its purpose.

What is the best way to fix broken symlinks using the agent?

Prompt the agent to use the Bash tool to find broken links by running shell commands that check for file existence. Once identified, ask the agent to recreate the links using relative paths instead of absolute ones. This ensures that the links remain valid even if the project is moved or accessed by different tools within the Claude Code environment.

Read next

More on when it goes wrong·All posts