Bash tool runs shell commands and returns their output. Commands execute in a persistent bash session — the working directory is preserved between calls, though the shell state (variables, aliases, functions) is re-initialized from the user’s profile on each invocation.
Claude prefers dedicated tools (
Read, Edit, Glob, Grep) over Bash equivalents for file operations. Bash is reserved for tasks where no purpose-built tool applies.Parameters
The shell command to execute. Supports all standard bash syntax including pipes, redirections, and compound operators (
&&, ||, ;).Maximum execution time in milliseconds. Defaults to 120,000 ms (2 minutes). Maximum allowed value is 600,000 ms (10 minutes).Both values can be overridden at runtime via
BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS environment variables.A short human-readable description of what the command does. Shown in the UI when Claude explains its actions.
When
true, the command runs in the background. Claude is notified when it completes and does not need to poll for results. Do not append & to the command when using this parameter — background execution is handled internally.Session behavior
The bash session persists working directory across calls but does not persist:- Shell variables set in previous commands
- Aliases or functions
cdchanges (Claude uses absolute paths instead)
bash or zsh).
Timeouts
| Setting | Default | Max |
|---|---|---|
| Default timeout | 120,000 ms (2 min) | — |
| Maximum timeout | 600,000 ms (10 min) | — |
timeout value (in milliseconds) to override the default for a specific command.
Permission model
Every Bash command passes through a permission check before execution. The outcome is one of:- Allow — command matches an existing allow rule or is classified as read-only
- Ask — command requires user approval before running
- Deny — command matches an explicit deny rule and is blocked
Allow rules
Rules are matched by exact command, prefix (git commit:*), or wildcard pattern. Safe wrapper commands (timeout, time, nice, nohup) and safe environment variable assignments (NODE_ENV=prod, GOARCH=arm64) are stripped before matching so prefix rules work correctly.
Read-only auto-allow
Commands that only read state (e.g.,ls, cat, git log, grep) are automatically allowed without a prompt.
Security restrictions
Claude’s security layer checks each command for patterns that commonly indicate injection or obfuscation attempts. Commands containing the following require explicit user approval:- Command substitution:
`...`,$(),${} - Process substitution:
<(),>() - Input/output redirections (
<,>) in suspicious contexts - Zsh-specific constructs:
zmodload,emulate -c,ztcp,zsocket - ANSI-C quoting (
$'...') or locale quoting ($"...") - IFS variable manipulation (
$IFS) - Access to
/proc/*/environ - Newlines or carriage returns in non-quoted positions
Background execution
- Foreground (default)
- Background
Examples
Running tests
Running tests
Git operations
Git operations
Claude follows a strict protocol for
git commit and git push — it never amends pushed commits, never skips hooks with --no-verify, and never force-pushes to main/master without explicit user instruction.Installing dependencies
Installing dependencies
Long-running server with timeout override
Long-running server with timeout override
Tool preference
Claude uses Bash only when no purpose-built tool is available:| 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 |
| Shell commands, builds, tests | Bash |