> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jackdog668/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Bash tool

> Run shell commands from Claude. Covers inputs, timeouts, sandbox mode, security features, and permission behavior.

The `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

<ParamField body="command" type="string" required>
  The shell command to execute. Multi-command pipelines, `&&`-chained commands, and heredocs are all supported.
</ParamField>

<ParamField body="timeout" type="number">
  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).
</ParamField>

<ParamField body="run_in_background" type="boolean">
  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.
</ParamField>

<ParamField body="dangerouslyDisableSandbox" type="boolean">
  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.
</ParamField>

## Output

The tool returns the combined stdout and stderr of the command, along with the exit code. Long outputs may be truncated.

## Security features

The `Bash` 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 changes
* `git push --force` — may overwrite remote history
* `git clean -f` — may permanently delete untracked files
* `rm -rf` — may delete files recursively and permanently
* `DROP 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

<Warning>
  Even with these protections, you should review shell commands before approving them — especially commands that pipe output into further commands or use heredocs with dynamic content.
</Warning>

## 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 reading
* `write.allowOnly` — only these paths can be written to
* `write.denyWithinAllow` — exceptions within the write allowlist

**Network restrictions** can limit which hosts commands can connect to:

* `allowedHosts` — only these hosts are reachable
* `deniedHosts` — these hosts are explicitly blocked

**Temporary files:** When sandbox mode is active, the `$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`.

<Note>
  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.
</Note>

## Tool preferences

The `Bash` 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`        |

Use `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

Each `Bash` 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

Permission rules for `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 a `timeout` value.

For long-running commands (server processes, large builds), use `run_in_background: true` so Claude is not blocked waiting for completion.

## Example usage

<CodeGroup>
  ```bash Run tests theme={null}
  npm test
  ```

  ```bash Git status and diff in parallel theme={null}
  # Claude calls Bash twice in parallel:
  git status
  git diff
  ```

  ```bash Chain commands theme={null}
  mkdir -p src/components && touch src/components/Button.tsx
  ```

  ```bash Background long-running server theme={null}
  # With run_in_background: true
  npm run dev
  ```
</CodeGroup>