Last updated 13 October 2026
Allow Claude Code to run shell scripts
Claude Code hits a wall with shell scripts
When you ask Claude Code to run a local shell script, the agent often responds with a message saying it lacks the permission to execute that tool. You might see a tool execution denied error appearing in your terminal window instead of the expected output. This happens because the agent defaults to a cautious security model to prevent it from making destructive changes to your system without your oversight. You expect the Bash tool to handle these scripts, but the environment stops the process before it can start to protect your files and configuration.
The problem usually appears when you have a custom build script, a database migration, or a deployment automation file that you want the agent to trigger. The agent identifies that it needs to use the Bash tool but finds that the current session settings do not allow for the execution of those specific commands. This interruption breaks the flow of your development work and forces you to manually copy and paste commands into a separate terminal window. You can fix this by adjusting the permission levels or the configuration files that govern how the agent interacts with your local shell environment.
Adjust the session permission mode
The fastest way to resolve an execution error is to change the permission mode within your active session. Claude Code operates in different modes that control how much freedom it has to use tools like Bash or Write. You can see the current mode in the interface and cycle through the available options by pressing Shift and Tab together. The default mode requires the agent to ask for your consent for every significant action. Moving to a more permissive mode can silence these interruptions for the duration of the current session.
Switching to the bypassPermissions mode gives the agent the highest level of freedom. In this mode, the agent can execute scripts using the Bash tool without waiting for you to approve every single step. This is useful for complex refactoring tasks where the agent needs to run a test suite or a script repeatedly to verify changes. You should be aware that this mode removes the safety checks that prevent accidental system changes. Use it only when you are working in a repository you trust and you have a clear view of what the script does.
Configure tool permissions in settings files
For a more permanent fix that survives across different sessions, you need to edit the settings files. Claude Code looks for a file named settings.json inside a directory called .claude in your project root. You can also find a global settings file in your home directory at ~/.claude/settings.json. These files contain a section for permissions where you can explicitly allow or deny specific tools. Adding the Bash tool to the allowed list in these JSON files ensures that the agent can run scripts without asking for permission every time you start a new session.
If you want to keep your project settings clean but change the behavior on your specific machine, use the .claude/settings.local.json file. This file acts as an override for the project-level settings and is typically ignored by version control systems. By defining the Bash tool permissions here, you grant yourself the ability to run scripts while keeping the default security settings for the rest of your team. This approach balances the need for speed with the requirement for a secure and consistent shared codebase across multiple developer environments.
Use project instructions to guide script execution
Setting permissions is only half of the solution. You also need to tell the agent how and when it should use your scripts to avoid errors. This is where the CLAUDE.md file becomes essential. This file sits in the root of your repository and serves as the primary manual for the agent. You can write clear instructions in this file about which shell scripts are safe to run and what parameters they require. When the agent reads this file at the start of a session, it understands the context of your automation tools and follows your established workflows.
In your CLAUDE.md, describe the purpose of each script and the expected outcome. For example, if you have a script for database migrations, explain that it should be run every time a schema file changes. This prevents the agent from guessing how to use your tools and reduces the chance of errors that might trigger a permission block. If you have a large project with different scripts in different folders, you can place a separate CLAUDE.md in a subdirectory to provide localized instructions for that specific part of the tree, which the agent will respect when working in those folders.
Monitor script execution with adhdTerminal
When you run many scripts across different branches or projects, keeping track of which terminal is doing what becomes difficult. This is a situation where adhdTerminal provides a better way to work. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. Instead of hiding your active sessions in background tabs, it runs many Claude Code sessions side by side, each one a tile on a wall. You can see at a glance if a script is still working or if the agent is waiting for your input because of a permission prompt.
The tile system in adhdTerminal also helps you manage long running scripts. Each tile has a colour, a number, and a name, and shows whether the session is working, waiting for you, done, or idle. Tiles reopen in the same place after a restart and resume the same session. A free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task. It costs 99 dollars once, and one key runs one computer at a time and can be moved, with a 7 day free trial and no account required.
Troubleshoot tool errors with internal commands
If your scripts still refuse to run after you have adjusted the settings, you should use the built-in diagnostic tools. The command claude doctor is the first thing you should run in your terminal. It checks your installation and the environment to ensure everything is configured correctly. It can identify if there are issues with your path or if the agent cannot find the necessary shell binaries. This command often reveals simple configuration mistakes that prevent the Bash tool from functioning as expected within the agent environment.
Another useful command inside an active session is /status. This slash command shows you the current state of the agent, including which files it has read and what permissions are currently active. If you find that the agent is confused about the environment, you can use /clear to start the session over in the same folder. This resets the internal state without closing the terminal entirely. If you have been working for a long time and the context window is full of old script output, use /compact to summarize the session and free up space for new commands.
Manage subagents for complex scripting tasks
Sometimes a single script is part of a larger task that requires more specialized logic. Claude Code allows you to define subagents using markdown files in the .claude/agents directory. You can create a subagent specifically designed to handle shell scripts and automation. This subagent can have its own set of instructions and a narrower focus, which makes it less likely to make mistakes when executing complex shell commands. You invoke these subagents from within your main session to delegate specific scripting work to them.
When a subagent runs, it follows the same permission rules as the main agent. However, by isolating the script execution to a subagent, you can better control the flow of information. You can use the /agents command to see which specialized helpers are available to you in the current project. If a subagent finishes its task or hits an error, the main session receives a notification. This modular approach is particularly helpful when you are automating repetitive tasks that involve multiple steps across different parts of your project.
Security considerations for local script execution
Allowing an AI agent to execute shell scripts on your local machine carries inherent risks. The agent has the same level of access to your file system as the terminal it is running in. This is why Claude Code respects your .gitignore file and will not touch files that you have explicitly told git to ignore unless you provide specific instructions. You should always review what the agent is planning to do by using the /review command before it executes a long sequence of commands. This gives you a chance to spot potentially dangerous operations before they happen.
If you are concerned about the agent making changes you cannot undo, ensure your work is committed to a git repository before you start a session. You can use the /permissions command to check the current tool settings and make sure you have not accidentally granted more access than you intended. While features like bypassPermissions are convenient for speed, they should be used with caution. The goal is to create a workflow where the agent can be productive without compromising the stability or security of your local development environment.
Resume and carry on with previous sessions
A development task involving scripts often spans several hours or days. You do not want to re-configure your permissions and instructions every time you open your terminal. You can use the command claude --continue to pick up exactly where you left off in the most recent session in your current folder. This carries over the context and the permission state of that session. If you need to go back to an even earlier task, the command claude --resume provides a list of your previous sessions so you can select the one you need from the list.
Inside a session, you can also use the /resume command to switch between different tasks without leaving the interactive interface. This is helpful when you are testing scripts in different branches and need to jump back and forth between them. By maintaining the continuity of your sessions, you ensure that the agent remains familiar with your scripting environment. This reduces the friction of managing tool permissions and allows you to focus on the actual code instead of the configuration of your agent every time you start your computer.
Questions people ask
How do I stop a script that is running out of control?
You can press the Escape key once to interrupt what the agent is doing. If the script is stuck or you need to shut down the session immediately, pressing Ctrl+C will quit the entire session and return you to your main shell.
Can I allow only specific shell commands while blocking others?
You can manage tool permissions in the settings.json file within your .claude directory. While the agent uses the Bash tool for scripts, you can specify in the permissions section which tools are allowed or denied. This gives you granular control over what the agent can execute without manual approval.
Why does Claude Code say it cannot find my script file?
The agent relies on tools like Glob and Grep to find files and it respects your .gitignore rules. If your script is ignored by git, the agent will not see it unless you explicitly add the directory using the /add-dir command. Check that the file path is correct and that the agent has the necessary read permissions for that folder.
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.
- 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.
- Claude Code cannot edit system filesHandle permission errors that occur when Claude Code attempts to modify files outside of the immediate project directory or in protected paths.