Le SDK Claude Code

Le SDK Claude Code

Le SDK Claude Code vous permet d’exécuter Claude Code de façon programmatique depuis vos propres applications et scripts. Il est disponible pour TypeScript, Python et via le CLI, vous donnant les mêmes fonctionnalités que le terminal mais intégrées dans des workflows plus larges. Vous avez d’ailleurs déjà croisé ce mécanisme sans qu’il soit nommé : le hook de prévention de duplication de la leçon 16 lançait une seconde instance de Claude Code de façon programmatique, et c’est exactement ce que le SDK rend possible.

Un malentendu fréquent mérite d’être levé tout de suite. Le SDK n’est ni une version allégée ni un client API de bas niveau : il exécute exactement le même Claude Code que celui que vous utilisez déjà. Il a accès à tous les mêmes outils et les utilisera pour compléter la tâche que vous lui donnez, en enchaînant lectures, recherches et éditions comme il le ferait dans votre terminal.

Caractéristiques clés

Cette continuité se retrouve dans la configuration. Le SDK hérite de tous les paramètres des instances Claude Code dans le même répertoire : votre CLAUDE.md, vos commandes personnalisées, vos serveurs MCP et vos hooks s’appliquent sans que vous ayez à les redéclarer. Un script lancé depuis la racine du projet travaille donc avec le même contexte qu’une session interactive, ce qui supprime les écarts de comportement entre ce que vous testez à la main et ce que votre pipeline exécute la nuit.

Une différence importante subsiste toutefois : les permissions sont en lecture seule par défaut. Le choix est cohérent avec l’usage visé, puisqu’un script s’exécute sans personne pour valider une opération risquée. Le SDK trouve ainsi son meilleur emploi comme partie de pipelines ou d’outils plus larges, là où une intervention humaine n’est ni possible ni souhaitable.

Utilisation basique

Voici un exemple simple en TypeScript qui demande à Claude d’analyser du code :

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

const prompt =
  "Cherche des requetes en doublon dans le dossier ./src/queries";

for await (const message of query({ prompt })) {
  console.log(JSON.stringify(message, null, 2));
}

Quand vous exécutez ce code, vous verrez la conversation brute entre votre Claude Code local et le modèle Claude, message par message. La boucle for await mérite l’attention : query ne renvoie pas un résultat final mais un flux. Défilent alors les décisions d’utilisation d’outils, les résultats de ces outils, puis les réponses du modèle. C’est aussi ce qui vous permet de réagir en cours de route au lieu d’attendre la fin.

Permissions et outils

Par défaut, le SDK n’a que des permissions de lecture seule. Il peut lire des fichiers, parcourir des répertoires et effectuer des recherches grep, mais il ne peut pas écrire, éditer ou créer de fichiers. Un script d’analyse — chercher des doublons, produire un rapport, vérifier une convention — fonctionne donc tel quel, sans configuration supplémentaire, et ne peut rien casser au passage.

Pour activer les permissions d’écriture, ajoutez l’option allowedTools :

for await (const message of query({
  prompt,
  options: {
    allowedTools: ["Edit", "Write"]
  }
})) {
  console.log(JSON.stringify(message, null, 2));
}

Le geste est délibérément explicite. Vous n’ouvrez pas les droits en bloc : vous nommez les outils que vous acceptez de confier à ce script précis, et rien d’autre ne sera disponible pour lui.

Applications pratiques

Reste à savoir où brancher tout cela. Un hook Git est un candidat naturel : le SDK peut passer en revue automatiquement les changements avant un commit et refuser ceux qui ne tiennent pas la route. Dans un script de build, il analyse et optimise le code pendant la construction, à un moment où l’ensemble des sources est de toute façon parcouru. Vous pouvez également en faire des commandes d’aide à la maintenance du code, exécutées à la demande sur une partie du projet, ou lui confier la génération automatique de documentation à partir des sources — cette tâche fastidieuse que personne ne fait spontanément. En CI/CD, enfin, il ajoute des vérifications de qualité de code que les linters classiques ne savent pas exprimer, parce qu’elles supposent de comprendre l’intention et pas seulement la syntaxe.

Le SDK vous permet donc d’ajouter de l’intelligence IA à n’importe quelle partie de votre processus de développement où un accès programmatique serait utile. La bonne question à se poser n’est pas « que sait faire le SDK », puisqu’il sait faire tout ce que fait Claude Code, mais « quelle tâche répétitive de mon pipeline mériterait un lecteur attentif ».