Mode headless de Claude Code : -p, CI et la GitHub Action
Scriptez Claude Code comme un outil Unix : prompts à coup unique avec claude -p, fichiers passés par pipe, JSON à analyser, sessions reprises par id, --bare pour la CI, et la GitHub Action @claude qui construit des fonctionnalités depuis un issue — tiré droit du pas à pas d'Anthropic lui-même.
L'essentiel
- claude -p "prompt" tourne en un coup et imprime le résultat — pas de session interactive. Ça se compose comme n'importe quel outil Unix : pipe en entrée, pipe en sortie, chaînage dans les scripts et les étapes de CI.
- --output-format json renvoie le résultat plus session_id, coûts et métadonnées ; stream-json émet des événements séparés par des sauts de ligne pour les consommateurs en temps réel. Analysez avec jq et construisez dessus.
- Le headless démarre sans permission d'édition ni destructive. Accordez exactement le nécessaire avec --allowedTools "Bash(git diff *),Edit" — syntaxe de règles de permission, correspondance par préfixe.
- La GitHub Action @claude est le mode headless avec une interface : taguez @claude sur un issue ou une PR et elle lit le code, crée des PR et des commits, répond aux questions et relit le code — sur vos propres runners GitHub.
Building headless automation with Claude Code | Code w/ Claude
Chaîne : Anthropic20:59
Headless mode — official documentation
Documentation officielle : code.claude.com/docs
Claude Code GitHub Action — official docs
Documentation officielle : code.claude.com/docs
Les flags, limites et comportements de cette page sont vérifiés contre la documentation officielle du headless ; la conférence ci-dessus est le pas à pas d'Anthropic lui-même et la source visuelle des captures.
Les captures d'écran sont attribuées à leurs créateurs, avec des liens profonds vers les horodatages exacts. Les plans du conférencier et du public ne sont pas utilisés.
Exécuter Claude Code en headless, étape par étape
Partie 1 — Les bases du headless
- 1
Ce qu'est le mode headless
Le mode headless, c'est Claude Code sans l'interface interactive : le même agent, piloté par programme. Anthropic le présente comme une brique simple pour les applications agentiques — utilisez-le comme un outil Unix dans vos scripts et pipelines, pour l'automatisation de CI, les environnements distants, ou comme moteur derrière une interface de chat web.
Le cadrage d'Anthropic lui-même : le SDK est un accès programmatique à Claude Code en environnement headless.Voir à 2:10 - 2
Prompts à coup unique avec claude -p
Le flag -p (ou --print) exécute un seul prompt et sort : claude -p "Write me a function that calculates the Fibonacci sequence". Rien ne reste ouvert — vous obtenez la sortie sur stdout et un code de sortie que vos scripts peuvent vérifier. Associez-y --allowedTools pour accorder l'accès en écriture d'avance.
Une question en un coup : claude -p génère la fonction de Fibonacci et sort — pas de TUI, pas de relances.Voir à 3:30 - 3
Passer des fichiers par pipe droit dans Claude
Le stdin marche comme pour tout outil CLI : cat app.log | claude -p "summarize the most common error logs". Dans la démo d'Anthropic, 2000 lignes de log entrent et un résumé des erreurs en langue courante sort — la même astuce marche pour les échecs de build, les stack traces et les exports. Le stdin passé par pipe est plafonné à 10 Mo.
cat plus le symbole pipe plus claude -p : deux mille lignes de log deviennent un diagnostic en trois phrases.Voir à 3:55 - 4
Décoder les sorties qu'on déteste lire
Le même motif transforme les sorties hostiles en réponses : ifconfig | claude -p "what interfaces do I have configured? don't include lo". Tout ce qu'une commande imprime — état réseau, erreurs du compilateur, plans terraform — peut passer par Claude pour un résumé humain.
ifconfig passé par claude -p : chaque interface expliquée, la loopback exclue sur demande.Voir à 4:15 - 5
Obtenir du JSON structuré en sortie
Ajoutez --output-format json et la réponse devient un objet analysable : le texte du résultat, la session_id, la durée et total_cost_usd. Pour les consommateurs en direct, --output-format stream-json émet des événements séparés par des lignes au fil de l'eau — la dernière ligne est le résultat final.
Mode JSON : un seul bloc avec le résultat, un id de session à reprendre plus tard, et le coût de l'exécution.Voir à 4:35
Partie 2 — Scripter comme un ingénieur
- 6
Accorder les outils délibérément
Le headless démarre sans permission d'édition ni destructive. --allowedTools préapprouve ce dont la tâche a besoin, en syntaxe de règles de permission : --allowedTools "Bash(npm run build),Bash(npm test:*),Write". Les outils MCP peuvent être mis en liste allow de la même façon — accordez l'ensemble le plus étroit qui fasse le travail.
Le décryptage du SDK : permissions d'outils, modes de sortie structurée et prompts système personnalisés sur une seule diapositive.Voir à 11:00 - 7
Garder le contexte d'une exécution à l'autre
Le mode JSON renvoie une session_id — repassez-la avec --resume "$session_id" pour poursuivre le même état de conversation depuis une exécution ultérieure ou un autre processus. C'est comme ça qu'on bâtit des produits interactifs par-dessus : l'utilisateur dit quelque chose, Claude répond, vous préservez la session pour le tour suivant.
- 8
Gérer les permissions sans humain
Si vous ne pouvez pas prédire quels outils Claude nécessitera, --permission-prompt-tool délègue les décisions d'approbation à un serveur MCP à l'exécution — l'outil demande à votre service (ou à votre utilisateur, via votre app) d'autoriser chaque action, au lieu que vous listiez tout à l'avance.
- 9
Passer en --bare pour la CI
--bare saute la découverte automatique des hooks, skills, commandes personnalisées, sous-agents, plugins, serveurs MCP et CLAUDE.md pour le démarrage le plus rapide possible — recommandé pour les scripts et la CI, et promis comme défaut de -p. Il exige ANTHROPIC_API_KEY et reçoit le contexte explicitement via des flags.
Partie 3 — La GitHub Action @claude
- 10
Faire connaissance avec la GitHub Action @claude
La GitHub Action est le mode headless avec une interface bâtie sur le SDK. Taguez @claude sur n'importe quelle PR ou issue et elle peut lire votre code, créer des PR, ajouter des commits aux existantes, répondre aux questions et relire les changements — sur vos runners GitHub habituels, donc aucune infrastructure à garder.
Le contrat de l'Action : taguez @claude, décrivez ce qu'il vous faut — elle travaille le dépôt sur vos propres runners.Voir à 17:10 - 11
Assigner un issue à Claude
Dans la démo en direct d'Anthropic, un commentaire « @claude please implement this feature and comment on it » a fait répondre le bot avec un plan délimité — des puces de ce qu'il allait construire — avant de créer la branche, les commits et la pull request, le tout traçable dans les logs de l'Action.
Le commentaire @claude sur un vrai issue : Claude répond avec un plan délimité avant de toucher au code.Voir à 7:50 - 12
L'installer sur votre dépôt
Le résultat est un résumé d'implémentation cochée sur l'issue — fonctionnalités ajoutées, todos fermés. Pour y arriver, ouvrez Claude Code dans votre dépôt et lancez /install-github-action : un flux interactif ouvre une PR avec le YAML du workflow, puis configurez les clés d'API en secrets du dépôt et fusionnez.
L'exécution finie : un résumé d'implémentation coché avec chaque fonctionnalité que l'Action a ajoutée à l'appli de démo.Voir à 13:30
Headless vs interactif vs SDK vs la GitHub Action
Quatre façons de piloter le même agent — choisissez selon qui (ou quoi) demande :
- 1CLI interactive — la session TUI : prompts de permission, mode plan, /commands. Idéal pour un humain qui pilote une tâche maintenant.
- 2Headless claude -p — un tir programmatique : stdin et stdout, codes de sortie, pas d'interface. Idéal pour les scripts, les tâches cron et les questions rapides depuis d'autres outils.
- 3L'Agent SDK — la même puissance headless en bibliothèque typée : sessions multi-tours, outils personnalisés, streaming. Idéal quand Claude est un composant dans votre application.
- 4La GitHub Action @claude — du headless sur le modèle d'événements de GitHub : issues, PR et reviews sur vos propres runners. Idéal pour l'automatisation à l'échelle du dépôt que toute l'équipe peut déclencher.
- 5--bare headless — un démarrage dénudé pour la CI : pas de CLAUDE.md, de hooks, skills, plugins ni de découverte automatique MCP, contexte explicite via des flags, le démarrage à froid le plus rapide.
Elles partagent le même accès au modèle et le même système de permissions — une règle de permission accordée au headless s'applique partout, c'est pourquoi la discipline --allowedTools compte.
Le headless déraille ? Premier secours
Cinq pièges propres au headless, et le remède de chacun :
- 1Le script sort avant que Claude ait fini. Vérifiez le code de sortie : 0 c'est le succès, tout le reste a échoué. SIGTERM sort avec 143 et laisse le tour inachevé — terminez les exécutions avec SIGINT ou le interrupt() du SDK si vous devez stopper en plein tour.
- 2L'entrée par pipe tronquée en silence. Le stdin est plafonné à 10 Mo — écrivez les payloads plus gros dans un fichier et référencez le chemin dans le prompt.
- 3« --bg rejected » ou une erreur --cloud. Les flags réservés à l'interactif ne s'appliquent pas à -p : --bg est rejeté sans appel, et --cloud a besoin d'un id de session pour mettre un message en file plutôt qu'une description de tâche.
- 4L'exécution de CI ignore votre CLAUDE.md et vos hooks. C'est --bare qui fait son travail : il saute la découverte automatique. Passez le contexte explicitement avec --settings, --mcp-config, --agents ou --plugin-dir.
- 5Les tâches bash d'arrière-plan meurent en cours de route. Les shells d'arrière-plan sont tués environ 5 secondes après l'arrivée du résultat ; les sous-agents et workflows gardent le processus en vie jusqu'à un plafond d'inactivité de 10 minutes. Attendez-les explicitement en CI.
Pour tout le reste, ajoutez --verbose et lisez les événements stream-json — system/init nomme le modèle, les outils et les serveurs MCP réellement chargés.