Ferramenta Bash

A ferramenta bash permite que o Claude execute comandos de shell em uma sessão bash persistente, possibilitando operações de 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 exclusivamente via shell, o Claude apresenta ganhos significativos de desempenho com acesso a uma sessão bash persistente.



Visão geral

A ferramenta bash fornece ao Claude:

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

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



Casos de uso

• Fluxos de trabalho de desenvolvimento: Executar comandos de build, testes e ferramentas de desenvolvimento
• Automação de sistema: Executar scripts, gerenciar arquivos, automatizar tarefas
• Processamento de dados: Processar arquivos, executar scripts de análise, gerenciar conjuntos de dados
• Configuração de ambiente: Instalar pacotes, configurar ambientes



Início rápido



Como funciona

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

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



Parâmetros

*Obrigatório, a menos que esteja usando restart



Exemplo: Automação em várias etapas

O Claude pode encadear comandos para concluir tarefas complexas:

User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Claude's tool uses:
1. Install package
   {"command": "pip install requests"}

2. Create 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. Run script
   {"command": "python fetch_joke.py"}

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



Implementar a ferramenta bash

A ferramenta bash é implementada como uma ferramenta sem esquema. Ao usar essa ferramenta, você não precisa fornecer um esquema de entrada como em outras ferramentas; o esquema está incorporado ao modelo do Claude e não pode ser modificado.



Tratar erros

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



Seguir as melhores práticas de implementação



Segurança



Principais recomendações

• 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 a execução de comandos



Preços

A ferramenta bash adiciona 245 tokens de entrada às suas chamadas de API.

Tokens adicionais são consumidos por:

• Saídas de comando (stdout/stderr)
• Mensagens de erro
• Conteúdos de arquivos grandes

Consulte preços de uso de ferramentas para obter 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

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

• Capturar uma linha de base: Antes de qualquer trabalho do agente começar, faça commit do estado atual. Esse é o ponto de partida conhecido como bom.
• Commit por funcionalidade: Cada funcionalidade concluída recebe seu próprio commit. Eles servem como pontos de rollback caso algo dê errado mais tarde.
• Reconstruir 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.
• Reverter em caso de falha: Se o trabalho sair dos trilhos, git checkout reverte para o último commit bom em vez de tentar depurar um estado quebrado.



Operações de arquivo

• Processar dados: wc -l *.csv && ls -lh *.csv
• Pesquisar arquivos: find . -name "*.py" | xargs grep "pattern"
• Criar backups: tar -czf backup.tar.gz ./data



Tarefas de sistema

• Verificar 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 lidar com vim, less ou prompts de senha
• Sem aplicações GUI: Apenas linha de comando
• Escopo da sessão: O estado da sessão bash fica do lado do cliente. A API é stateless. Sua aplicação é responsável por manter a sessão de shell entre os turnos.
• Limites de saída: Saídas grandes podem ser truncadas
• Sem streaming: Resultados retornados após a conclusão



Combinando com outras ferramentas

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



Próximos passos