Bash

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

Note: 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

• command (string) — The shell command to execute. Supports all standard bash syntax including pipes, redirections, and compound operators (&&, ||, ;).

• timeout (number) — 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.

• description (string) — A short human-readable description of what the command does. Shown in the UI when Claude explains its actions.

• run_in_background (boolean) — 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
• cd changes (Claude uses absolute paths instead)

Claude initializes each session from the user's shell profile (bash or zsh).

Timeouts

Pass a 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

Warning: Commands are split into subcommands before permission checking. A rule like Bash(ls:*) will not match ls /tmp && rm -rf / — the rm -rf / subcommand is checked separately.

Background execution

Foreground (default)

    {
      "command": "npm run build",
      "description": "Build the project"
    }
    ```

    Claude waits for the command to finish and receives its output immediately.


  #### Background

```json
    {
      "command": "npm run dev",
      "description": "Start dev server",
      "run_in_background": true
    }
    ```

    The command starts and Claude continues without blocking. A notification arrives when the process finishes.


## Examples

#### Running tests

```bash
  pytest tests/ -x --tb=short

Run a test suite and stop on the first failure.

Git operations

  git status && git diff --staged

Check working tree status and staged changes in a single compound command.

Note: 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

  npm install

Standard package installation. Claude stages related commands in parallel when they are independent.

Long-running server with timeout override

  {
    "command": "cargo build --release",
    "timeout": 300000,
    "description": "Release build (up to 5 min)"
  }

Override the 2-minute default for commands known to take longer.

Tool preference

Claude uses Bash only when no purpose-built tool is available: