Mode headless : faire tourner des agents sans interaction

En mode headless ou non-interactif, un agent IA tourne sans fenêtre de chat – idéal pour les scripts et la CI, mais sans pouvoir te poser de questions.

Ce que signifie headless

Normalement, tu discutes en direct avec un agent : il pose une question, tu réponds, il continue. En mode headless ou non-interactif, ce dialogue disparaît. Tu fournis un prompt en argument ou via un pipe, l'agent le traite et renvoie une seule réponse à la fin – sans question intermédiaire, sans fenêtre de chat.

À quoi ça ressemble dans Claude Code

La commande claude -p "Trouve et corrige le bug dans auth.py" démarre Claude Code en mode non-interactif. Tu peux aussi envoyer des données via un pipe : cat erreur.log | claude -p "Explique la cause". La sortie peut être récupérée en texte brut ou en JSON structuré (--output-format json), ce qui s'intègre bien dans des scripts.

À quoi ça sert

Traitement par lots (batch) : parcourir automatiquement de nombreux fichiers ou tickets
CI/CD : par exemple vérifier automatiquement chaque pull request pour des fautes de frappe ou des problèmes de sécurité
Tâches cron et automatisations planifiées, sans intervention humaine

Le risque : pas de questions en retour

La plus grande différence avec le mode interactif : l'agent ne peut pas te demander la permission ou une clarification. S'il tombe sur une situation où il demanderait normalement, il doit décider seul ou abandonner. C'est pourquoi le choix du mode de permissions (voir l'entrée dédiée) compte particulièrement en fonctionnement headless : sans règles claires, un agent peut soit faire trop peu (il abandonne sans cesse), soit trop (il exécute des actions risquées sans demander).

EXEMPLE

# Script CI : vérification des fautes de frappe pour chaque diff de PR git diff main | claude -p "Trouve les fautes de frappe dans ce diff. Pour chacune, indique 'fichier:ligne' et le problème, rien d'autre." --output-format json

🛠️ EXERCICE — À TOI DE JOUER

Construis un appel headless simple qui résume un fichier, et observe comment il se comporte sans pouvoir poser de questions.

Exécute dans un terminal : claude -p "Résume ce fichier en 3 phrases" --allowedTools "Read" avec un vrai fichier de ton projet.
Répète l'appel, mais indique un fichier qui n'existe pas – observe comment l'agent réagit sans demander (une erreur au lieu d'une question).
Essaie --output-format json et regarde le JSON résultant : quels champs contient-il en plus du texte lui-même ?

✅ AUTO-VÉRIFICATION

☐ As-tu pu expliquer pourquoi l'agent n'a pas simplement demandé, face au fichier manquant ?
☐ As-tu compris à quoi sert --allowedTools dans ce contexte ?
☐ Connais-tu les deux scénarios (batch, CI) de l'entrée où le fonctionnement headless a le plus de sens ?

QUIZ RAPIDE

Quel est le plus grand risque lorsqu'on fait tourner un agent en mode headless / non-interactif ?