Ferramenta Bash

ConstruirFerramentas

Ferramenta Bash

Permita que Claude execute comandos shell em uma sessão bash persistente para automação de linha de comando e operações do sistema.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

A ferramenta bash permite que Claude execute comandos shell em uma sessão bash persistente, possibilitando operações do sistema, execução de scripts e automação de linha de comando. O acesso ao shell é uma capacidade fundamental de agentes. No Terminal-Bench 2.0, um benchmark que avalia tarefas reais de terminal usando validação apenas com shell, Claude mostra ganhos de desempenho significativos com acesso a uma sessão bash persistente.

Visão geral

A ferramenta bash fornece a Claude:

Sessão bash persistente que mantém estado
Capacidade de executar qualquer comando shell
Acesso a variáveis de ambiente e diretório de trabalho
Capacidades de encadeamento de comandos e scripting

Para suporte de modelo, consulte a Referência de ferramentas.

Casos de uso

Fluxos de trabalho de desenvolvimento: Execute comandos de compilação, testes e ferramentas de desenvolvimento
Automação de sistema: Execute scripts, gerencie arquivos, automatize tarefas
Processamento de dados: Processe arquivos, execute scripts de análise, gerencie conjuntos de dados
Configuração de ambiente: Instale pacotes, configure ambientes

Início rápido

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Como funciona

A ferramenta bash mantém uma sessão persistente:

Claude determina qual comando executar
Você executa o comando em um shell bash
Retorna a saída (stdout e stderr) para Claude
O estado da sessão persiste entre comandos (variáveis de ambiente, diretório de trabalho)

Parâmetros

Parâmetro	Obrigatório	Descrição
`command`	Sim*	O comando bash a executar
`restart`	Não	Defina como `true` para reiniciar a sessão bash

*Obrigatório a menos que esteja usando restart

Exemplo: Automação em múltiplas etapas

Claude pode encadear comandos para completar tarefas complexas:

Solicitação do usuário:
"Instale a biblioteca requests e crie um script Python simples que
busca uma piada de uma API, depois execute-o."

A ferramenta de Claude usa:
1. Instale o pacote
   {"command": "pip install requests"}

2. Crie o script
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Execute o script
   {"command": "python fetch_joke.py"}

A sessão mantém estado entre comandos, então arquivos criados na etapa 2 estão disponíveis na etapa 3.

Implemente a ferramenta bash

A ferramenta bash é implementada como uma ferramenta sem schema. Ao usar esta ferramenta, você não precisa fornecer um schema de entrada como com outras ferramentas; o schema é incorporado ao modelo de Claude e não pode ser modificado.

Configure um ambiente bash

Crie uma sessão bash persistente com a qual Claude possa interagir:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Manipule a execução de comandos

Crie uma função para executar comandos e capturar saída:

def execute_command(self, command):
    # Send command to bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Capture output with timeout
    output = self._read_output(timeout=10)
    return output

Processe as chamadas de ferramenta de Claude

Extraia e execute comandos das respostas de Claude:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implemente medidas de segurança

Adicione validação e restrições. Use uma lista de permissões em vez de uma lista de bloqueio, já que listas de bloqueio são fáceis de contornar. Rejeite operadores shell para que comandos encadeados não possam passar pela lista de permissões:

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Allow only commands from an explicit allowlist
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Reject shell operators that would chain additional commands
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Esta verificação é uma primeira linha de defesa. Para isolamento mais forte, execute comandos validados com shell=False e passe shlex.split(command) como a lista de argumentos, para que o shell nunca interprete a string.

Manipule erros

Ao implementar a ferramenta bash, manipule vários cenários de erro:

Siga as melhores práticas de implementação

Segurança

A ferramenta bash fornece acesso direto ao sistema. Implemente estas medidas de segurança essenciais:

Execução em ambientes isolados (Docker/VM)
Implementação de filtragem de comandos e listas de permissões
Definição de limites de recursos (CPU, memória, disco)
Registro de todos os comandos executados

Recomendações principais

Use ulimit para definir restrições de recursos
Filtre comandos perigosos (sudo, rm -rf, etc.)
Execute com permissões mínimas de usuário
Monitore e registre toda execução de comando

Preços

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

Command outputs (stdout/stderr)
Error messages
Large file contents

Consulte preços de uso de ferramentas para detalhes completos de preços.

Padrões comuns

Fluxos de trabalho de desenvolvimento

Executar testes: pytest && coverage report
Compilar projetos: npm install && npm run build
Operações Git: git status && git add . && git commit -m "message"

Checkpointing baseado em Git

Git serve como um mecanismo de recuperação estruturado em fluxos de trabalho de agentes de longa duração, não apenas uma forma de salvar alterações:

Capture uma linha de base: Antes de qualquer trabalho do agente começar, faça commit do estado atual. Este é o ponto de partida conhecido como bom.
Commit por recurso: Cada recurso concluído recebe seu próprio commit. Estes servem como pontos de reversão se algo der errado depois.
Reconstrua o estado no início da sessão: Leia git log junto com um arquivo de progresso para entender o que já foi feito e o que vem a seguir.
Reverta em caso de falha: Se o trabalho der errado, git checkout reverte para o último commit bom em vez de tentar depurar um estado quebrado.

Operações de arquivo

Processamento de dados: wc -l *.csv && ls -lh *.csv
Pesquisa de arquivos: find . -name "*.py" | xargs grep "pattern"
Criação de backups: tar -czf backup.tar.gz ./data

Tarefas do sistema

Verificação de recursos: df -h && free -m
Gerenciamento de processos: ps aux | grep python
Configuração de ambiente: export PATH=$PATH:/new/path && echo $PATH

Limitações

Sem comandos interativos: Não pode manipular vim, less ou prompts de senha
Sem aplicações GUI: Apenas linha de comando
Escopo de sessão: O estado da sessão bash é do lado do cliente. A API é sem estado. Sua aplicação é responsável por manter a sessão shell entre turnos.
Limites de saída: Saídas grandes podem ser truncadas
Sem streaming: Resultados retornados após conclusão

Combinando com outras ferramentas

A ferramenta bash é mais poderosa quando combinada com o editor de texto e outras ferramentas.

Se você também estiver usando a ferramenta de execução de código, Claude tem acesso a dois ambientes de execução separados: sua sessão bash local e o contêiner em sandbox da Anthropic. O estado não é compartilhado entre eles. Consulte Usando execução de código com outras ferramentas de execução para orientação sobre como instruir Claude a distinguir entre ambientes.

Próximos passos

Visão geral de uso de ferramentas

Saiba mais sobre uso de ferramentas com Claude

Ferramenta editor de texto

Visualize e edite arquivos de texto com Claude

Was this page helpful?

ConstruirFerramentas

Ferramenta Bash

Permita que Claude execute comandos shell em uma sessão bash persistente para automação de linha de comando e operações do sistema.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Visão geral

A ferramenta bash fornece a Claude:

Sessão bash persistente que mantém estado
Capacidade de executar qualquer comando shell
Acesso a variáveis de ambiente e diretório de trabalho
Capacidades de encadeamento de comandos e scripting

Para suporte de modelo, consulte a Referência de ferramentas.

Casos de uso

Fluxos de trabalho de desenvolvimento: Execute comandos de compilação, testes e ferramentas de desenvolvimento
Automação de sistema: Execute scripts, gerencie arquivos, automatize tarefas
Processamento de dados: Processe arquivos, execute scripts de análise, gerencie conjuntos de dados
Configuração de ambiente: Instale pacotes, configure ambientes

Início rápido

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Como funciona

A ferramenta bash mantém uma sessão persistente:

Claude determina qual comando executar
Você executa o comando em um shell bash
Retorna a saída (stdout e stderr) para Claude
O estado da sessão persiste entre comandos (variáveis de ambiente, diretório de trabalho)

Parâmetros

Parâmetro	Obrigatório	Descrição
`command`	Sim*	O comando bash a executar
`restart`	Não	Defina como `true` para reiniciar a sessão bash

*Obrigatório a menos que esteja usando restart

Exemplo: Automação em múltiplas etapas

Claude pode encadear comandos para completar tarefas complexas:

Solicitação do usuário:
"Instale a biblioteca requests e crie um script Python simples que
busca uma piada de uma API, depois execute-o."

A ferramenta de Claude usa:
1. Instale o pacote
   {"command": "pip install requests"}

2. Crie o script
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Execute o script
   {"command": "python fetch_joke.py"}

A sessão mantém estado entre comandos, então arquivos criados na etapa 2 estão disponíveis na etapa 3.

Implemente a ferramenta bash

Configure um ambiente bash

Crie uma sessão bash persistente com a qual Claude possa interagir:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Manipule a execução de comandos

Crie uma função para executar comandos e capturar saída:

def execute_command(self, command):
    # Send command to bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Capture output with timeout
    output = self._read_output(timeout=10)
    return output

Processe as chamadas de ferramenta de Claude

Extraia e execute comandos das respostas de Claude:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implemente medidas de segurança

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Allow only commands from an explicit allowlist
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Reject shell operators that would chain additional commands
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Manipule erros

Ao implementar a ferramenta bash, manipule vários cenários de erro:

Siga as melhores práticas de implementação

Segurança

A ferramenta bash fornece acesso direto ao sistema. Implemente estas medidas de segurança essenciais:

Execução em ambientes isolados (Docker/VM)
Implementação de filtragem de comandos e listas de permissões
Definição de limites de recursos (CPU, memória, disco)
Registro de todos os comandos executados

Recomendações principais

Use ulimit para definir restrições de recursos
Filtre comandos perigosos (sudo, rm -rf, etc.)
Execute com permissões mínimas de usuário
Monitore e registre toda execução de comando

Preços

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

Command outputs (stdout/stderr)
Error messages
Large file contents

Consulte preços de uso de ferramentas para detalhes completos de preços.

Padrões comuns

Fluxos de trabalho de desenvolvimento

Executar testes: pytest && coverage report
Compilar projetos: npm install && npm run build
Operações Git: git status && git add . && git commit -m "message"

Checkpointing baseado em Git

Git serve como um mecanismo de recuperação estruturado em fluxos de trabalho de agentes de longa duração, não apenas uma forma de salvar alterações:

Capture uma linha de base: Antes de qualquer trabalho do agente começar, faça commit do estado atual. Este é o ponto de partida conhecido como bom.
Commit por recurso: Cada recurso concluído recebe seu próprio commit. Estes servem como pontos de reversão se algo der errado depois.
Reconstrua o estado no início da sessão: Leia git log junto com um arquivo de progresso para entender o que já foi feito e o que vem a seguir.
Reverta em caso de falha: Se o trabalho der errado, git checkout reverte para o último commit bom em vez de tentar depurar um estado quebrado.

Operações de arquivo

Processamento de dados: wc -l *.csv && ls -lh *.csv
Pesquisa de arquivos: find . -name "*.py" | xargs grep "pattern"
Criação de backups: tar -czf backup.tar.gz ./data

Tarefas do sistema

Verificação de recursos: df -h && free -m
Gerenciamento de processos: ps aux | grep python
Configuração de ambiente: export PATH=$PATH:/new/path && echo $PATH

Limitações

Sem comandos interativos: Não pode manipular vim, less ou prompts de senha
Sem aplicações GUI: Apenas linha de comando
Escopo de sessão: O estado da sessão bash é do lado do cliente. A API é sem estado. Sua aplicação é responsável por manter a sessão shell entre turnos.
Limites de saída: Saídas grandes podem ser truncadas
Sem streaming: Resultados retornados após conclusão

Combinando com outras ferramentas

A ferramenta bash é mais poderosa quando combinada com o editor de texto e outras ferramentas.

Próximos passos

Visão geral de uso de ferramentas

Saiba mais sobre uso de ferramentas com Claude

Ferramenta editor de texto

Visualize e edite arquivos de texto com Claude

Was this page helpful?

Visão geral

Casos de uso

Início rápido

Como funciona

Parâmetros

Exemplo de uso

Exemplo: Automação em múltiplas etapas

Implemente a ferramenta bash

Manipule erros

Tempo limite de execução de comando

Comando não encontrado

Permissão negada

Siga as melhores práticas de implementação

Use tempos limite de comando

Mantenha o estado da sessão

Manipule saídas grandes

Registre todos os comandos

Sanitize outputs

Segurança

Recomendações principais

Preços

Padrões comuns

Fluxos de trabalho de desenvolvimento

Checkpointing baseado em Git

Operações de arquivo

Tarefas do sistema

Limitações

Combinando com outras ferramentas

Próximos passos

Visão geral

Casos de uso

Início rápido

Como funciona

Parâmetros

Exemplo de uso

Exemplo: Automação em múltiplas etapas

Implemente a ferramenta bash

Manipule erros

Tempo limite de execução de comando

Comando não encontrado

Permissão negada

Siga as melhores práticas de implementação

Use tempos limite de comando

Mantenha o estado da sessão

Manipule saídas grandes

Registre todos os comandos

Sanitize outputs

Segurança

Recomendações principais

Preços

Padrões comuns

Fluxos de trabalho de desenvolvimento

Checkpointing baseado em Git

Operações de arquivo

Tarefas do sistema

Limitações

Combinando com outras ferramentas

Próximos passos