Le SDK Claude Code permet aux développeurs d’intégrer Claude Code dans leurs applications de manière programmatique. Il permet d’exécuter Claude Code en tant que sous-processus, offrant ainsi un moyen de créer des assistants de codage et des outils alimentés par l’IA qui exploitent les capacités de Claude.

Le SDK est disponible pour une 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 :

  1. Créez une clé API Anthropic dans la Console Anthropic
  2. Ensuite, définissez la variable d’environnement ANTHROPIC_API_KEY. Nous recommandons de stocker cette clé en toute sécurité (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 "Écris une fonction pour calculer les nombres de Fibonacci"

# Utilisation d'un pipe pour fournir stdin
$ echo "Explique ce code" | claude -p

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

# Diffuser la sortie JSON au fur et à mesure qu'elle arrive
$ claude -p "Construis 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 :

ArgumentDescriptionPar défaut
abortControllerContrôleur d’abandonnew AbortController()
cwdRépertoire de travail actuelprocess.cwd()
executableQuel runtime JavaScript utilisernode lors de l’exécution avec Node.js, bun lors de l’exécution avec Bun
executableArgsArguments à passer à l’exécutable[]
pathToClaudeCodeExecutableChemin vers l’exécutable Claude CodeExécutable fourni avec @anthropic-ai/claude-code

Python

Le SDK Python est disponible sous le nom 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 à plusieurs tours

Pour les conversations à plusieurs 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, refactorise 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 "Mettre à jour les tests"

# Continuer en mode impression (non interactif)
$ claude -p --continue "Ajouter 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 "Construire 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éer 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 à l'invite système (fonctionne uniquement avec --print)
$ claude -p "Construire une API REST" --append-system-prompt "Après avoir écrit le 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 l’option --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 des 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"
      }
    }
  }
}

Puis utilisez-le avec Claude Code :

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

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

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

Lors de l’utilisation des outils MCP, vous devez les autoriser explicitement à l’aide de l’option --allowedTools. Les noms des 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 uniquement le nom du serveur (c’est-à-dire mcp__<serverName>), tous les outils de ce serveur seront autorisés.

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

Outil d’invite d’autorisation personnalisé

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

  1. Nous vérifions d’abord les paramètres d’autorisation : tous les fichiers settings.json, ainsi que --allowedTools et --disallowedTools passés au SDK ; si l’un d’entre eux autorise ou refuse l’appel d’outil, nous procédons à l’appel d’outil
  2. 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 renvoyer une charge utile JSON sous forme de chaîne 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 simplement renvoyer l'entrée originale
}

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

Par exemple, une implémentation d’outil d’invite d’autorisation MCP en 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 suit :

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

Notes d’utilisation :

  • Utilisez updatedInput pour indiquer au modèle que l’invite d’autorisation a modifié 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 de modification de fichier à l’utilisateur et lui permet de modifier manuellement le diff, l’outil d’invite d’autorisation doit renvoyer cette modification mise à jour.
  • La charge utile doit être au format JSON stringifié

Options CLI disponibles

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

OptionDescriptionExemple
--print, -pExécuter en mode non interactifclaude -p "requête"
--output-formatSpécifier le format de sortie (text, json, stream-json)claude -p --output-format json
--resume, -rReprendre une conversation par ID de sessionclaude --resume abc123
--continue, -cContinuer la conversation la plus récenteclaude --continue
--verboseActiver la journalisation détailléeclaude --verbose
--max-turnsLimiter les tours agentiques en mode non interactifclaude --max-turns 3
--system-promptRemplacer l’invite système (uniquement avec --print)claude --system-prompt "Instruction personnalisée"
--append-system-promptAjouter à l’invite système (uniquement avec --print)claude --append-system-prompt "Instruction personnalisée"
--allowedToolsListe d’outils autorisés séparés par des espaces, ou

chaîne d’outils autorisés séparés par des virgules
claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsListe d’outils refusés séparés par des espaces, ou

chaîne d’outils refusés séparés par des virgules
claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configCharger les serveurs MCP à partir d’un fichier JSONclaude --mcp-config servers.json
--permission-prompt-toolOutil MCP pour gérer les invites d’autorisation (uniquement avec --print)claude --permission-prompt-tool mcp__auth__prompt

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

Formats de sortie

Le SDK prend en charge plusieurs formats de sortie :

Sortie texte (par défaut)

Renvoie uniquement le texte de la réponse :

$ claude -p "Explique le fichier src/components/Header.tsx"
# Sortie : C'est un composant React qui affiche...

Sortie JSON

Renvoie des données structurées incluant des 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 la réponse ici...",
  "session_id": "abc123"
}

Sortie JSON en streaming

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

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

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

Schéma de message

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

type SDKMessage =
  // Un message d'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, lorsque 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 avec JSONSchema. Nous utilisons le versionnement sémantique pour le package principal Claude Code afin de communiquer les changements majeurs à ce format.

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

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 "Écris une fonction Python pour lire des fichiers CSV"
run_claude "Optimise cette requête de base de données" "json"

Traitement de fichiers avec Claude

# Traiter un fichier avec Claude
$ cat mycode.py | claude -p "Examine ce code pour détecter des bugs"

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

# Utiliser Claude dans un pipeline
$ grep -l "TODO" *.py | while read file; do
    claude -p "Corrige 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 "Initialiser un nouveau projet" --output-format json | jq -r '.session_id' > session.txt

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

Meilleures pratiques

  1. Utiliser le format de sortie JSON pour l’analyse programmatique des réponses :

    # Analyser la réponse JSON avec jq
    result=$(claude -p "Générer du code" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  2. Gérer les erreurs avec élégance - vérifier 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
    
  3. Utiliser la gestion de session pour maintenir le contexte dans les conversations à plusieurs tours

  4. Envisager des délais d’attente pour les opérations de longue durée :

    timeout 300 claude -p "$complex_prompt" || echo "Délai expiré après 5 minutes"
    
  5. Respecter les limites de taux lors de multiples requêtes en ajoutant des délais entre les appels

Applications réelles

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

Ressources connexes