Try free

Last updated 13 October 2026

Fix Claude Code permission denied errors

Operating system file access rules

Claude Code runs as a local process in your terminal. If your terminal application does not have the right to access the filesystem, the agent will return errors when it tries to use the Read or Write tools. On macOS, this often happens if you have not granted Full Disk Access to your terminal emulator or the specific shell you use. You might see a generic permission denied message even if the file exists and the path is correct. Check your system privacy settings to ensure your terminal has permission to touch the folders where your code lives.

Windows users face similar issues with execution policies or folder ownership. If you run the claude command in a folder where your user account lacks write access, the agent cannot create its own temporary files or modify your source code. You must ensure that the user account running the terminal has full control over the project directory. If you are working in a system directory or a location managed by another service, you might need to move your project to a user-owned directory to avoid constant access denied errors from the operating system.

Managing internal permission modes

The agent has several built-in permission modes that dictate how much it can do without your input. These modes are default, acceptEdits, plan, and bypassPermissions. If you find the agent is constantly asking for permission to run a simple Bash command or to use the Edit tool, you are likely in the default mode. This mode is safe but can be slow for experienced developers who trust the agent. You can cycle through these modes by pressing Shift+Tab while the session is active. Switching to bypassPermissions allows the agent to execute tools without waiting for your manual approval on every step.

It is important to understand that these modes only exist within the session. They do not override your operating system permissions. If the OS denies an action, the agent will fail regardless of which internal mode you have selected. Use the plan mode when you want the agent to describe what it wants to do before it attempts any changes. This gives you a chance to spot potential permission issues or dangerous commands before the agent tries to execute them in your shell. The mode you choose is visible in the interface so you always know the current level of autonomy the agent has.

Configuring tool permissions in settings

You can define granular rules for how the agent uses specific tools in your configuration files. Claude Code looks for a file named settings.json inside the .claude directory of your project. It also checks for a global configuration at ~/.claude/settings.json. Inside these files, you can use the permissions key to set default behaviors for different tools like Bash, Write, or NotebookEdit. If a tool is explicitly denied in your settings, the agent will report a permission error whenever it tries to perform that action. Check both your local and global settings to ensure you have not accidentally disabled a tool you need.

The hierarchy of settings is important for troubleshooting. Project-level settings in .claude/settings.json will override your global user settings. If you share a repository with a team and someone has checked in a restrictive settings file, your agent will follow those rules even if your global config is more permissive. You can also create a .claude/settings.local.json file for your own untracked overrides. This is the best place to put your personal preferences for permission levels if you want to keep them separate from the main project configuration. Verify these files if the agent behaves differently across different repositories.

Filesystem ownership and shell execution

The Bash tool is one of the most powerful capabilities of the agent, but it is also the most likely to hit permission errors. When the agent runs a command, it uses your current shell environment. If your shell does not have the necessary environment variables or if it requires a password for certain operations, the agent will fail. This is common when trying to run package managers or system-level scripts. The agent cannot provide a password to a sudo prompt. You must ensure that the commands the agent needs to run are executable by your current user without interactive password entry.

Check the ownership of your files using standard shell commands. If a file was created by a different user or a root process, the agent will not be able to use the Edit or Write tools on it. This often happens in projects that use containerization where files might be mapped to the host with different permissions. Use your shell to change the owner or the mode of the files so the agent can work. If you frequently hit these issues, examine your terminal setup to see if you are running in a restricted shell environment that limits what child processes can do.

Version control and ignored files

Claude Code is designed to respect your .gitignore file. If you ask the agent to read or edit a file that is listed in your ignore rules, it may report that the file is inaccessible or does not exist. This is a safety feature to prevent the agent from accidentally modifying sensitive files like environment variables or build artifacts. If you need the agent to work with an ignored file, you have to temporarily remove that file from .gitignore or specifically tell the agent that it is allowed to access it. The Glob and Read tools will strictly follow these exclusion rules by default.

This behavior can sometimes look like a permission error because the agent refuses to touch the file. If you are certain the operating system permissions are correct but the agent still cannot see the file, check your project root for .gitignore. Also look for any CLAUDE.md files in the repository. A CLAUDE.md file can contain project instructions that tell the agent to avoid certain directories or file types. If the agent is instructed to stay out of a folder, it will behave as if it lacks the permission to enter that part of the file tree.

Visualizing session state with adhdTerminal

Keeping track of permission requests across multiple projects is easier when you can see the state of every session at once. adhdTerminal displays your Claude Code sessions as tiles on a wall. Each tile shows whether the agent is currently working, waiting for your input, or sitting idle. When a session hits a permission gate in default mode, the tile clearly indicates that it is waiting for you. This prevents you from leaving an agent stuck for hours because you did not notice a permission prompt buried in one of many open terminal tabs.

The app is a native solution for macOS and Windows that helps you manage these parallel workflows. Since each tile preserves its place and name, you can dedicate specific tiles to tasks that you know require bypassPermissions mode. You can see the last few lines of the conversation on the tile itself, which often includes the specific error message or permission request the agent just generated. This visual overview makes it much simpler to jump into the right context and provide the necessary approval or fix the underlying filesystem issue.

Diagnostic tools and session resets

If you are unsure why the agent is failing, use the built-in diagnostic commands. Running claude doctor from your terminal will check the health of your installation and your basic environment. This can identify issues with your path or missing dependencies that might cause permission-like symptoms. Inside a session, you can use the /doctor command to get specific information about the current state of the agent and its tools. This report can help you identify if a specific tool is being blocked by your configuration.

Sometimes a session can get into a state where it consistently fails due to previous permission errors or a cluttered context window. In these cases, use the /clear command to start the conversation over in the same folder. This does not delete your files but it wipes the agent's memory of the current conversation. If the agent has built up a set of incorrect assumptions about what it is allowed to do, clearing the session often fixes the problem. You can also use /compact to summarize the session if the context window is getting too full, which can sometimes resolve issues where the agent is confused by a long history of failed attempts.

Handling tasks through the mobile app

The free adhdTerminal iPhone app adds a layer of flexibility for handling permission requests when you are not at your computer. It mirrors your wall of tiles over an end to end encrypted link. If an agent starts a task that requires your approval, you can see the notification on your phone. You can then send a short prompt or approve the next task directly from the app. This is particularly useful for long-running scripts that might hit a permission prompt halfway through while you are away from your desk.

This mobile mirroring ensures that your development process does not stop just because you stepped away. You can monitor the progress of multiple tiles and respond to permission gates as they happen. If an agent reports a filesystem error, you can read the headline of the problem on your phone and decide if it is something you need to fix immediately or if you can give the agent a different instruction to bypass the problematic directory. This connection keeps you in control of the agent's permissions without requiring you to stay tethered to your workstation.

Directory specific instructions and subagents

Permissions can also be influenced by the structure of your project. If you have a CLAUDE.md file in a subdirectory, the instructions in that file apply specifically to that part of the tree. A subagent defined in .claude/agents might also have its own set of rules. If you find that the agent has permissions in the root of the project but fails in a specific folder, check for these local instruction files. They might contain directives that restrict the agent's use of the Edit or Write tools in that specific area to prevent accidental changes to critical code.

The agent also respects a global instruction file at ~/.claude/CLAUDE.md. If you have set broad restrictions there, they will follow you across every project you work on. This is a common source of confusion when you move from a personal project to a work project and find the agent is refusing to perform certain tasks. Review your global instructions to ensure they are not too restrictive for your current needs. By balancing global rules with project-specific settings and internal permission modes, you can create a workflow that is both secure and efficient.

Questions people ask

How can I make the agent stop asking for permission on every file edit?

You can switch to bypassPermissions mode by pressing Shift+Tab until that mode is selected. Alternatively, you can modify your settings.json file to set the default permission for the Edit tool to allowed. This will let the agent modify files without a manual prompt for each change.

Why does the agent say it cannot find a file that I can see in my terminal?

The agent likely cannot see the file because it is listed in your .gitignore file. Claude Code respects your git rules and will ignore any files that are not tracked or are explicitly excluded. To fix this, you must either remove the file from .gitignore or use a configuration that allows the agent to see ignored files.

What should I do if claude doctor reports a permission error?

A permission error in the doctor report usually means the agent cannot access its own configuration directory or the necessary terminal utilities. Check that your user has read and write access to the ~/.claude directory. You may also need to ensure that your terminal has Full Disk Access in your operating system's security settings.

Read next

More on claude code basics·All posts