Bash tool executes shell commands and returns their output. It is the primary way Claude interacts with your system — running builds, tests, git operations, package managers, and any other CLI tool.
The working directory persists between commands within a session, but shell state (variables, functions, aliases) does not carry over between separate Bash calls. The shell environment is initialized from the user’s profile (bash or zsh) at the start of each call.
Inputs
The shell command to execute. Multi-command pipelines,
&&-chained commands, and heredocs are all supported.Maximum time in milliseconds to wait before the command is killed. Defaults to 120,000 ms (2 minutes). The maximum allowed value is configurable but defaults to 600,000 ms (10 minutes).
When
true, runs the command as a background task. Claude is notified when the task completes rather than waiting for it inline. Only use this when the result is not needed immediately.When
true, runs the command outside the sandbox (if sandbox mode is active). Claude will only set this when a command has failed due to a sandbox restriction and the user has not explicitly restricted this override.Output
The tool returns the combined stdout and stderr of the command, along with the exit code. Long outputs may be truncated.Security features
TheBash tool includes several layers of security validation applied before a command is executed.
Destructive command warnings
Commands that are difficult or impossible to reverse display an informational warning in the permission dialog. The warning does not block the command — it is purely informational to help you make an informed decision. Examples of patterns that trigger warnings:git reset --hard— may discard uncommitted changesgit push --force— may overwrite remote historygit clean -f— may permanently delete untracked filesrm -rf— may delete files recursively and permanentlyDROP TABLE(in a SQL command) — may permanently destroy data
Path validation
Commands are parsed and validated for path-related constraints. Absolute paths that fall outside the current project are flagged and may require explicit approval.Read-only validation
When Claude is operating in a context that restricts writes, commands that would modify the filesystem are blocked before execution.Shell injection defense
The tool parses commands using a shell AST and blocks several categories of shell syntax that can be used to bypass permission rules:- Process substitutions:
<(),>() - Command substitutions:
$(),${} - Zsh-specific dangerous builtins:
zmodload,emulate,sysopen,sysread,syswrite - Heredocs inside command substitutions
- PowerShell comment syntax (
<#) as a defense-in-depth measure
Sandbox mode
When sandbox mode is enabled, commands run inside a restricted environment with controlled filesystem and network access. Filesystem restrictions are split into read and write configurations:read.denyOnly— paths that are blocked from readingwrite.allowOnly— only these paths can be written towrite.denyWithinAllow— exceptions within the write allowlist
allowedHosts— only these hosts are reachabledeniedHosts— these hosts are explicitly blocked
$TMPDIR environment variable is set to a writable sandbox directory. Always use $TMPDIR for temporary files rather than /tmp directly.
When a command fails due to a sandbox restriction, Claude will note the probable cause and explain that the user can adjust sandbox settings using /sandbox.
The
dangerouslyDisableSandbox parameter allows bypassing sandbox restrictions on a per-command basis. Claude defaults to running within the sandbox and only uses this override when there is clear evidence of sandbox-caused failure.Tool preferences
TheBash tool is a general-purpose fallback. Claude prefers dedicated tools for common operations because they provide a better experience and make it easier to review and approve specific operations:
| Task | Preferred tool |
|---|---|
| Find files by name | Glob |
| Search file contents | Grep |
| Read a file | Read |
| Edit a file | Edit |
| Write a new file | Write |
Bash for operations that don’t map to a dedicated tool — running test suites, building projects, executing scripts, git operations, and interacting with CLIs.
Permission behavior
EachBash command requires permission before it runs (unless a matching allow rule already exists). You can approve a command:
- Once — runs this time only
- For this session — auto-approved for the rest of the session
- Always — writes a permanent allow rule to project settings
Bash commands use prefix matching. Approving npm test also auto-approves future npm test --watch calls (since npm test is a prefix of the full command string).
--permission-mode effect
The --permission-mode CLI flag changes how Bash permissions are handled:
| Mode | Effect on Bash |
|---|---|
| Default | Each new command pattern requires approval |
acceptEdits | Filesystem commands (mkdir, touch, rm, mv, cp, sed) are auto-approved; other commands still require approval |
bypassPermissions | All commands are auto-approved |
Timeout behavior
If a command exceeds the timeout, it is killed and an error is returned to Claude. The default timeout is 120,000 ms (2 minutes). You can increase this up to the configured maximum by passing atimeout value.
For long-running commands (server processes, large builds), use run_in_background: true so Claude is not blocked waiting for completion.