Herramienta bash

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

Compatibilidad de modelos

Modelo	Versión de herramienta
Modelos Claude 4 y Sonnet 3.7 (deprecated)	`bash_20250124`

Las versiones anteriores de herramientas no están garantizadas para ser compatibles hacia atrás con modelos más nuevos. Siempre usa la versión de herramienta que corresponde a tu versión de modelo.

Casos de uso

Flujos de trabajo de desarrollo: Ejecutar comandos de compilació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

Cómo funciona

La herramienta bash mantiene una sesión persistente:

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

Parámetros

Parámetro	Requerido	Descripción
`command`	Sí*	El comando bash a ejecutar
`restart`	No	Establece en `true` para reiniciar la sesión bash

*Requerido a menos que uses restart

Ejemplo: Automatización de múltiples pasos

Claude puede encadenar comandos para completar tareas complejas:

# Solicitud del usuario
"Install the requests library and create a simple Python script that fetches a joke from an API, then run it."

# La herramienta de Claude usa:
# 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.

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

Usa ulimit para establecer restricciones de recursos
Filtra comandos peligrosos (sudo, rm -rf, etc.)
Ejecuta con permisos de usuario mínimos
Monitorea y registra 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

Consulta precios de uso de herramientas para obtener detalles completos de precios.

Patrones comunes

Flujos de trabajo de desarrollo

Ejecutar pruebas: pytest && coverage report
Compilar proyectos: npm install && npm run build
Operaciones de Git: git status && git add . && git commit -m "message"

Operaciones de archivos

Procesar datos: wc -l *.csv && ls -lh *.csv
Buscar archivos: find . -name "*.py" | xargs grep "pattern"
Crear copias de seguridad: 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 a API
Límites de salida: Las salidas grandes pueden truncarse
Sin streaming: Resultados devueltos después de la finalización

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

Descripción general del uso de herramientas

Aprende sobre el uso de herramientas con Claude

import anthropic

client = anthropic.Anthropic()

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

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

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 tiempo de espera
    output = self._read_output(timeout=10)
    return output

Procesar las llamadas de herramientas de Claude

Extrae y ejecuta 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 = "Bash session restarted"
        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
        }

Implementar medidas de seguridad

Añade 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"Command contains dangerous pattern: {pattern}"
    
    # Añadir más validación según sea necesario
    return True, None

Descripción general

Compatibilidad de modelos

Casos de uso

Inicio rápido

Cómo funciona

Parámetros

Ejemplo de uso

Ejemplo: Automatización de múltiples pasos

Implementar la herramienta bash

Manejar errores

Tiempo de espera de ejecución de comando

Comando no encontrado

Seguir las mejores prácticas de implementación

Usar tiempos de espera de comando

Seguridad

Recomendaciones clave

Precios

Patrones comunes

Flujos de trabajo de desarrollo

Operaciones de archivos

Tareas del sistema

Limitaciones

Combinar con otras herramientas

Próximos pasos

Permiso denegado

Mantener el estado de la sesión

Manejar salidas grandes

Registrar todos los comandos

Desinfectar salidas