La herramienta bash permite a Claude ejecutar comandos de shell en una sesión bash persistente, permitiendo operaciones del sistema, ejecución de scripts y automatización de línea de comandos.

Descripción general

La herramienta bash proporciona a Claude:

  • Sesión bash persistente que mantiene el estado
  • Capacidad de ejecutar cualquier comando de shell
  • Acceso a variables de entorno y directorio de trabajo
  • Capacidades de encadenamiento de comandos y scripting

Versiones de herramientas

ModeloVersión de Herramienta
Claude 4 & Sonnet 3.7bash_20250124
Claude Sonnet 3.5bash_20241022

Claude Sonnet 3.5 requiere el encabezado beta computer-use-2024-10-22 al usar la herramienta bash.

La herramienta bash está generalmente disponible en Claude 4 y Sonnet 3.7.

Casos de uso

  • Flujos de trabajo de desarrollo: Ejecutar comandos de construcción, pruebas y herramientas de desarrollo
  • Automatización del sistema: Ejecutar scripts, gestionar archivos, automatizar tareas
  • Procesamiento de datos: Procesar archivos, ejecutar scripts de análisis, gestionar conjuntos de datos
  • Configuración del entorno: Instalar paquetes, configurar entornos

Inicio rápido

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "bash_20250124",
            "name": "bash"
        }
    ],
    messages=[
        {"role": "user", "content": "Lista todos los archivos Python en el directorio actual."}
    ]
)

Cómo funciona

La herramienta bash mantiene una sesión persistente:

  1. Claude determina qué comando ejecutar
  2. Ejecutas el comando en un shell bash
  3. Devuelves la salida (stdout y stderr) a Claude
  4. El estado de la sesión persiste entre comandos (variables de entorno, directorio de trabajo)

Parámetros

ParámetroRequeridoDescripción
commandSí*El comando bash a ejecutar
restartNoEstablecer en true para reiniciar la sesión bash

*Requerido a menos que se use restart

Ejemplo: Automatización de múltiples pasos

Claude puede encadenar comandos para completar tareas complejas:

# Solicitud del usuario
"Instala la biblioteca requests y crea un script Python simple que obtenga un chiste de una API, luego ejecútalo."

# Usos de herramientas de Claude:
# 1. Instalar paquete
{"command": "pip install requests"}

# 2. Crear 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. Ejecutar script
{"command": "python fetch_joke.py"}

La sesión mantiene el estado entre comandos, por lo que los archivos creados en el paso 2 están disponibles en el paso 3.


Implementar la herramienta bash

La herramienta bash se implementa como una herramienta sin esquema. Al usar esta herramienta, no necesitas proporcionar un esquema de entrada como con otras herramientas; el esquema está integrado en el modelo de Claude y no se puede modificar.

1

Configurar un entorno bash

Crea una sesión bash persistente con la que Claude pueda interactuar:

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()
2

Manejar la ejecución de comandos

Crea una función para ejecutar comandos y capturar la salida:

def execute_command(self, command):
    # Enviar comando a bash
    self.process.stdin.write(command + '\n')
    self.process.stdin.flush()
    
    # Capturar salida con timeout
    output = self._read_output(timeout=10)
    return output
3

Procesar las llamadas de herramientas de Claude

Extraer y ejecutar comandos de las respuestas 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 = "Sesión bash reiniciada"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)
        
        # Devolver resultado a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }
4

Implementar medidas de seguridad

Agregar validación y restricciones:

def validate_command(command):
    # Bloquear comandos peligrosos
    dangerous_patterns = ['rm -rf /', 'format', ':(){:|:&};:']
    for pattern in dangerous_patterns:
        if pattern in command:
            return False, f"El comando contiene un patrón peligroso: {pattern}"
    
    # Agregar más validación según sea necesario
    return True, None

Manejar errores

Al implementar la herramienta bash, maneja varios escenarios de error:

Seguir las mejores prácticas de implementación

Seguridad

La herramienta bash proporciona acceso directo al sistema. Implementa estas medidas de seguridad esenciales:

  • Ejecutar en entornos aislados (Docker/VM)
  • Implementar filtrado de comandos y listas de permitidos
  • Establecer límites de recursos (CPU, memoria, disco)
  • Registrar todos los comandos ejecutados

Recomendaciones clave

  • Usar ulimit para establecer restricciones de recursos
  • Filtrar comandos peligrosos (sudo, rm -rf, etc.)
  • Ejecutar con permisos mínimos de usuario
  • Monitorear y registrar toda la ejecución de comandos

Precios

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

Ver precios de uso de herramientas para detalles completos de precios.

Patrones comunes

Flujos de trabajo de desarrollo

  • Ejecutar pruebas: pytest && coverage report
  • Construir proyectos: npm install && npm run build
  • Operaciones Git: git status && git add . && git commit -m "mensaje"

Operaciones de archivos

  • Procesar datos: wc -l *.csv && ls -lh *.csv
  • Buscar archivos: find . -name "*.py" | xargs grep "patrón"
  • Crear respaldos: tar -czf backup.tar.gz ./data

Tareas del sistema

  • Verificar recursos: df -h && free -m
  • Gestión de procesos: ps aux | grep python
  • Configuración del entorno: export PATH=$PATH:/new/path && echo $PATH

Limitaciones

  • Sin comandos interactivos: No puede manejar vim, less, o solicitudes de contraseña
  • Sin aplicaciones GUI: Solo línea de comandos
  • Alcance de sesión: Persiste dentro de la conversación, se pierde entre llamadas API
  • Límites de salida: Las salidas grandes pueden ser truncadas
  • Sin streaming: Los resultados se devuelven después de completarse

Combinar con otras herramientas

La herramienta bash es más poderosa cuando se combina con el editor de texto y otras herramientas.

Próximos pasos