Toolofficial publisher

bash (Anthropic, côté client)

Tool : A precise action the AI can call · requires anthropic-api

Claude requests shell commands that your code executes.

Essential for code agents; your code must handle filtering and confinement.

Docs

Overall score

6.4 /10

Security: serious reservations

Utility

8.0

Reliability

6.0

Security

Serious reservations

Ease

5 min · Technical

Security reflects where data goes, requested permissions and incidents on record at the verification date. It is not a guarantee of zero risk: check the deployment mode and the connections you enable.

What it does, concretely

Automating command-line tasks from an AI agent raises a concrete question: who actually runs the commands, and in which environment? The bash tool addresses this by clearly separating responsibilities: Claude formulates the command, and your application executes it in a bash process it fully controls.

In practice, when you include the tool in a request, Claude responds with a tool_use block containing the command to run. Your code executes that command in a persistent bash session, then returns stdout and stderr in a tool_result block. The session stays alive between calls: the working directory, environment variables, and any files created are preserved from one call to the next.

This tool is aimed at developers building code agents, automation pipelines, or data analysis tools via the Anthropic API. It covers use cases such as running tests, installing packages, processing files, or configuring an environment.

It is not suitable for use without isolation: every command runs on your infrastructure with your permissions. Without a container or virtual machine and without an allowlist of permitted commands, the risk of unintended execution is real.

What it offers

·Persistent bash session: the working directory, environment variables, and created files are preserved between calls.
·Client-side execution: Claude proposes the command, your code runs it and returns the result, without Claude accessing your system directly.
·Parallel tool calls: Claude can return multiple tool_use blocks in a single response, to be run in order within the same session.
·Session restart: the restart parameter kills the bash process and starts a fresh one.
·Structured error reporting: the is_error field in tool_result signals to Claude that a command failed, along with the corresponding message.
·Timeout handling: your code can enforce a time limit per command and restart the session if it hangs.
·Compatible with all current Claude models via version bash_20250124, with no beta header required.

Our tips

Use an allowlist of permitted commands rather than a blocklist: a blocklist cannot anticipate every dangerous command.
Add a timeout to every command and kill the entire process group (shell and children) on expiry, then restart the session to avoid permanent blocking.
Always return stdout and stderr together in tool_result: error messages then appear where they occurred, helping Claude diagnose problems.
When Claude returns multiple tool_use blocks in a single response, run them in order in the same session and return all results in a single user message.
Run the bash session inside a container or virtual machine: that is the real security boundary, with command validation serving only as an additional safety net.

Watch out

Command allowlist validation does not catch operators attached to a word (for example cat data.txt|grep x is treated as a single token by the shlex parser): isolation inside a container remains essential.
The API is stateless: nothing about the bash session travels between requests, so your application is fully responsible for managing the shell process lifecycle.

In practice

Price: Free
Commercial use: Commercial use: yes
Available on: api
Host: anthropic-api
FR interface: No

Security and data

Rating: Security: serious reservations
Capabilities: readswritesexecutesnetwork
Your data: Data stays local
Maintenance: Active

Links and repository checked on 25 October 2026 · added on 1 January 2025

How to install bash (Anthropic, côté client)

1. Obtain an Anthropic API key at platform.claude.com. 2. Install the Python SDK: pip install anthropic 3. In your code, include {"type": "bash_20250124", "name": "bash"} in the tools array of your Messages request. 4. Create a persistent bash session in your application (a /bin/bash process kept alive between calls). 5. For each response with stop_reason tool_use, run the received command in your session and return the output in a tool_result block. 6. Security precaution: run the session inside an isolated container and apply a command allowlist before any execution.

pip install anthropic

Official documentation ↗

In the same category

Whole category Code →