Exécuter Claude Code par programmation

Utilisez l'Agent SDK pour exécuter Claude Code par programmation depuis la CLI, Python ou TypeScript.

L'Agent SDK vous donne accès aux mêmes outils, boucle d'agent et gestion du contexte qui alimentent Claude Code. Il est disponible en tant que CLI pour les scripts et CI/CD, ou en tant que packages Python et TypeScript pour un contrôle programmatique complet.

Pour exécuter Claude Code en mode non interactif, passez -p avec votre prompt et les options CLI dont vous avez besoin :

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Cette page couvre l'utilisation de l'Agent SDK via la CLI (claude -p). Pour les packages SDK Python et TypeScript avec sorties structurées, callbacks d'approbation d'outils et objets de message natifs, consultez la documentation complète de l'Agent SDK.

Utilisation basique

Ajoutez le flag -p (ou --print) à n'importe quelle commande claude pour l'exécuter de manière non-interactive. Toutes les options CLI ne se combinent pas avec -p. Claude Code rejette --bg, et rejette --cloud avec une description de tâche, avec une erreur nommant le conflit ; --cloud avec un ID de session et -p à la place met en file d'attente un message dans cette session cloud et se termine. Les options que vous combinerez souvent avec -p incluent :

• --continue pour continuer les conversations
• --allowedTools pour approuver automatiquement les outils
• --output-format pour obtenir une sortie structurée

Cet exemple pose une question à Claude sur votre base de code et affiche la réponse :

claude -p "What does the auth module do?"

Claude Code se termine avec le code 0 en cas de succès et un code non-zéro quand l'exécution échoue, donc vos scripts peuvent se brancher sur le code de sortie. Si vous passez un flag invalide, Claude Code signale l'erreur sur stderr avant le démarrage de l'exécution. Quand une défaillance se produit à l'intérieur de l'exécution, comme une authentification manquante, Claude Code affiche la défaillance comme le résultat sur stdout.

Démarrer plus rapidement avec le mode bare

Ajoutez --bare pour réduire le temps de démarrage en ignorant la découverte automatique des hooks, skills, commandes personnalisées, sous-agents, plugins, serveurs MCP, mémoire automatique et CLAUDE.md. Sans cela, claude -p charge le même contexte qu'une session interactive, y compris tout ce qui est configuré dans le répertoire de travail ou ~/.claude.

Le mode bare est utile pour CI et les scripts où vous avez besoin du même résultat sur chaque machine. Un hook dans le ~/.claude d'un coéquipier ou un serveur MCP dans le .mcp.json du projet ne s'exécutera pas, car le mode bare ne les lit jamais. Un répertoire que vous nommez avec --add-dir est une exception partielle : le mode bare charge les skills de son dossier .claude/skills/, mais ignore toujours ses dossiers .claude/commands/ et .claude/agents/. Skills from additional directories couvre ce qui se charge et ce qui ne se charge pas.

Sans --bare, une session -p exécute les hooks dans le .claude/settings.json d'un projet et connecte les serveurs dans son .mcp.json, même dans un dossier que vous n'avez jamais approuvé. Une session -p n'affiche aucune boîte de dialogue de confiance d'espace de travail et aucune invite d'approbation par serveur. What runs before you trust a folder couvre chaque type de contenu de référentiel sous -p et comment le garder à l'écart.

Cet exemple exécute une tâche de résumé ponctuelle en mode bare et pré-approuve l'outil Read pour que l'appel se termine sans invite de permission. Définissez ANTHROPIC_API_KEY avant de l'exécuter, car le mode bare n'utilise pas votre connexion d'abonnement :

claude --bare -p "Summarize README.md" --allowedTools "Read"

En mode bare, Claude Code ne lit jamais les identifiants OAuth ou le trousseau système. Pour l'API Anthropic, définissez ANTHROPIC_API_KEY dans l'environnement, avec une clé créée dans la Claude Console, ou fournissez un apiKeyHelper dans le JSON --settings. Amazon Bedrock, Google Cloud's Agent Platform et Microsoft Foundry continuent à lire leurs propres identifiants de fournisseur comme d'habitude.

En mode bare, Claude a accès aux outils Bash, lecture de fichier et modification de fichier. Passez tout contexte dont vous avez besoin avec un flag :

Tâches en arrière-plan à la sortie

Si Claude démarre une tâche Bash en arrière-plan lors d'une exécution claude -p, par exemple un serveur de développement ou une compilation en surveillance, ce shell est terminé environ cinq secondes après que Claude ait retourné son résultat final et que stdin ait été fermé. La période de grâce permet à une tâche qui se termine juste après le résultat de livrer quand même sa sortie.

Si Claude démarre un sous-agent en arrière-plan ou un workflow, claude -p reste plutôt ouvert jusqu'à ce que ce travail se termine, car son résultat fait partie de la sortie finale.

Par défaut, l'attente se termine après 10 minutes d'attente continue inactive, donc un sous-agent ou un workflow bloqué ne peut pas maintenir le processus ouvert indéfiniment. À ce stade, Claude Code arrête tout ce qui s'exécute toujours et abandonne son résultat partiel. Pour modifier la limite, définissez CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, ou définissez-le sur 0 pour attendre sans limite.

Si Claude démarre une montre Monitor lors d'une exécution claude -p, Claude Code attend la montre jusqu'à ce qu'elle expire ou que le plafond de dix minutes termine l'attente, selon ce qui arrive en premier. Pendant qu'il attend, Claude continue à répondre à ce que la montre signale. Par défaut, une montre expire cinq minutes après que Claude la démarre.

Arrêter une exécution avec SIGTERM

Si vous arrêtez une exécution claude -p avec SIGTERM, par exemple avec kill ou depuis un superviseur de processus, Claude Code se termine avec le code 143. Claude Code laisse le tour en cours inachevé et n'enregistre aucun résultat pour celui-ci. Pour terminer le tour à la place, envoyez SIGINT, ou appelez interrupt() du SDK Agent, avant d'arrêter le processus.

Sur SIGTERM, Claude Code termine l'arborescence des processus de toute commande Bash qui s'exécute toujours. Claude Code exécute ensuite les hooks SessionEnd et se termine. Lors de la sortie, Claude Code ne démarre aucun nouvel appel d'outil, n'envoie aucune nouvelle demande de modèle et n'exécute aucun hook autre que SessionEnd. Si l'exécution était au milieu d'une commande ou en attente d'une réponse à une invite de permission quand le signal est arrivé, Claude Code gère cette étape comme suit :

• Exécution d'une commande : Claude Code enregistre la commande comme tuée dans la session.
• En attente d'une réponse à une invite de permission : si vous envoyez SIGTERM au processus, Claude Code laisse l'invite sans réponse. Si votre programme ferme la session via le SDK Agent, le SDK termine l'entrée de Claude Code avant d'envoyer un signal, et Claude Code annule l'invite dès que l'entrée se termine.

Quand vous reprenez la session, Claude Code continue le tour que SIGTERM a laissé inachevé.

Exemples

Ces exemples mettent en évidence les modèles CLI courants. Lorsqu'une commande nomme un fichier tel que auth.py ou build-error.txt, remplacez-le par un fichier de votre propre projet. Dans les environnements CI ou autres environnements scriptés, ajoutez --bare pour que Claude Code démarre sans charger les hooks, plugins, mémoire automatique ou CLAUDE.md de l'hôte.

Transmettre des données via Claude

Le mode non interactif lit stdin, vous pouvez donc transmettre des données et rediriger la réponse comme n'importe quel autre outil en ligne de commande.

Cet exemple transmet un journal de compilation à Claude et écrit l'explication dans un fichier :

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Avec --output-format json, la charge utile de réponse inclut total_cost_usd et une ventilation des coûts par modèle, afin que les appelants scriptés puissent suivre les dépenses sans consulter le tableau de bord d'utilisation. Lorsque vous continuez une conversation antérieure avec --continue ou --resume, l'exécution rapporte le total de la conversation, les dépenses des exécutions antérieures incluses. Les deux chiffres sont des estimations côté client et peuvent différer de votre facture réelle.

Si Claude Code ne peut pas lire stdin, par exemple parce que le processus qui l'a démarré a déconnecté son extrémité, Claude Code imprime un avertissement sur stderr et continue avec l'invite de la ligne de commande. Avant la v2.1.211, une stdin illisible sur Windows plantait la session ou la fermait silencieusement sans sortie.

Ajouter Claude à un script de compilation

Vous pouvez envelopper un appel non interactif dans un script pour utiliser Claude comme linter ou examinateur spécifique au projet.

Ce script package.json transmet le diff par rapport à main à Claude et lui demande de signaler les fautes de frappe. Transmettre le diff signifie que Claude n'a pas besoin de permission Bash pour le lire, et les guillemets échappés gardent le script portable vers Windows :

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Exécutez-le avec npm run lint:claude.

Obtenir une sortie structurée

Utilisez --output-format pour contrôler la façon dont les réponses sont renvoyées :

• text (par défaut) : sortie en texte brut
• json : JSON structuré avec résultat, ID de session et métadonnées
• stream-json : JSON délimité par des sauts de ligne pour le streaming en temps réel

Cet exemple retourne un résumé du projet en JSON avec les métadonnées de session, avec le résultat textuel dans le champ result :

claude -p "Summarize this project" --output-format json

Pour obtenir une sortie conforme à un schéma spécifique, utilisez --output-format json avec --json-schema et une définition JSON Schema. La réponse inclut les métadonnées de la requête (ID de session, utilisation, etc.) avec la sortie structurée dans le champ structured_output.

Cet exemple extrait les noms de fonction et les retourne sous forme de tableau de chaînes :

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Si la valeur n'est pas un JSON Schema valide, claude se ferme avec Error: --json-schema is not a valid JSON Schema suivi du diagnostic du validateur. Claude Code accepte les schémas qui utilisent le mot-clé format, tel que "format": "email", mais traite format comme une annotation et ne l'applique pas. Avant la v2.1.205, Claude Code ignorait silencieusement un schéma invalide et retournait du texte non structuré, et traitait tout schéma contenant format comme invalide.

Réponses en streaming

Utilisez --output-format stream-json avec --verbose et --include-partial-messages pour recevoir les jetons au fur et à mesure qu'ils sont générés. Chaque ligne est un objet JSON représentant un événement :

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

La dernière ligne du flux est un message result avec le texte de réponse final, le coût et les métadonnées de session.

Si votre consommateur lit le flux lentement, Claude Code attend que la sortie en file d'attente se vide avant de se fermer, en mettant à l'échelle l'attente en fonction de la quantité restante en file d'attente, plafonnée à 30 secondes. Avant la v2.1.214, l'attente de fermeture était plafonnée à environ deux secondes, ce qui pouvait couper la fin d'une grande réponse.

L'exemple suivant utilise jq pour filtrer les deltas de texte et afficher uniquement le texte en streaming. L'indicateur -r génère des chaînes brutes (sans guillemets) et -j joint sans sauts de ligne pour que les jetons se transmettent continuellement :

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Pour le streaming programmatique avec des rappels et des objets de message, consultez Réponses en streaming en temps réel dans la documentation du SDK Agent.

Suivre les messages des sous-agents

Les messages des sous-agents apparaissent dans le flux sous forme de messages assistant et user dont le champ parent_tool_use_id est l'ID de l'appel d'outil qui a généré le sous-agent. Les messages de la conversation principale portent null dans ce champ.

Le premier message d'un sous-agent s'exécutant en avant-plan est un message user portant l'invite qui le pilote. Après ce premier message, Claude Code émet :

• Par défaut : les blocs tool_use et tool_result du sous-agent.
• Avec --forward-subagent-text ou CLAUDE_CODE_FORWARD_SUBAGENT_TEXT : les blocs de texte et de réflexion du sous-agent également, afin que vous puissiez reconstruire la transcription de chaque sous-agent. Cela nécessite Claude Code v2.1.211 ou ultérieur.

Lorsque vous activez l'une ou l'autre option, Claude Code transfère les messages des sous-agents à chaque profondeur d'imbrication, qu'ils aient été générés avec l'outil Agent ou démarrés en tant que compétence dupliquée. Les messages des sous-agents qu'une compétence dupliquée génère, et des compétences dupliquées démarrées à l'intérieur d'un sous-agent ou d'une autre compétence dupliquée, nécessitent Claude Code v2.1.275 ou ultérieur. Dans parent_tool_use_id, les messages du sous-agent imbriqué portent l'ID de l'appel d'outil Agent ou Skill qui l'a démarré, afin que vous puissiez reconstruire l'arborescence d'imbrication complète en suivant ces ID. Avant la v2.1.219, les messages des sous-agents imbriqués n'apparaissaient pas dans le flux.

Les compétences qui s'exécutent dans un sous-agent apparaissent dans le flux de la même manière : le premier message de la compétence dupliquée est un message user portant le contenu de la compétence qui pilote l'exécution. Si vous activez l'une ou l'autre option, le flux porte également les blocs de texte et de réflexion de la compétence dupliquée. Avant la v2.1.265, seuls les blocs tool_use et tool_result d'une compétence dupliquée apparaissaient dans le flux.

Gérer les tentatives d'API

Lorsqu'une requête API échoue avec une erreur réessayable, Claude Code émet un événement system/api_retry avant de réessayer. Sur la v2.1.246 ou ultérieur, lorsqu'un 401 ou 403 rejette une credential apiKeyHelper, Claude Code effectue les deux premières tentatives silencieusement sans événement, puis émet l'événement comme d'habitude à partir de la troisième tentative consécutive. Les tentatives silencieuses comptent toujours vers attempt. Vous pouvez utiliser l'événement pour afficher la progression des tentatives dans votre propre interface.

Lire les métadonnées de session

L'événement system/init rapporte les métadonnées de session, y compris le modèle, les outils, les serveurs MCP et les plugins chargés. C'est le premier événement du flux sauf si des événements de démarrage le précèdent :

• Événements plugin_install, lorsque CLAUDE_CODE_SYNC_PLUGIN_INSTALL est défini.
• Événements hook_started, hook_progress et hook_response, tandis qu'un hook SessionStart ou Setup configuré s'exécute. Ceux-ci se transmettent au fur et à mesure que le hook les produit. Claude Code v2.1.169 à v2.1.203 les a livrés en un seul lot après la fin du hook, toujours avant system/init ; v2.1.204 a restauré la livraison en direct.

L'événement porte également un tableau optionnel capabilities de chaînes nommant les comportements de protocole que cette version de Claude Code implémente, tels que interrupt_receipt_v1 ou interrupt_cancel_queued_v1. Vérifiez-le pour détecter les fonctionnalités au lieu de comparer les chaînes de version, et ignorez les valeurs que vous ne reconnaissez pas. Le champ nécessite Claude Code v2.1.205 ou ultérieur et est absent des versions antérieures. Consultez SDKSystemMessage pour la liste des capacités.

Échouer CI lorsqu'un plugin ou un serveur MCP ne se charge pas

Utilisez les champs de plugin dans l'événement system/init pour détecter un plugin qui ne s'est pas chargé :

Utilisez les champs du serveur MCP de la même manière. Lorsque vous passez --mcp-config avec -p, Claude Code attend les serveurs toujours en attente avant d'exécuter le premier tour, jusqu'au délai d'expiration de démarrage MCP_TIMEOUT, 30 secondes par défaut. Un serveur distant avec une liste d'outils mise en cache ignore l'attente, affiche pending dans system/init et se connecte lors de son premier appel d'outil. L'attente nécessite Claude Code v2.1.221 ou ultérieur.

Claude Code valide chaque entrée --mcp-config au démarrage et ignore les entrées qui échouent la validation, par exemple une entrée url sans type. L'exécution continue et se ferme correctement, vérifiez donc ces champs pour détecter un serveur qui ne s'est jamais chargé :

Lorsque vous exécutez la commande à la main dans un terminal, Claude Code imprime également un avertissement de démarrage sur stderr, tel que Warning: 1 MCP server skipped due to invalid config:, suivi de la raison de chaque entrée ignorée. Lorsque vous redirigez stderr, ou lorsqu'un programme tel qu'un exécuteur CI ou un hôte SDK le capture, Claude Code n'imprime aucun avertissement et rapporte les entrées ignorées uniquement dans le champ mcp_server_errors. L'avertissement nécessite Claude Code v2.1.219 ou ultérieur.

Suivre les installations de plugins

Lorsque CLAUDE_CODE_SYNC_PLUGIN_INSTALL est défini, Claude Code émet des événements system/plugin_install tandis que les plugins de marketplace s'installent avant le premier tour. Utilisez-les pour afficher la progression de l'installation dans votre propre interface utilisateur.

Approuver automatiquement les outils

Utilisez --allowedTools pour permettre à Claude d'utiliser certains outils sans demander. Cet exemple exécute une suite de tests et corrige les défaillances, permettant à Claude d'exécuter des commandes Bash et de lire/modifier des fichiers sans demander la permission :

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Pour définir une base de référence pour la session entière au lieu de lister les outils individuels, passez un mode de permission. Pour -p, le mode de permission de démarrage intégré est Manual sur tous les plans, donc passez le mode de permission que vous souhaitez :

• auto : passez --permission-mode auto pour qu'un classificateur examine la plupart des actions au lieu de vous
• dontAsk : Claude Code refuse chaque appel qui demanderait autrement, ce qui est utile pour les exécutions CI verrouillées. Les actions qui n'ont pas besoin d'approbation en mode Manual s'exécutent toujours, telles que les lectures de fichiers dans vos répertoires de travail et l'ensemble de commandes en lecture seule, ainsi que les actions que vos entrées --allowedTools ou les règles permissions.allow couvrent. AskUserQuestion, les outils de connecteur que votre organisation a définis sur ask, et les outils MCP marqués requiresUserInteraction sont refusés même lorsqu'une règle d'autorisation correspond
• acceptEdits : Claude écrit les fichiers sans demander, et Claude Code approuve automatiquement les commandes de système de fichiers courants telles que mkdir, touch, mv et cp. Les actions qu'aucun mode n'approuve automatiquement s'appliquent toujours. Hormis l'ensemble de commandes en lecture seule, les autres commandes shell et requêtes réseau ont toujours besoin d'une entrée --allowedTools ou d'une règle permissions.allow. Consultez ce que acceptEdits approuve automatiquement pour la liste complète

Cet exemple applique les corrections de lint avec acceptEdits comme base de référence :

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Désactiver les invites de permission dans les exécutions sans surveillance

Passez --permission-prompts none lorsque personne n'est disponible pour répondre aux invites de permission, par exemple dans une tâche planifiée. L'indicateur est plus important lorsque votre exécution a un hôte de permission : une application Agent SDK avec un rappel canUseTool, ou un outil MCP que vous passez avec --permission-prompt-tool. Sans l'indicateur, votre exécution attend que cet hôte réponde à chaque demande de permission.

Avec l'indicateur, votre exécution ne consulte pas l'hôte et n'attend pas. Tout ce qui demanderait est refusé sauf si un hook PermissionRequest l'autorise, Claude est informé que personne ne peut approuver la demande et ne pas la réessayer, et l'exécution continue. Dans une exécution -p sans hôte, ces demandes sont refusées de toute façon, et l'indicateur indique également à Claude de ne pas les réessayer. Les règles de permission, les hooks PermissionRequest et le mode de permission que vous définissez décident toujours de chaque appel en premier ; Claude Code refuse uniquement les demandes que rien d'autre ne résout.

Cet exemple exécute une tâche sans surveillance en mode auto. Le classificateur examine chaque action comme d'habitude, et Claude Code refuse tout ce qui aurait autrement entraîné une invite :

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Avec --permission-prompts none, Claude Code supprime les outils qui ont besoin d'une réponse d'une personne, tels que AskUserQuestion, afin que Claude ne puisse pas les appeler. Toute demande d'élicitation MCP à laquelle aucun hook Elicitation ne répond est annulée.

Avec --output-format stream-json, les refus apparaissent sous forme de messages système permission_denied, et le message de résultat final les énumère dans permission_denials.

Créer un commit

Cet exemple examine les modifications mises en scène et crée un commit avec un message approprié :

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

L'indicateur --allowedTools utilise la syntaxe de règle de permission. Le * de fin active la correspondance de préfixe, donc Bash(git diff *) autorise toute commande commençant par git diff. L'espace avant * est important : sans lui, Bash(git diff*) correspondrait également à git diff-index.

Personnaliser l'invite système

Utilisez --append-system-prompt pour ajouter des instructions tout en conservant le comportement par défaut de Claude Code. Cet exemple transmet un diff PR à Claude et lui demande de vérifier les vulnérabilités de sécurité. Enregistrez-le en tant que script shell, par exemple review.sh :

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Dans le script, "$1" représente le premier argument que vous passez sur la ligne de commande. Exécutez bash review.sh 123 et le shell remplace "$1" par 123, donc le script récupère le diff pour la PR 123. Claude Code imprime l'examen en JSON, avec le texte dans le champ result.

Consultez les indicateurs d'invite système pour plus d'options, y compris --system-prompt pour remplacer complètement l'invite par défaut.

Continuer les conversations

Utilisez --continue pour continuer la conversation la plus récente, ou --resume avec un ID de session pour continuer une conversation spécifique. Sur Claude Code v2.1.257 ou ultérieur, lorsque vous passez --continue, Claude Code ouvre une session en arrière-plan qui a terminé, mais pas une qui s'exécute toujours. Cet exemple exécute un examen, puis envoie des invites de suivi :

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Si vous exécutez plusieurs conversations, capturez l'ID de session pour reprendre une conversation spécifique :

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Vous pouvez exécuter les deux commandes à partir de répertoires différents : Claude Code trouve la session par son ID dans n'importe quel projet sur cette machine. Avant la v2.1.223, Claude Code recherchait l'ID uniquement dans le répertoire du projet actuel et ses git worktrees, vous deviez donc exécuter les deux commandes à partir du même répertoire.

À la place de l'ID de session, vous pouvez passer à --resume le chemin absolu vers le fichier de transcription .jsonl d'une session, et Claude Code continue la conversation stockée dans ce fichier.

Étapes suivantes

• Démarrage rapide de l'Agent SDK : créez votre premier agent avec Python ou TypeScript
• Référence CLI : tous les flags et options CLI
• GitHub Actions : utilisez l'Agent SDK dans les workflows GitHub
• GitLab CI/CD : utilisez l'Agent SDK dans les pipelines GitLab