Outil Bash

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.

L'outil bash permet à Claude d'exécuter des commandes shell dans une session bash persistante, permettant les opérations système, l'exécution de scripts et l'automatisation en ligne de commande. L'accès au shell est une capacité fondamentale des agents. Sur Terminal-Bench 2.0, un benchmark qui évalue les tâches réelles du terminal en utilisant la validation uniquement par shell, Claude montre des gains de performance importants avec l'accès à une session bash persistante.

Aperçu

L'outil bash fournit à Claude :

Une session bash persistante qui maintient l'état
La capacité d'exécuter n'importe quelle commande shell
L'accès aux variables d'environnement et au répertoire de travail
Les capacités de chaînage de commandes et de script

Pour le support des modèles, consultez la Référence des outils.

Cas d'utilisation

Flux de travail de développement : Exécuter les commandes de build, les tests et les outils de développement
Automatisation système : Exécuter des scripts, gérer les fichiers, automatiser les tâches
Traitement des données : Traiter les fichiers, exécuter les scripts d'analyse, gérer les ensembles de données
Configuration de l'environnement : Installer les packages, configurer les environnements

Démarrage rapide

Fonctionnement

L'outil bash maintient une session persistante :

Claude détermine quelle commande exécuter
Vous exécutez la commande dans un shell bash
Retournez la sortie (stdout et stderr) à Claude
L'état de la session persiste entre les commandes (variables d'environnement, répertoire de travail)

Paramètres

Paramètre	Requis	Description
`command`	Oui*	La commande bash à exécuter
`restart`	Non	Définir à `true` pour redémarrer la session bash

*Requis sauf si vous utilisez restart

Exemple : Automatisation multi-étapes

Claude peut chaîner les commandes pour accomplir des tâches complexes :

Demande de l'utilisateur :
"Installer la bibliothèque requests et créer un simple script Python qui
récupère une blague à partir d'une API, puis l'exécuter."

L'outil de Claude utilise :
1. Installer le package
   {"command": "pip install requests"}

2. Créer le 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. Exécuter le script
   {"command": "python fetch_joke.py"}

La session maintient l'état entre les commandes, donc les fichiers créés à l'étape 2 sont disponibles à l'étape 3.

Implémenter l'outil bash

L'outil bash est implémenté comme un outil sans schéma. Lors de l'utilisation de cet outil, vous n'avez pas besoin de fournir un schéma d'entrée comme avec d'autres outils ; le schéma est intégré au modèle de Claude et ne peut pas être modifié.

Gérer les erreurs

Lors de l'implémentation de l'outil bash, gérez divers scénarios d'erreur :

Suivre les meilleures pratiques d'implémentation

Sécurité

L'outil bash fournit un accès direct au système. Implémentez ces mesures de sécurité essentielles :

Exécution dans des environnements isolés (Docker/VM)
Implémentation du filtrage des commandes et des listes blanches
Définition des limites de ressources (CPU, mémoire, disque)
Enregistrement de toutes les commandes exécutées

Recommandations clés

Utiliser ulimit pour définir les contraintes de ressources
Filtrer les commandes dangereuses (sudo, rm -rf, etc.)
Exécuter avec des permissions utilisateur minimales
Surveiller et enregistrer toute exécution de commande

Tarification

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

Consultez tarification de l'utilisation des outils pour les détails complets de la tarification.

Modèles courants

Flux de travail de développement

Exécuter les tests : pytest && coverage report
Construire les projets : npm install && npm run build
Opérations Git : git status && git add . && git commit -m "message"

Points de contrôle basés sur Git

Git sert de mécanisme de récupération structuré dans les flux de travail d'agents de longue durée, pas seulement un moyen de sauvegarder les modifications :

Capturer une ligne de base : Avant que tout travail d'agent ne commence, validez l'état actuel. C'est le point de départ connu et bon.
Valider par fonctionnalité : Chaque fonctionnalité complétée obtient son propre commit. Ceux-ci servent de points de restauration si quelque chose se passe mal plus tard.
Reconstruire l'état au démarrage de la session : Lire git log aux côtés d'un fichier de progression pour comprendre ce qui a déjà été fait et ce qui vient ensuite.
Revenir en cas d'échec : Si le travail tourne mal, git checkout revient au dernier bon commit au lieu d'essayer de déboguer un état cassé.

Opérations sur les fichiers

Traitement des données : wc -l *.csv && ls -lh *.csv
Recherche dans les fichiers : find . -name "*.py" | xargs grep "pattern"
Création de sauvegardes : tar -czf backup.tar.gz ./data

Tâches système

Vérification des ressources : df -h && free -m
Gestion des processus : ps aux | grep python
Configuration de l'environnement : export PATH=$PATH:/new/path && echo $PATH

Limitations

Pas de commandes interactives : Impossible de gérer vim, less ou les invites de mot de passe
Pas d'applications GUI : Ligne de commande uniquement
Portée de la session : L'état de la session bash est côté client. L'API est sans état. Votre application est responsable du maintien de la session shell entre les tours.
Limites de sortie : Les grandes sorties peuvent être tronquées
Pas de streaming : Résultats retournés après la fin

Combinaison avec d'autres outils

L'outil bash est plus puissant lorsqu'il est combiné avec l'éditeur de texte et d'autres outils.

Si vous utilisez également l'outil d'exécution de code, Claude a accès à deux environnements d'exécution séparés : votre session bash locale et le conteneur en bac à sable d'Anthropic. L'état n'est pas partagé entre eux. Consultez Utilisation de l'exécution de code avec d'autres outils d'exécution pour des conseils sur la façon d'inviter Claude à faire la distinction entre les environnements.

Étapes suivantes

Aperçu de l'utilisation des outils

En savoir plus sur l'utilisation des outils avec Claude

Outil éditeur de texte

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)

Configurer un environnement bash

Créer une session bash persistante avec laquelle Claude peut 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()

Gérer l'exécution des commandes

Créer une fonction pour exécuter les commandes et capturer la sortie :

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

Traiter les appels d'outils de Claude

Extraire et exécuter les commandes à partir des réponses 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,
        }

Implémenter les mesures de sécurité

Ajouter la validation et les restrictions. Utilisez une liste blanche plutôt qu'une liste noire, car les listes noires sont faciles à contourner. Rejeter les opérateurs shell afin que les commandes chaînées ne puissent pas contourner la liste blanche :

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

Cette vérification est une première ligne de défense. Pour une isolation plus forte, exécutez les commandes validées avec shell=False et passez shlex.split(command) comme liste d'arguments, afin que le shell n'interprète jamais la chaîne.

Aperçu

Cas d'utilisation

Démarrage rapide

Fonctionnement

Paramètres

Exemple d'utilisation

Exemple : Automatisation multi-étapes

Implémenter l'outil bash

Gérer les erreurs

Délai d'expiration de l'exécution de la commande

Commande non trouvée

Suivre les meilleures pratiques d'implémentation

Utiliser les délais d'expiration des commandes

Sécurité

Recommandations clés

Tarification

Modèles courants

Flux de travail de développement

Points de contrôle basés sur Git

Opérations sur les fichiers

Tâches système

Limitations

Combinaison avec d'autres outils

Étapes suivantes

Permission refusée

Maintenir l'état de la session

Gérer les grandes sorties

Enregistrer toutes les commandes

Assainir les sorties