170 lines
6.0 KiB
Markdown
170 lines
6.0 KiB
Markdown
> ## Documentation Index
|
|
> Fetch the complete documentation index at: https://vineetagarwal-code-claude-code.mintlify.app/llms.txt
|
|
> Use this file to discover all available pages before exploring further.
|
|
|
|
# Bash
|
|
|
|
> Execute shell commands in a persistent bash session.
|
|
|
|
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.
|
|
</Note>
|
|
|
|
## Parameters
|
|
|
|
<ParamField body="command" type="string" required>
|
|
The shell command to execute. Supports all standard bash syntax including pipes, redirections, and compound operators (`&&`, `||`, `;`).
|
|
</ParamField>
|
|
|
|
<ParamField body="timeout" type="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.
|
|
</ParamField>
|
|
|
|
<ParamField body="description" type="string">
|
|
A short human-readable description of what the command does. Shown in the UI when Claude explains its actions.
|
|
</ParamField>
|
|
|
|
<ParamField body="run_in_background" type="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.
|
|
</ParamField>
|
|
|
|
## 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
|
|
|
|
| Setting | Default | Max |
|
|
| --------------- | ------------------- | --- |
|
|
| Default timeout | 120,000 ms (2 min) | — |
|
|
| Maximum timeout | 600,000 ms (10 min) | — |
|
|
|
|
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.
|
|
</Warning>
|
|
|
|
## Background execution
|
|
|
|
<Tabs>
|
|
<Tab title="Foreground (default)">
|
|
```json theme={null}
|
|
{
|
|
"command": "npm run build",
|
|
"description": "Build the project"
|
|
}
|
|
```
|
|
|
|
Claude waits for the command to finish and receives its output immediately.
|
|
</Tab>
|
|
|
|
<Tab title="Background">
|
|
```json theme={null}
|
|
{
|
|
"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.
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Examples
|
|
|
|
<Accordion title="Running tests">
|
|
```bash theme={null}
|
|
pytest tests/ -x --tb=short
|
|
```
|
|
|
|
Run a test suite and stop on the first failure.
|
|
</Accordion>
|
|
|
|
<Accordion title="Git operations">
|
|
```bash theme={null}
|
|
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.
|
|
</Note>
|
|
</Accordion>
|
|
|
|
<Accordion title="Installing dependencies">
|
|
```bash theme={null}
|
|
npm install
|
|
```
|
|
|
|
Standard package installation. Claude stages related commands in parallel when they are independent.
|
|
</Accordion>
|
|
|
|
<Accordion title="Long-running server with timeout override">
|
|
```json theme={null}
|
|
{
|
|
"command": "cargo build --release",
|
|
"timeout": 300000,
|
|
"description": "Release build (up to 5 min)"
|
|
}
|
|
```
|
|
|
|
Override the 2-minute default for commands known to take longer.
|
|
</Accordion>
|
|
|
|
## 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** |
|
|
|
|
|
|
Built with [Mintlify](https://mintlify.com). |