Last updated 13 October 2026
Fix permission denied on macOS folders
The system blocks access to sensitive directories
When you run Claude Code on macOS Sonoma or Sequoia, you might encounter an error when the agent tries to use the Bash or Write tools. This usually happens because macOS protects certain parts of your file system from unauthorized software. If your project sits in the Documents, Desktop, or Downloads folders, the operating system requires explicit consent before any command line tool can modify files. You will often see an Operation not permitted message in your terminal window when the agent attempts to read a file or create a new directory.
The problem occurs because the agent runs as a process inside your terminal emulator. Even if you can manually run commands like touch or mkdir, the agent might still face restrictions if the operating system does not recognize the tool as a trusted entity. This is a common hurdle for developers who use modern coding agents that perform automated file operations. You must align the system level security settings with the requirements of the tool to ensure a smooth workflow without constant interruptions from the sandbox.
Granting Full Disk Access to the terminal
The most effective way to resolve permission issues is to provide Full Disk Access to your terminal application. Open the System Settings app on your Mac and navigate to the Privacy and Security section. Scroll down until you find the entry for Full Disk Access and click on it to see the list of approved applications. You need to find your preferred terminal emulator in this list and toggle the switch to the on position. This allows any process started within that terminal to bypass the standard folder protections for Documents and Desktop.
If you use the default Terminal app, look for it by name. If you use a third party terminal like iTerm2, Ghostty, or Warp, you must enable the setting for that specific application. You might need to enter your administrator password or use Touch ID to confirm the change. Once you have toggled the switch, you should restart your terminal session to ensure the new permissions take effect. This change gives the agent the freedom to use the Read, Write, and Edit tools across your entire user profile without triggering system alerts.
Managing file access through the binary path
In some cases, granting access to the terminal application does not satisfy the security requirements of macOS. The operating system sometimes tracks the specific binary that performs the file operations. If the agent still cannot write to your repository after you have enabled Full Disk Access for your terminal, you may need to add the node binary or the claude script directly to the permission list. You can find the exact path to the tool by typing which claude in your shell. This will print the location where the tool is installed on your machine.
To add a specific binary to the Full Disk Access list, click the plus icon at the bottom of the Privacy and Security window in System Settings. Use the file picker to navigate to the path you found earlier. If the folder is hidden, you can press Command+Shift+G and paste the path into the box to find it. Adding the tool directly ensures that macOS recognizes the agent as a trusted developer tool. This step is particularly useful if you work in a locked down environment where the terminal itself has limited rights.
Switching between internal permission modes
Claude Code has its own internal permission system that works on top of the macOS security layer. You can cycle through four different modes by pressing Shift+Tab while you are inside an active session. The default mode asks for your confirmation before the agent uses any tool that could change your files. The acceptEdits mode allows the agent to use the Write and Edit tools without asking, but it will still prompt you for other actions. This is a good balance for developers who want speed but still want to supervise shell commands.
The plan mode is a safe way to explore a project without making any changes. In this mode, the agent will describe the steps it wants to take but will not actually execute them. If you are confident in the task and want the agent to work autonomously, you can switch to the bypassPermissions mode. This mode allows the agent to run all tools, including Bash and Write, without stopping for a prompt. This is useful for large refactoring jobs where the agent needs to touch dozens of files in a single session.
Using project instructions for access control
You can guide the behavior of the agent by using project instruction files. A file named CLAUDE.md in the root of your repository can hold specific rules about which files the agent should prioritize or ignore. If you have a subdirectory that requires different handling, you can place a secondary CLAUDE.md file inside that folder. The agent reads these files to understand the context of your project and will respect the boundaries you set. This is a powerful way to prevent the agent from wandering into sensitive data folders or large build artifacts.
These instructions also help the agent use the Glob and Grep tools more effectively. By defining the structure of your project in CLAUDE.md, you reduce the number of trial and error attempts the agent makes when searching for code. You can also specify the preferred way to run tests or build the project. This reduces the chance of the agent running a Bash command that might trigger a permission warning or a system error. Clear instructions make the agent more efficient and less likely to hit the limits of your environment.
Organizing multiple high permission sessions
When you work on several projects at once, managing different permission levels can become a burden. You might want one session to have full bypassPermissions access for a migration, while another session stays in the default mode for safety. adhdTerminal is a native app for macOS and Windows that solves this by running many Claude Code sessions side by side as tiles on a wall. Each tile has a colour, a number, and a name, which makes it easy to track which project is running with high privileges and which one is restricted.
The tile interface shows you whether an agent is working, waiting for you, or idle. This is helpful when you are running several tasks that require long processing times. Tiles reopen in the same place after a restart and resume the same session automatically. If you need to step away from your desk, a free iPhone app mirrors the wall over an end to end encrypted link. You can use the mobile app to answer a prompt or send the next task to an agent while you are on the move, ensuring your work continues without delay.
Checking environment health with the doctor command
If you continue to experience issues with file access, you should check the integrity of your installation. Run the claude doctor command in your terminal to perform a diagnostic check on your environment. This command verifies that the tool is installed correctly and that it can reach the necessary services. It also checks your configuration files for any errors that might be causing the agent to behave unexpectedly. If the doctor command finds an issue, it will provide advice on how to fix it.
Sometimes the problem is not with the permissions but with an outdated version of the tool. You can run the claude update command to ensure you have the latest improvements and bug fixes. If your configuration becomes cluttered or you want to start fresh with your settings, you can use the /config command inside a session to view and modify your current parameters. Keeping your environment clean and updated reduces the friction between the agent and the macOS security sub-system.
Configuring tool specific permissions in settings
You can gain even finer control over permissions by editing the settings.json file. This file can exist at three levels: in your home directory at ~/.claude/settings.json for global rules, in the project root at .claude/settings.json, or in .claude/settings.local.json for untracked overrides. Within these files, you can define a permissions object that specifies which tools are allowed or denied. For example, you can allow the Read tool globally but require a prompt for the Write tool in specific projects.
This configuration method is ideal for teams that want to share a common security baseline. By checking a .claude/settings.json file into your repository, you ensure that every developer on the team uses the agent with the same safety constraints. You can also use the /permissions command inside a session to see the current state of these rules. Taking the time to set up these files prevents accidental changes to your codebase and gives you peace of mind when the agent is working on complex logic.
Questions people ask
How do I stop the agent if it starts making a mistake?
You can press the Escape key once to immediately interrupt the agent and stop its current action. If you need to undo a series of changes, pressing Escape twice will open a menu where you can select an earlier message to return to. You can also use Ctrl+C to quit the entire session and stop all background processes.
Why does the agent fail to read files even after I gave it Full Disk Access?
The agent respects your .gitignore file by default. If the files you are trying to access are ignored by git, the agent will not interact with them unless you change your project instructions. You should also check if the files are owned by a different user or have restricted read permissions at the Unix file system level.
Can I use the agent to modify system files outside my home directory?
You should avoid using the agent to modify system files as it does not have the ability to run commands with sudo or elevated root privileges. The agent is designed to work within your user space and your development repositories. Trying to modify system level files will likely result in a permission denied error that cannot be bypassed through the standard settings.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.