SDK Claude Code

Le SDK Claude Code permet d’exécuter Claude Code en tant que sous-processus, fournissant un moyen de construire des assistants de codage et des outils alimentés par l’IA qui exploitent les capacités de Claude.

Le SDK est disponible pour l’utilisation en ligne de commande, TypeScript et Python.

Authentification

Pour utiliser le SDK Claude Code, nous recommandons de créer une clé API dédiée :

Créez une clé API Anthropic dans la Console Anthropic
Ensuite, définissez la variable d’environnement ANTHROPIC_API_KEY. Nous recommandons de stocker cette clé de manière sécurisée (par exemple, en utilisant un secret Github)

Utilisation de base du SDK

Le SDK Claude Code vous permet d’utiliser Claude Code en mode non-interactif depuis vos applications.

Ligne de commande

Voici quelques exemples de base pour le SDK en ligne de commande :

# Exécuter une seule invite et quitter (mode impression)
$ claude -p "Écrivez une fonction pour calculer les nombres de Fibonacci"

# Utiliser un pipe pour fournir stdin
$ echo "Expliquez ce code" | claude -p

# Sortie au format JSON avec métadonnées
$ claude -p "Générez une fonction hello world" --output-format json

# Diffuser la sortie JSON au fur et à mesure qu'elle arrive
$ claude -p "Construisez un composant React" --output-format stream-json

TypeScript

Le SDK TypeScript est inclus dans le package principal @anthropic-ai/claude-code sur NPM :

import { query, type SDKMessage } from "@anthropic-ai/claude-code";

const messages: SDKMessage[] = [];

for await (const message of query({
  prompt: "Write a haiku about foo.py",
  abortController: new AbortController(),
  options: {
    maxTurns: 3,
  },
})) {
  messages.push(message);
}

console.log(messages);

Le SDK TypeScript accepte tous les arguments pris en charge par le SDK en ligne de commande, ainsi que :

Argument	Description	Par défaut
`abortController`	Contrôleur d’abandon	`new AbortController()`
`cwd`	Répertoire de travail actuel	`process.cwd()`
`executable`	Quel runtime JavaScript utiliser	`node` lors de l’exécution avec Node.js, `bun` lors de l’exécution avec Bun
`executableArgs`	Arguments à passer à l’exécutable	`[]`
`pathToClaudeCodeExecutable`	Chemin vers l’exécutable Claude Code	Exécutable livré avec `@anthropic-ai/claude-code`

Python

Le SDK Python est disponible sous claude-code-sdk sur PyPI :

pip install claude-code-sdk

Prérequis :

Python 3.10+
Node.js
CLI Claude Code : npm install -g @anthropic-ai/claude-code

Utilisation de base :

import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []
    
    async for message in query(
        prompt="Write a haiku about foo.py",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

Le SDK Python accepte tous les arguments pris en charge par le SDK en ligne de commande via la classe ClaudeCodeOptions :

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="You are a helpful assistant",
    cwd=Path("/path/to/project"),  # Peut être une chaîne ou un Path
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

async for message in query(prompt="Hello", options=options):
    print(message)

Utilisation avancée

La documentation ci-dessous utilise le SDK en ligne de commande comme exemple, mais peut également être utilisée avec les SDK TypeScript et Python.

Conversations multi-tours

Pour les conversations multi-tours, vous pouvez reprendre des conversations ou continuer à partir de la session la plus récente :

# Continuer la conversation la plus récente
$ claude --continue

# Continuer et fournir une nouvelle invite
$ claude --continue "Maintenant refactorisez ceci pour de meilleures performances"

# Reprendre une conversation spécifique par ID de session
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# Reprendre en mode impression (non-interactif)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "Mettez à jour les tests"

# Continuer en mode impression (non-interactif)
$ claude -p --continue "Ajoutez la gestion des erreurs"

Invites système personnalisées

Vous pouvez fournir des invites système personnalisées pour guider le comportement de Claude :

# Remplacer l'invite système (fonctionne uniquement avec --print)
$ claude -p "Construisez une API REST" --system-prompt "Vous êtes un ingénieur backend senior. Concentrez-vous sur la sécurité, les performances et la maintenabilité."

# Invite système avec des exigences spécifiques
$ claude -p "Créez un schéma de base de données" --system-prompt "Vous êtes un architecte de base de données. Utilisez les meilleures pratiques PostgreSQL et incluez une indexation appropriée."

Vous pouvez également ajouter des instructions à l’invite système par défaut :

# Ajouter une invite système (fonctionne uniquement avec --print)
$ claude -p "Construisez une API REST" --append-system-prompt "Après avoir écrit du code, assurez-vous de faire une revue de code vous-même."

Configuration MCP

Le Model Context Protocol (MCP) vous permet d’étendre Claude Code avec des outils et des ressources supplémentaires provenant de serveurs externes. En utilisant le flag --mcp-config, vous pouvez charger des serveurs MCP qui fournissent des capacités spécialisées comme l’accès aux bases de données, les intégrations d’API ou les outils personnalisés.

Créez un fichier de configuration JSON avec vos serveurs MCP :

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/files"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Ensuite, utilisez-le avec Claude Code :

# Charger les serveurs MCP à partir de la configuration
$ claude -p "Listez tous les fichiers du projet" --mcp-config mcp-servers.json

# Important : les outils MCP doivent être explicitement autorisés en utilisant --allowedTools
# Les outils MCP suivent le format : mcp__$serverName__$toolName
$ claude -p "Recherchez les commentaires TODO" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# Utilisez un outil MCP pour gérer les invites de permission en mode non-interactif
$ claude -p "Déployez l'application" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

Lors de l’utilisation d’outils MCP, vous devez les autoriser explicitement en utilisant le flag --allowedTools. Les noms d’outils MCP suivent le modèle mcp__<serverName>__<toolName> où :

serverName est la clé de votre fichier de configuration MCP
toolName est l’outil spécifique fourni par ce serveur

Cette mesure de sécurité garantit que les outils MCP ne sont utilisés que lorsqu’ils sont explicitement autorisés.

Si vous spécifiez seulement le nom du serveur (c’est-à-dire mcp__<serverName>), tous les outils de ce serveur seront autorisés.

Les modèles glob (par exemple, mcp__go*) ne sont pas pris en charge.

Outil d’invite de permission personnalisé

Optionnellement, utilisez --permission-prompt-tool pour passer un outil MCP que nous utiliserons pour vérifier si l’utilisateur accorde ou non au modèle les permissions d’invoquer un outil donné. Lorsque le modèle invoque un outil, voici ce qui se passe :

Nous vérifions d’abord les paramètres de permission : tous les fichiers settings.json, ainsi que --allowedTools et --disallowedTools passés dans le SDK ; si l’un de ceux-ci autorise ou refuse l’appel d’outil, nous procédons à l’appel d’outil
Sinon, nous invoquons l’outil MCP que vous avez fourni dans --permission-prompt-tool

L’outil MCP --permission-prompt-tool reçoit le nom de l’outil et l’entrée, et doit retourner une charge utile JSON-stringifiée avec le résultat. La charge utile doit être l’une des suivantes :

// l'appel d'outil est autorisé
{
  "behavior": "allow",
  "updatedInput": {...}, // entrée mise à jour, ou retournez simplement l'entrée originale
}

// l'appel d'outil est refusé
{
  "behavior": "deny",
  "message": "..." // chaîne lisible par l'homme expliquant pourquoi la permission a été refusée
}

Par exemple, une implémentation d’outil d’invite de permission MCP TypeScript pourrait ressembler à ceci :

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simulate a permission check - approve if the input contains "allow", otherwise deny',
  {
    tool_name: z.string().describe("The tool requesting permission"),
    input: z.object({}).passthrough().describe("The input for the tool"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Permission denied by test approval_prompt tool",
                }
          ),
        },
      ],
    };
  }
);

Pour utiliser cet outil, ajoutez votre serveur MCP (par exemple avec --mcp-config), puis invoquez le SDK comme ceci :

claude -p "..." \
  --permission-prompt-tool mcp__test-server__approval_prompt \
  --mcp-config my-config.json

Notes d’utilisation :

Utilisez updatedInput pour dire au modèle que l’invite de permission a muté son entrée ; sinon, définissez updatedInput sur l’entrée originale, comme dans l’exemple ci-dessus. Par exemple, si l’outil montre un diff d’édition de fichier à l’utilisateur et lui permet d’éditer le diff manuellement, l’outil d’invite de permission devrait retourner cette édition mise à jour.
La charge utile doit être JSON-stringifiée

Options CLI disponibles

Le SDK exploite toutes les options CLI disponibles dans Claude Code. Voici les principales pour l’utilisation du SDK :

Flag	Description	Exemple
`--print`, `-p`	Exécuter en mode non-interactif	`claude -p "requête"`
`--output-format`	Spécifier le format de sortie (`text`, `json`, `stream-json`)	`claude -p --output-format json`
`--resume`, `-r`	Reprendre une conversation par ID de session	`claude --resume abc123`
`--continue`, `-c`	Continuer la conversation la plus récente	`claude --continue`
`--verbose`	Activer la journalisation détaillée	`claude --verbose`
`--max-turns`	Limiter les tours agentiques en mode non-interactif	`claude --max-turns 3`
`--system-prompt`	Remplacer l’invite système (uniquement avec `--print`)	`claude --system-prompt "Instruction personnalisée"`
`--append-system-prompt`	Ajouter à l’invite système (uniquement avec `--print`)	`claude --append-system-prompt "Instruction personnalisée"`
`--allowedTools`	Liste séparée par des espaces d’outils autorisés, ou chaîne de liste séparée par des virgules d’outils autorisés	`claude --allowedTools mcp__slack mcp__filesystem` `claude --allowedTools "Bash(npm install),mcp__filesystem"`
`--disallowedTools`	Liste séparée par des espaces d’outils refusés, ou chaîne de liste séparée par des virgules d’outils refusés	`claude --disallowedTools mcp__splunk mcp__github` `claude --disallowedTools "Bash(git commit),mcp__github"`
`--mcp-config`	Charger les serveurs MCP à partir d’un fichier JSON	`claude --mcp-config servers.json`
`--permission-prompt-tool`	Outil MCP pour gérer les invites de permission (uniquement avec `--print`)	`claude --permission-prompt-tool mcp__auth__prompt`

Pour une liste complète des options CLI et des fonctionnalités, consultez la documentation de référence CLI.

Formats de sortie

Le SDK prend en charge plusieurs formats de sortie :

Sortie texte (par défaut)

Retourne seulement le texte de réponse :

$ claude -p "Expliquez le fichier src/components/Header.tsx"
# Sortie : Ceci est un composant React montrant...

Sortie JSON

Retourne des données structurées incluant les métadonnées :

$ claude -p "Comment fonctionne la couche de données ?" --output-format json

Format de réponse :

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "Le texte de réponse ici...",
  "session_id": "abc123"
}

Sortie JSON en streaming

Diffuse chaque message au fur et à mesure qu’il est reçu :

$ claude -p "Construisez une application" --output-format stream-json

Chaque conversation commence par un message système init initial, suivi d’une liste de messages utilisateur et assistant, suivi d’un message système result final avec les statistiques. Chaque message est émis comme un objet JSON séparé.

Schéma de message

Les messages retournés par l’API JSON sont strictement typés selon le schéma suivant :

type SDKMessage =
  // Un message assistant
  | {
      type: "assistant";
      message: Message; // du SDK Anthropic
      session_id: string;
    }

  // Un message utilisateur
  | {
      type: "user";
      message: MessageParam; // du SDK Anthropic
      session_id: string;
    }

  // Émis comme dernier message
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Émis comme dernier message, quand nous avons atteint le nombre maximum de tours
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Émis comme premier message au début d'une conversation
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

Nous publierons bientôt ces types dans un format compatible JSONSchema. Nous utilisons la versioning sémantique pour le package principal Claude Code pour communiquer les changements cassants à ce format.

Les types Message et MessageParam sont disponibles dans les SDK Anthropic. Par exemple, consultez les SDK Anthropic TypeScript et Python.

Formats d’entrée

Le SDK prend en charge plusieurs formats d’entrée :

Entrée texte (par défaut)

Le texte d’entrée peut être fourni comme argument :

$ claude -p "Expliquez ce code"

Ou le texte d’entrée peut être transmis via stdin :

$ echo "Expliquez ce code" | claude -p

Entrée JSON en streaming

Un flux de messages fourni via stdin où chaque message représente un tour utilisateur. Cela permet plusieurs tours d’une conversation sans relancer le binaire claude et permet de fournir des conseils au modèle pendant qu’il traite une demande.

Chaque message est un objet JSON ‘Message utilisateur’, suivant le même format que le schéma de message de sortie. Les messages sont formatés en utilisant le format jsonl où chaque ligne d’entrée est un objet JSON complet. L’entrée JSON en streaming nécessite -p et --output-format stream-json.

Actuellement, ceci est limité aux messages utilisateur texte uniquement.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Expliquez ce code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Exemples

Intégration de script simple

#!/bin/bash

# Fonction simple pour exécuter Claude et vérifier le code de sortie
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "Succès !"
    else
        echo "Erreur : Claude a échoué avec le code de sortie $?" >&2
        return 1
    fi
}

# Exemples d'utilisation
run_claude "Écrivez une fonction Python pour lire les fichiers CSV"
run_claude "Optimisez cette requête de base de données" "json"

Traitement de fichiers avec Claude

# Traiter un fichier à travers Claude
$ cat mycode.py | claude -p "Examinez ce code pour les bugs"

# Traiter plusieurs fichiers
$ for file in *.js; do
    echo "Traitement de $file..."
    claude -p "Ajoutez des commentaires JSDoc à ce fichier :" < "$file" > "${file}.documented"
done

# Utiliser Claude dans un pipeline
$ grep -l "TODO" *.py | while read file; do
    claude -p "Corrigez tous les éléments TODO dans ce fichier" < "$file"
done

Gestion de session

# Démarrer une session et capturer l'ID de session
$ claude -p "Initialisez un nouveau projet" --output-format json | jq -r '.session_id' > session.txt

# Continuer avec la même session
$ claude -p --resume "$(cat session.txt)" "Ajoutez des tests unitaires"

Meilleures pratiques

Utilisez le format de sortie JSON pour l’analyse programmatique des réponses :

# Analyser la réponse JSON avec jq
result=$(claude -p "Générez du code" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

Gérez les erreurs avec élégance - vérifiez les codes de sortie et stderr :

if ! claude -p "$prompt" 2>error.log; then
    echo "Une erreur s'est produite :" >&2
    cat error.log >&2
    exit 1
fi

Utilisez la gestion de session pour maintenir le contexte dans les conversations multi-tours

Considérez les timeouts pour les opérations de longue durée :

timeout 300 claude -p "$complex_prompt" || echo "Timeout après 5 minutes"

Respectez les limites de taux lors de multiples requêtes en ajoutant des délais entre les appels

Applications du monde réel

Le SDK Claude Code permet des intégrations puissantes avec votre flux de travail de développement. Un exemple notable est les Actions GitHub Claude Code, qui utilise le SDK pour fournir des capacités de revue de code automatisée, de création de PR et de triage de problèmes directement dans votre flux de travail GitHub.

Ressources connexes

Utilisation et contrôles CLI - Documentation CLI complète
Intégration GitHub Actions - Automatisez votre flux de travail GitHub avec Claude
Flux de travail courants - Guides étape par étape pour les cas d’usage courants

Premiers pas

Construire avec Claude

Déploiement

Administration

Référence

Ressources

Authentification

Utilisation de base du SDK

Ligne de commande

TypeScript

Python

Utilisation avancée

Conversations multi-tours

Invites système personnalisées

Configuration MCP

Outil d’invite de permission personnalisé

Options CLI disponibles

Formats de sortie

Sortie texte (par défaut)

Sortie JSON

Sortie JSON en streaming

Schéma de message

Formats d’entrée

Entrée texte (par défaut)

Entrée JSON en streaming

Exemples

Intégration de script simple

Traitement de fichiers avec Claude

Gestion de session

Meilleures pratiques

Applications du monde réel

Ressources connexes

Premiers pas

Construire avec Claude

Déploiement

Administration

Référence

Ressources

​Authentification

​Utilisation de base du SDK

​Ligne de commande

​TypeScript

​Python

​Utilisation avancée

​Conversations multi-tours

​Invites système personnalisées

​Configuration MCP

​Outil d’invite de permission personnalisé

​Options CLI disponibles

​Formats de sortie

​Sortie texte (par défaut)

​Sortie JSON

​Sortie JSON en streaming

​Schéma de message

​Formats d’entrée

​Entrée texte (par défaut)

​Entrée JSON en streaming

​Exemples

​Intégration de script simple

​Traitement de fichiers avec Claude

​Gestion de session

​Meilleures pratiques

​Applications du monde réel

​Ressources connexes

Authentification

Utilisation de base du SDK

Ligne de commande

TypeScript

Python

Utilisation avancée

Conversations multi-tours

Invites système personnalisées

Configuration MCP

Outil d’invite de permission personnalisé

Options CLI disponibles

Formats de sortie

Sortie texte (par défaut)

Sortie JSON

Sortie JSON en streaming

Schéma de message

Formats d’entrée

Entrée texte (par défaut)

Entrée JSON en streaming

Exemples

Intégration de script simple

Traitement de fichiers avec Claude

Gestion de session

Meilleures pratiques

Applications du monde réel

Ressources connexes