Guide CLI Claude Code : installation, configuration, commandes, variables d'environnement

En résumé : Claude Code est un CLI agentique qui analyse votre codebase, exécute des commandes et modifie des fichiers grâce à un système multicouche de permissions, de hooks, d’intégrations MCP et de subagents. Maîtrisez cinq systèmes fondamentaux (configuration, permissions, hooks, MCP et subagents) et vous débloquerez une productivité démultipliée. Choisissez le niveau de modèle adapté à chaque tâche — Opus pour le raisonnement complexe, Sonnet pour le travail courant, Haiku pour l’exploration rapide — ou standardisez sur Opus si la qualité est votre seule variable. Utilisez les hooks (et non les prompts) pour tout ce qui doit s’exécuter systématiquement.

Claude Code fonctionne comme un système agentique, et non comme une interface de chat dotée de connaissances en programmation. Le CLI analyse votre codebase, exécute des commandes, modifie des fichiers, gère les workflows git, se connecte à des services externes via MCP et délègue les tâches complexes à des subagents spécialisés. Tout passe par une interface en ligne de commande qui s’intègre à la manière dont les développeurs travaillent réellement. En février 2026, 4 % des commits publics GitHub (~135 000 par jour) sont rédigés par Claude Code — une croissance de 42 896× en 13 mois depuis la version de recherche préliminaire — et 90 % du code d’Anthropic est généré par IA.¹¹⁰

La différence entre un usage basique et un usage efficace de Claude Code repose sur cinq systèmes fondamentaux. Maîtrisez-les et Claude Code devient un multiplicateur de force :

1. Hiérarchie de configuration : contrôle le comportement
2. Système de permissions : encadre les opérations
3. Système de hooks : permet l’automatisation déterministe
4. Protocole MCP : étend les capacités
5. Système de subagents : gère les tâches complexes en plusieurs étapes

Points clés

• Cinq systèmes déterminent votre efficacité : hiérarchie de configuration, permissions, hooks, MCP et subagents contrôlent tout, du comportement à l’automatisation.
• Déléguez le travail à la couche de délégation : les subagents évitent l’engorgement du contexte en isolant l’exploration dans des fenêtres de contexte propres, ne renvoyant que des résumés.
• Les hooks garantissent l’exécution ; les prompts, non : utilisez les hooks pour le linting, le formatage et les vérifications de sécurité qui doivent s’exécuter à chaque fois, indépendamment du comportement du modèle.
• L’échelonnement des modèles réduit les coûts sans sacrifier la qualité : orientez l’exploration des subagents vers des modèles moins coûteux et réservez Opus au raisonnement architectural véritable — ou standardisez sur Opus si la qualité est votre seule variable.
• MCP connecte Claude à votre chaîne d’outils : bases de données, GitHub, Sentry et plus de 3 000 intégrations étendent Claude au-delà de la lecture de fichiers et des commandes bash.

J’ai passé des mois à pousser Claude Code dans ses retranchements sur des codebases de production, des pipelines CI/CD et des déploiements en entreprise. Ce guide condense cette expérience en la référence complète que j’aurais aimé avoir à mes débuts. Chaque fonctionnalité inclut la syntaxe réelle, des exemples de configuration concrets et les cas limites qui piègent même les utilisateurs expérimentés.

Choisissez votre parcours

Comment utiliser ce guide

Ce guide de plus de 5 000 lignes n’est pas conçu pour être lu de bout en bout. Commencez là où votre niveau d’expérience vous situe :

Utilisez Ctrl+F / Cmd+F de votre navigateur pour rechercher des flags, commandes ou clés de configuration spécifiques. La Carte de référence rapide en fin de guide fournit un résumé synthétique de toutes les commandes principales.

Approfondissements complémentaires

Ces articles de blog explorent en détail des aspects spécifiques de Claude Code :

Démarrage rapide en 60 secondes

Si vous voulez simplement lancer Claude Code et voir un résultat, faites ceci dans l’ordre :

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

C’est tout. Tout ce qui suit cette section détaille les options d’installation, configure les permissions et les hooks, met en place les serveurs MCP et couvre le déploiement en entreprise — mais rien de tout cela n’est nécessaire pour commencer.

Prérequis : Node 18+ (pour la voie npm), macOS / Linux / Windows 10+. Un abonnement Claude Pro, Max, Team ou Enterprise, ou une clé Anthropic API à l’usage, couvre l’utilisation. Consultez Comment installer Claude Code ? pour les spécificités de chaque plateforme, le dépannage et la voie du binaire natif (par défaut depuis la v2.1.113).

Fonctionnement de Claude Code : le modèle mental

Avant de plonger dans les fonctionnalités, il faut comprendre comment l’architecture de Claude Code façonne tout ce que vous faites avec lui. Le système fonctionne en trois couches :

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Couche Core : votre conversation principale. Chaque message, lecture de fichier et sortie d’outil consomme du contexte dans une fenêtre partagée (200K tokens en standard⁹⁸, 1M tokens avec Opus 4.6 ou les modèles à contexte étendu). Lorsque le contexte se remplit, Claude perd la trace des décisions antérieures et la qualité se dégrade. Cette couche coûte de l’argent par token.

Couche Delegation : les subagents sont lancés avec des contextes vierges, effectuent un travail ciblé et renvoient des résumés. Les résultats d’exploration n’encombrent pas votre conversation principale ; seules les conclusions reviennent. Orientez les subagents vers des paliers de modèles moins coûteux pour l’exploration, ou utilisez votre modèle principal tout du long si la qualité compte plus que le coût.

Couche Extension : MCP connecte des services externes (bases de données, GitHub, Sentry). Les hooks garantissent l’exécution de commandes shell indépendamment du comportement du modèle. Les skills encodent une expertise métier que Claude applique automatiquement. Les plugins empaquettent tous ces éléments pour la distribution.

L’idée clé : la plupart des utilisateurs travaillent entièrement dans la couche Core, voyant le contexte gonfler et les coûts grimper. Les utilisateurs avancés poussent l’exploration et les travaux spécialisés vers la couche Delegation, gardent la couche Extension configurée pour leur flux de travail, et n’utilisent la couche Core que pour l’orchestration et les décisions finales.

Table des matières

1. Comment installer Claude Code ?
2. Démarrage rapide : votre première session
3. Modes d’interaction principaux
4. Exploration approfondie du système de configuration
5. Quel modèle choisir ?
6. Combien coûte Claude Code ?
7. Cadres de décision
8. Comment fonctionne le système de permissions ?
9. Comment fonctionnent les hooks ?
10. Qu’est-ce que MCP (Model Context Protocol) ?
11. Qu’est-ce que les subagents ?
12. Qu’est-ce que le mode de réflexion étendue ?
13. Styles de sortie
14. Slash commands
15. Comment fonctionnent les skills ?
16. Système de plugins
17. Comment fonctionne la mémoire ?
18. Entrée image et multimodale
19. Mode vocal
20. Comment fonctionne l’intégration Git ?
21. Comment utiliser Claude Code dans mon IDE ?
22. Modèles d’utilisation avancés
23. Agents distants et en arrière-plan [APERÇU DE RECHERCHE]
24. Claude dans Chrome
25. Claude Code dans Slack [APERÇU DE RECHERCHE]
26. Claude Code sur le Web [APERÇU DE RECHERCHE]
27. Optimisation des performances
28. Comment déboguer les problèmes ?
29. Déploiement en entreprise
30. Référence des raccourcis clavier
31. Bonnes pratiques
32. Recettes de flux de travail
33. Guide de migration
34. Conseils par type de public
35. Fiche de référence rapide
36. Journal des modifications
37. Références

Comment installer Claude Code ?

Configuration système requise

Claude Code fonctionne sur macOS 13+, Ubuntu 20.04+/Debian 10+ et Windows 10+ (natif ou WSL). Le système nécessite au minimum 4 Go de RAM et une connexion internet active.⁹⁹ La compatibilité shell est optimale avec Bash, Zsh ou Fish.

Pour Windows, WSL 1 et WSL 2 fonctionnent tous les deux. Git Bash fonctionne également si vous préférez Windows natif. Alpine Linux et les autres systèmes basés sur musl nécessitent des paquets supplémentaires :

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Matrice de prise en charge des plateformes

Installation, mise à jour et désinstallation en un coup d’œil

Référence à parcourir : chaque méthode, chaque commande, vérification de version sur un seul écran. Les sous-sections ci-dessous couvrent les spécificités et le dépannage par méthode.

Depuis la v2.1.113, le CLI canonique lance un binaire Claude Code natif via une dépendance optionnelle par plateforme au lieu de JavaScript intégré — utilisez l’installateur natif pour la distribution testée. La voie npm fonctionne toujours mais reçoit l’avis de dépréciation initialement ajouté dans la v2.1.15.

Méthodes d’installation

Installation native (recommandée)

Le binaire natif offre l’expérience la plus propre, sans dépendance à Node.js :

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Pour une installation d’une version spécifique :

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Installation NPM (dépréciée)

Note : Depuis la v2.1.15, les installations npm affichent un avis de dépréciation. Le binaire natif est désormais la méthode d’installation recommandée. Migrez avec claude install.

Pour les environnements anciens où npm est encore nécessaire :

npm install -g @anthropic-ai/claude-code

N’utilisez jamais sudo avec l’installation npm. Cela crée des problèmes de permissions qui compliquent tout par la suite.

Migration depuis une installation existante

Si vous disposez d’une ancienne installation basée sur npm, migrez vers le binaire natif :

claude install

Options d’authentification

Claude Code prend en charge trois voies d’authentification, chacune avec des compromis différents :

Console Claude (facturation API)

Connectez-vous directement à la API d’Anthropic via platform.claude.com (anciennement console.anthropic.com). Créez un compte, configurez la facturation et authentifiez-vous via le CLI. La Console offre une facturation à l’usage avec un accès complet à l’API. Un espace de travail dédié « Claude Code » est créé automatiquement ; vous ne pouvez pas créer de clés API pour cet espace de travail, mais vous pouvez surveiller l’utilisation.

Abonnement Claude Pro ou Max

Utilisez les identifiants de votre compte claude.ai. L’abonnement couvre à la fois l’interface web et l’utilisation du CLI dans le cadre d’un seul forfait mensuel. L’abonnement simplifie la facturation pour les utilisateurs individuels qui souhaitent des coûts prévisibles.

Plateformes d’entreprise

AWS Bedrock, Google Vertex AI et Microsoft Foundry offrent chacune un accès de niveau entreprise avec des relations de facturation cloud existantes. Assistant de configuration Bedrock (v2.1.92+) : un assistant interactif sur l’écran de connexion vous guide à travers l’authentification AWS, la sélection de la région, la vérification des identifiants et l’épinglage du modèle.¹⁴⁴ Assistant de configuration Vertex AI (v2.1.98+) : un assistant équivalent pour Google Cloud, guidant l’authentification GCP, la configuration du projet et de la région, la vérification des identifiants et l’épinglage du modèle.¹⁴⁹ Vertex AI mTLS Workload Identity Federation (v2.1.121+) : Vertex AI accepte désormais la Workload Identity Federation basée sur des certificats X.509 (mTLS Application Default Credentials) — des jetons GCP de courte durée frappés à partir d’un certificat client, sans JSON de compte de service requise.¹⁶¹ Confiance des certificats CA du système d’exploitation (v2.1.101+) : les proxys TLS d’entreprise fonctionnent désormais par défaut — Claude Code fait confiance au magasin de certificats du système d’exploitation. Définissez CLAUDE_CODE_CERT_STORE=bundled pour utiliser uniquement les CA intégrées.¹⁵⁰

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

Pour les déploiements en entreprise derrière des proxys ou via des passerelles LLM :

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Vérification

claude doctor

La commande indique le type d’installation, la version, la configuration système et tout problème détecté.

Gestion de l’authentification (v2.1.41+)

Gérez l’authentification sans entrer dans le REPL :⁹⁷

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

Flux de travail courant pour basculer entre des comptes ou organisations :

claude auth logout && claude auth login

Voir aussi : Comment déboguer les problèmes ? pour résoudre les échecs d’authentification.

Mises à jour

Claude Code se met à jour automatiquement par défaut, en vérifiant au démarrage et périodiquement pendant les sessions. Les mises à jour sont téléchargées en arrière-plan et appliquées au prochain lancement.

Désactiver les mises à jour automatiques :

export DISABLE_AUTOUPDATER=1

Ou dans settings.json :

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Mise à jour manuelle :

claude update

Désinstallation

Installation native (macOS/Linux/WSL) :

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Installation native (Windows PowerShell) :

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Configuration propre (supprime tous les paramètres) :

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Démarrage rapide : votre première session

1. Installer et lancer :

claude                           # Launch in current directory

2. Naviguer vers un projet :

cd ~/my-project && claude        # Or launch from any git repo

3. Demander à Claude de faire quelque chose :

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Utiliser les raccourcis clés pendant votre session :

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Reprendre plus tard :

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Astuce d’expert : créez un fichier CLAUDE.md à la racine de votre projet avec les commandes de build, les conventions de code et les notes d’architecture. Claude le lit à chaque session — c’est l’action à plus fort effet de levier que vous puissiez entreprendre pour la qualité.

Modes d’interaction principaux

REPL interactif

Lancez Claude Code sans arguments pour entrer dans la boucle interactive read-eval-print :

cd your-project
claude

Le REPL conserve le contexte de conversation entre les tours. Saisissez vos requêtes directement, recevez des réponses et continuez jusqu’à ce que vous quittiez avec /exit ou Ctrl+D.

Commencez par une invite initiale pour cadrer la session :

claude "explain the authentication flow in this project"

Astuce d’expert : le REPL conserve son état lors des événements de compactage. Lorsque le contexte devient trop volumineux, Claude résume automatiquement les conversations plus anciennes tout en préservant les décisions clés et les extraits de code. Vous pouvez déclencher cela manuellement avec /compact ou ajouter des instructions personnalisées sur ce qu’il faut préserver.

Mode non interactif

Le mode print (-p) exécute une seule requête puis se termine :

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Pour une sortie structurée adaptée au parsing dans des scripts :

claude -p "count lines by file type" --output-format json

La sortie JSON inclut tout ce dont vous avez besoin pour l’automatisation :

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Pour le traitement en temps réel d’une sortie en streaming :

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Options de format de sortie :

Codes de sortie :

Contrôler le comportement agentique en mode -p :

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

Modèle d’intégration CI/CD :

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Gestion des sessions

Les sessions conservent l’historique des conversations pour permettre leur reprise. La persistance des sessions est essentielle pour un travail complexe réparti sur plusieurs sessions :

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Sessions liées aux PR (v2.1.27+, étendu en v2.1.119+) : démarrez une session liée à une pull ou merge request spécifique. Depuis la v2.1.119, --from-pr accepte les URL de MR GitLab, de PR Bitbucket et de PR GitHub Enterprise en plus de github.com :⁸¹¹⁵⁹

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

Les sessions sont également auto-liées aux PR lorsque vous les créez via gh pr create durant une session. Cela facilite la reprise du travail sur une PR spécifique plus tard. Le badge PR du pied de page peut pointer vers une URL de revue de code personnalisée via le paramètre prUrlTemplate (v2.1.119+) — pratique lorsque votre équipe relie les PR à un outil de revue séparé.¹⁵⁹

/resume accepte les URL de PR (v2.1.122+). Coller une URL de PR dans le champ de recherche /resume retrouve désormais la session qui a initialement créé cette PR — fonctionne sur github.com, GitHub Enterprise, gitlab.com (et GitLab auto-hébergé) et bitbucket.org.¹⁶¹

Sessions nommées : nommez les sessions au démarrage ou pendant une session :

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Note : --session-id requiert un UUID valide (par exemple, 550e8400-e29b-41d4-a716-446655440000). Pour un nommage de session lisible par un humain, utilisez plutôt /rename et --resume.

Claude Code stocke les sessions sous forme de transcripts JSONL. L’exécution d’agent assigne des valeurs agentId uniques avec des transcripts stockés sous agent-{agentId}.jsonl. La reprise préserve le contexte complet des conversations précédentes.

Mode Plan

Le mode plan restreint Claude à de l’exploration en lecture seule — pas d’édition de fichiers, pas d’exécution bash, pas d’actions destructrices. Claude conçoit une approche d’implémentation, l’écrit dans un fichier de plan et attend votre approbation avant d’exécuter quoi que ce soit.

Entrer en mode plan :

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

Comment cela fonctionne :

1. Claude entre en mode plan (automatiquement pour les tâches complexes, ou via Shift+Tab)
2. Explore la base de code en utilisant des outils en lecture seule : Read, Glob, Grep, WebSearch, WebFetch
3. Écrit un plan dans .claude/plans/{session-slug}.md
4. Sort du mode plan avec ExitPlanMode, présentant le plan pour votre revue
5. Vous approuvez, demandez des modifications ou rejetez

Outils disponibles en mode plan : Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. Les outils d’édition (Edit, Write, Bash, NotebookEdit) sont bloqués.

Après l’approbation du plan (v2.1.32+) : Claude propose trois options : - « Yes, clear context and auto-accept edits » (Shift+Tab) — démarre à neuf avec un contexte complet pour le plan - « Yes, and manually approve edits » — préserve le contexte, vous approuvez chaque modification - « Yes, auto-accept edits » — préserve le contexte, Claude exécute sans approbation par modification

Le nettoyage automatique du contexte à l’approbation est le workflow recommandé. Il offre au plan une fenêtre de contexte fraîche, ce qui améliore considérablement le respect du plan — Claude reste sur la bonne voie plus longtemps sans interférence d’anciennes conversations.

Quand utiliser le mode plan : - Implémentations de nouvelles fonctionnalités impliquant des décisions architecturales - Refactorings multi-fichiers où vous voulez d’abord revoir l’approche - Bases de code méconnues où l’exploration doit précéder la modification - Toute tâche où plusieurs approches valides existent et où vous voulez donner votre avis

Astuce d’expert : plus vous passez de temps en mode plan, plus Claude a de chances de réussir l’implémentation. Le mode plan est essentiellement de l’exploration sans coût — pas d’appels d’outils risqués, pas de modifications gaspillées. Utilisez-le sans retenue.

Plongée approfondie dans le système de configuration

Claude Code utilise un système de configuration en couches. Comprendre la hiérarchie est essentiel, car les niveaux supérieurs remplacent les niveaux inférieurs, et les paramètres d’entreprise ne peuvent absolument pas être contournés.

Hiérarchie de configuration

Astuce d’expert : utilisez .claude/settings.local.json pour les préférences personnelles dans les projets partagés (ajoutez-le à .gitignore). Utilisez .claude/settings.json pour la configuration à l’échelle de l’équipe qui sera versionnée dans le contrôle de version.

Référence complète de settings.json

Une configuration complète illustrant toutes les options principales :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

Référence des variables d’environnement

Authentification et API :

ANTHROPIC_API_KEY=sk-ant-...                    # Authentification API directe
ANTHROPIC_AUTH_TOKEN=token                      # En-tête d'autorisation personnalisé
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # En-têtes de requête supplémentaires

Configuration du modèle :

ANTHROPIC_MODEL=claude-opus-4-7                 # Remplacer le modèle par défaut (16 avril 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (par défaut Max/Team Premium)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Modèle pour les subagents
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 et Sonnet 4.6 uniquement — supprimé dans Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limiter la longueur de sortie
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Activer les équipes d'agents (v2.1.32+)

Configuration du fournisseur cloud :

CLAUDE_CODE_USE_BEDROCK=1                       # Utiliser AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Utiliser Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Utiliser Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Point de terminaison Bedrock personnalisé
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Niveau de service Bedrock (v2.1.122+) : 'default', 'flex' ou 'priority' ; envoyé via l'en-tête X-Amzn-Bedrock-Service-Tier[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Ignorer l'authentification Bedrock (pour les passerelles)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Ignorer l'authentification Vertex
AWS_BEARER_TOKEN_BEDROCK=token                  # Jeton bearer Bedrock
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Remplacer la région Vertex

Contrôle du comportement :

DISABLE_AUTOUPDATER=1                           # Empêcher les mises à jour automatiques en arrière-plan
DISABLE_UPDATES=1                               # Bloquer TOUS les chemins de mise à jour, y compris `claude update` manuel (v2.1.118+, plus strict que DISABLE_AUTOUPDATER)[^160]
DISABLE_TELEMETRY=1                             # Refuser la télémétrie d'utilisation
DISABLE_ERROR_REPORTING=1                       # Désactiver Sentry
DISABLE_BUG_COMMAND=1                           # Désactiver la commande /bug
DISABLE_COST_WARNINGS=1                         # Masquer les avertissements de coût
DISABLE_PROMPT_CACHING=1                        # Désactiver la mise en cache des prompts globalement
DISABLE_PROMPT_CACHING_SONNET=1                 # Désactiver pour Sonnet uniquement
DISABLE_PROMPT_CACHING_OPUS=1                   # Désactiver pour Opus uniquement
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Ignorer les appels API non critiques
ENABLE_PROMPT_CACHING_1H=1                      # Opter pour un TTL de cache de prompt d'1 heure (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Alias obsolète de la variable ci-dessus ; v2.1.108+ continue de l'honorer sur Bedrock mais consigne un avis de dépréciation
FORCE_PROMPT_CACHING_5M=1                       # Forcer un TTL de cache de 5 minutes (v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # Réactiver la recherche d'outils sur Vertex AI (désactivée par défaut en v2.1.119+ pour éviter un en-tête bêta non pris en charge). Valeurs valides : true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Masquer le répertoire de travail dans le logo de démarrage (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Activer les subagents forkés sur les builds externes (v2.1.117+)[^160]

Configuration des outils :

BASH_DEFAULT_TIMEOUT_MS=30000                   # Délai d'expiration des commandes Bash (30 s)
BASH_MAX_TIMEOUT_MS=600000                      # Délai d'expiration maximal de bash (10 min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Limite de sortie Bash
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Réinitialiser le CWD après chaque bash
MCP_TIMEOUT=5000                                # Délai d'expiration au démarrage du serveur MCP
MCP_TOOL_TIMEOUT=30000                          # Délai d'expiration de l'exécution de l'outil MCP
MAX_MCP_OUTPUT_TOKENS=25000                     # Limite de sortie MCP
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Limite de contexte des slash commands

Réseau et proxy :

HTTP_PROXY=http://proxy:8080                    # Proxy HTTP
HTTPS_PROXY=https://proxy:8080                  # Proxy HTTPS
NO_PROXY=localhost,example.com                  # Contourner le proxy pour certains domaines
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # Certificat mTLS
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # Clé privée mTLS
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # Phrase de passe mTLS

UI et terminal :

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Ne pas mettre à jour le titre du terminal
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Ignorer l'installation de l'extension IDE
CLAUDE_CODE_SHELL=/bin/zsh                      # Remplacer la détection du shell
USE_BUILTIN_RIPGREP=1                           # Utiliser le ripgrep inclus (par défaut)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Répertoire de configuration personnalisé
IS_DEMO=1                                       # Masquer les éléments d'UI sensibles[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Désactiver les tâches en arrière-plan et Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Remplacer le répertoire temp[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Désactiver la fenêtre de contexte de 1M (utiliser le 200K standard)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Délai d'expiration git du marketplace de plugins (par défaut 120 s, anciennement 30 s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Supprimer les instructions intégrées de commit/PR[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Arrêter les tâches cron planifiées en cours de session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # Délai d'expiration des hooks SessionEnd (la valeur par défaut varie)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Activer l'outil PowerShell de Windows sur Linux/macOS (nécessite pwsh dans le PATH ; v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Forcer Session Recap lorsque la télémétrie est désactivée (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Émettre les corps complets des requêtes/réponses API comme événements de log OTel (v2.1.111+)[^153]
TRACEPARENT=00-...                            # Parent W3C Trace Context (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # État W3C Trace Context (v2.1.110+, SDK/headless)[^153]

Exportateurs OpenTelemetry + filtrage des champs sensibles :¹⁶³

OTEL_LOGS_EXPORTER=none                       # Exportateur de logs OTel (prend en charge 'none' pour désactiver ; v2.1.85 a corrigé le crash)
OTEL_METRICS_EXPORTER=none                    # Exportateur de métriques OTel (prend en charge 'none' ; v2.1.85 a corrigé le crash)
OTEL_TRACES_EXPORTER=none                     # Exportateur de traces OTel (prend en charge 'none' ; v2.1.85 a corrigé le crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opter pour l'émission du contenu des outils dans les spans OTel (v2.1.101+, sensible par défaut)
OTEL_LOG_TOOL_DETAILS=1                       # Opter pour les tool_parameters dans les événements tool_result OTel (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opter pour l'émission des prompts utilisateur dans les traces OTel (v2.1.101+, sensible par défaut)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Désactiver la récupération des notes de version (v2.0.17+) ; v2.1.110 a aussi arrêté la requête Haiku d'auto-titre en headless/SDK lorsqu'elle est définie

Attributs de span de requête LLM en v2.1.121+ : stop_reason, gen_ai.response.finish_reasons et user_system_prompt sont désormais émis sur les spans de requête LLM. user_system_prompt est protégé derrière OTEL_LOG_USER_PROMPTS=1 car il peut contenir des informations personnelles identifiables (PII).¹⁶¹

Changements au niveau des événements en v2.1.122+ : les attributs numériques sur les événements de log api_request et api_error sont désormais émis sous forme de nombres (auparavant des chaînes) — corrige les collecteurs OTel en aval qui typaient strictement le schéma. Un nouvel événement de log claude_code.at_mention se déclenche lorsque Claude Code résout une mention @.¹⁶¹

Contrôle API / Modèle :¹⁶³

CLAUDE_CODE_EXTRA_BODY='{...}'                # Injecter des champs de corps supplémentaires dans les appels API ; v2.1.113 a corrigé les erreurs 400 avec output_config.effort sur les appels Vertex/subagent
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Remplacer le maximum de tokens de contexte (variable préexistante ; v2.1.98 a corrigé la gestion de DISABLE_COMPACT lorsque les deux sont définies)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Remplacer la limite de tokens par défaut pour les opérations de lecture de fichiers (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Ne pas se rabattre sur API non-streaming en cas d'échec de streaming (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Activer les en-têtes bêta API ; v2.1.78 a corrigé l'ignorance silencieuse sur les modèles Haiku
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # ID du modèle rapide (ARN Bedrock pris en charge ; v0.2.125 a cessé d'échapper les barres obliques dans l'ARN)

Plugins / MCP :¹⁶³

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Répertoire de cache des plugins (v2.1.72 a corrigé le répertoire littéral '~' sur certains shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Préserver le cache du marketplace de plugins en cas d'échec de git pull (compatible hors ligne ; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Transmis aux scripts MCP headersHelper afin qu'un seul helper puisse desservir plusieurs serveurs (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Transmis aux scripts MCP headersHelper en plus du nom (v2.1.85+)

Shell / IDE :¹⁶³

CLAUDE_CODE_SHELL_PREFIX="time "              # Englober chaque commande shell invoquée par Claude avec un préfixe (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Chemin Git Bash personnalisé sur Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK : quitter après N ms d'inactivité (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Désactiver l'auto-connexion à l'IDE (v1.0.61+)

Entreprise / authentification :¹⁶³

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opter pour la résolution DNS côté proxy (v2.0.55 est passée d'activé par défaut à opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL pour les clés API générées dynamiquement via apiKeyHelper (rafraîchissement apiKeyHelper ajouté en v0.2.74 avec un défaut de 5 min ; variable d'env ajoutée en v0.2.117)

Variables de skill (v2.1.69+) :

${CLAUDE_SKILL_DIR}                            # Auto-référence permettant aux skills de localiser leur propre répertoire[^117]

Identité de l’appelant SDK (v2.1.51+) :

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Fournir l'UUID de compte de manière synchrone pour les appelants SDK
CLAUDE_CODE_USER_EMAIL=[email protected]        # Fournir l'e-mail de l'utilisateur pour les appelants SDK
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Fournir l'UUID de l'organisation pour les appelants SDK

Débogage :

ANTHROPIC_LOG=debug                             # Activer la journalisation des requêtes API

Quel modèle dois-je choisir ?

Choisir le bon modèle pour chaque tâche a un impact significatif à la fois sur le coût et sur la qualité. Claude Code propose une commutation de modèle flexible à plusieurs niveaux.

Modèles disponibles

Opus 4.7 (16 avril 2026) : Le modèle phare actuel. Fenêtre de contexte de 1M tokens au tarif standard — pas de surcoût pour le contexte long. 128K de sortie max, uniquement le raisonnement adaptatif (le raisonnement étendu a été supprimé), et un nouveau niveau d’effort xhigh recommandé comme point de départ pour les charges de travail de codage et agentiques.¹⁵² Date limite des connaissances fiable : janvier 2026. Date limite des données d’entraînement : janvier 2026. ID du modèle : claude-opus-4-7. Tarification identique à Opus 4.6 à 5 $/25 $ par MTok avec écriture cache 5 min à 6,25 $, écriture cache 1 h à 10 $, et lecture cache à 0,50 $ par MTok.¹⁵¹ Opus 4.7 résout 3× plus de tâches en production sur SWE-Bench qu’Opus 4.6, obtient 70 % sur CursorBench (contre 58 % pour 4.6), et améliore la résolution de 13 % sur le benchmark de codage interne de 93 tâches d’Anthropic.¹⁵¹ Utilise un nouveau tokenizer — attendez-vous à environ 1×–1,35× du nombre de tokens pour le même texte ; augmentez la marge max_tokens et les déclencheurs de compactage.¹⁵² La vision prend en charge des images jusqu’à 2 576 px / 3,75 MP avec des coordonnées de pixels 1:1.¹⁵²

Benchmarks de codage Opus 4.7 (avril 2026) :¹⁵⁸

Opus 4.7 mène SWE-bench Verified avec 12,7 points d’avance sur la référence largement citée GPT-5-Codex et SWE-bench Pro avec 6,6 points d’avance sur GPT-5.4 (57,7 %). Sur Terminal-Bench 2.0, GPT-5.3-Codex devance encore GPT-5.4 (77,3 % contre 75,1 %) et tous deux surpassent Opus 4.7 (69,4 %). Le leadership en matière de benchmarks est fluctuant ; consultez les pages des fournisseurs avant de vous engager pour un choix de plusieurs trimestres.

Modèle par défaut selon le plan (Claude Code) :¹⁵⁴

Opus 4.7 nécessite Claude Code v2.1.111 ou ultérieur ; exécutez claude update pour mettre à niveau.¹⁵⁴ Bedrock, Vertex et Foundry exposent Opus 4.7 via les noms complets explicites du modèle ou des épinglages ANTHROPIC_DEFAULT_OPUS_MODEL, et non via l’alias opus par défaut.¹⁵⁴

Changements d’API Messages avec rupture dans Opus 4.7 (visibles côté appelant) :¹⁵²

• Le budget_tokens du raisonnement étendu est supprimé. Utilisez plutôt thinking: {type: "adaptive"}. Le raisonnement adaptatif est désactivé par défaut ; les requêtes sans champ thinking s’exécutent sans raisonnement.
• Définir temperature, top_p ou top_k à une valeur autre que celle par défaut renvoie HTTP 400. Omettez ces paramètres et orientez le modèle via le prompting.
• Le contenu du raisonnement est omis des réponses par défaut. Définissez thinking.display: "summarized" pour restaurer le raisonnement visible (requis si votre produit diffuse le raisonnement aux utilisateurs).

Les budgets de tâches (en-tête bêta task-budgets-2026-03-13) vous permettent d’indiquer au modèle un objectif de tokens sur l’ensemble d’une boucle agentique via output_config.task_budget ; minimum 20K tokens.¹⁵²

Opus 4.6 (legacy) : Toujours disponible sous claude-opus-4-6 avec un contexte de 1M et une sortie max de 128K. Envisagez de migrer vers Opus 4.7 pour un meilleur codage agentique. Opus 4.6 a été initialement publié le 5 février 2026.⁸⁶¹⁵¹ Depuis la v2.1.117 (22 avril 2026), les abonnés Pro et Max passent par défaut à l’effort high sur Opus 4.6 et Sonnet 4.6 (auparavant medium) ; Opus 4.7 reste à xhigh. Ce changement a restauré l’intelligence après la rétrogradation d’effort du 4 mars au 7 avril, documentée dans le post-mortem du 23 avril.¹⁵⁹¹⁶⁰

Sonnet 4.6 (17 février 2026) : Modèle équilibré ; a remplacé Sonnet 4.5 comme modèle par défaut sur claude.ai et Claude Cowork.¹⁰⁰ Tarification identique à Sonnet 4.5 (3 $/15 $ par MTok). Performances de recherche agentique améliorées tout en consommant moins de tokens. Prend en charge le raisonnement étendu, le raisonnement adaptatif et une fenêtre de contexte de 1M tokens (bêta). Sortie max de 64K (limite supérieure 128K en v2.1.77).¹²⁶ Date limite des connaissances : août 2025 (fiable), janvier 2026 (données d’entraînement). ID du modèle : claude-sonnet-4-6.

Claude Mythos Preview (7 avril 2026) : Un modèle de frontière en aperçu de recherche pour le travail de cybersécurité défensive, proposé dans le cadre du projet Glasswing.¹⁴⁶ Sur invitation uniquement ; non disponible au grand public. Anthropic présente Opus 4.7 comme délibérément moins capable que Mythos sur les dimensions cyber — un compromis de sécurité — et a ouvert un Cyber Verification Program à l’adresse https://claude.com/form/cyber-use-case pour les chercheurs en sécurité légitimes ayant besoin d’un accès élevé.¹⁵³

Pourquoi ces différences de prix sont importantes : Une session de codage typique consomme 50K-200K tokens en entrée et 10K-50K tokens en sortie. Avec Haiku, cela représente 0,10 $-0,45 $ par session. Avec Opus, la même session coûte 0,50 $-2,25 $, soit 5× plus. Réservez Opus pour les problèmes véritablement difficiles.¹

Quand utiliser chaque modèle

Haiku : À utiliser pour les subagents effectuant de l’exploration, des recherches simples de fichiers, des questions rapides. Il est environ 5× moins cher qu’Opus et répond plus rapidement. Parfait pour les tâches en arrière-plan où vous n’avez pas besoin d’un raisonnement profond.

Sonnet : Le cheval de bataille pour le développement quotidien lorsque le coût compte. Gère la plupart des tâches de codage : implémentation de fonctionnalités, correction de bugs, écriture de tests, revue de code. Sonnet 4.6 offre une recherche agentique améliorée et une meilleure efficacité des tokens par rapport à Sonnet 4.5, avec la prise en charge du raisonnement adaptatif et une fenêtre de contexte de 1M au tarif standard.¹⁰⁰ Depuis Opus 4.7 (16 avril 2026), Claude Code utilise Opus par défaut uniquement sur les plans Max et Team Premium ; les comptes Pro, Team Standard, Enterprise et API conservent Sonnet 4.6 par défaut jusqu’à ce qu’Enterprise et API passent à Opus 4.7 le 23 avril 2026.¹⁵⁴ Utilisez Sonnet lorsque vous avez besoin de tokens moins chers, d’une latence plus rapide ou d’une économie de subagents.

Opus : Le niveau phare depuis le 16 avril 2026, et le modèle par défaut sur les plans Max et Team Premium.¹⁵¹¹⁵⁴ Réservez le raisonnement plus coûteux là où il rapporte : décisions architecturales, débogage délicat, compréhension de systèmes complexes, analyse de sécurité, travail agentique à long horizon. Opus 4.7 résout 3× plus de tâches en production sur SWE-Bench qu’Opus 4.6, obtient 70 % sur CursorBench (contre 58 %), et améliore la résolution de 13 % sur un benchmark de codage interne de 93 tâches.¹⁵¹ Claude Code utilise par défaut l’effort xhigh sur Opus 4.7, ajustable via /effort (v2.1.111+).¹⁵³¹⁵⁴ Le mode Auto est disponible pour les abonnés Max sur Opus 4.7 via Anthropic API sans nécessiter --enable-auto-mode ; les autres plans/fournisseurs ont une disponibilité spécifique au plan et contrôlée par l’administrateur.¹⁵³ Contexte de 1M au tarif standard — pas de surcoût pour le contexte long. Changements de comportement à connaître : Opus 4.7 suit les instructions plus littéralement, calibre la longueur de la réponse à la complexité de la tâche, exécute moins de subagents par défaut et adopte un ton plus direct avec moins de formulations validation-forward. Si vos prompts contiennent de l’échafaudage pour forcer des messages de progression intermédiaires ou un comportement de double vérification, essayez de le retirer.¹⁵²

Opusplan : Un mode hybride qui utilise Opus pour la planification (où la qualité du raisonnement compte le plus) et Sonnet pour l’exécution (où la vitesse compte). Excellent pour les refactorisations complexes où vous voulez le meilleur plan mais n’avez pas besoin d’un raisonnement de niveau Opus pour chaque modification individuelle.

Changement de modèle

Pendant une session :

> /model opus
> /model sonnet
> /model haiku

Au démarrage :

claude --model opus

Via l’environnement :

export ANTHROPIC_MODEL=opus

Dans settings.json :

{
  "model": "claude-sonnet-4-5-20250929"
}

Pour les subagents spécifiquement :

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Contexte étendu

Pour les grandes bases de code ou les longues sessions, activez le contexte de 1M tokens :

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 avec contexte de 1M

Ou au sein d’une session :

> /model sonnet[1m]
> /model opus[1m]

Opus 4.7, Opus 4.6 et Sonnet 4.6 incluent tous la fenêtre de contexte complète de 1M tokens au tarif standard — pas de surcoût pour le contexte long.¹⁵⁵ Une requête de 900K tokens est facturée au même tarif par token qu’une requête de 9K tokens. Les remises de mise en cache des prompts et de traitement par lots s’appliquent aux tarifs standard sur l’ensemble de la fenêtre de contexte.

Sur les abonnements Max, Team et Enterprise, Opus avec contexte de 1M est inclus automatiquement — aucun suffixe [1m] nécessaire (activé par défaut depuis la v2.1.75, le 13 mars 2026).¹²⁴¹⁵⁴ Sur Pro, le contexte de 1M est accessible via usage supplémentaire. Les utilisateurs de API et en pay-as-you-go ont un accès complet de 1M aux tarifs standard par token.¹⁵⁴

Pour désactiver les variantes de contexte de 1M dans le sélecteur de modèles, définissez CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Vérification du modèle actuel

> /status

La commande affiche le modèle actuel, les informations du compte, les paramètres appliqués et d’autres états de session.

Étiquettes du sélecteur de modèles (v2.1.51+) : Le sélecteur /model affiche désormais des étiquettes lisibles par l’humain (par exemple, « Sonnet 4.6 ») au lieu des ID bruts du modèle pour les versions épinglées, avec des indications de mise à niveau lorsque des versions plus récentes sont disponibles.¹⁰⁵

Mode rapide (v2.1.36+)

Le mode rapide fournit une sortie significativement plus rapide à partir du même modèle ; il ne bascule pas vers un modèle moins cher. Activez-le pendant une session avec /fast.⁹³

> /fast            # Activer/désactiver le mode rapide

Tarification (mode rapide Opus 4.6) :

Le mode rapide est en aperçu de recherche, uniquement pour Opus 4.6, et offre une sortie environ 2,5× plus rapide à 6× le tarif de base.¹⁵⁶ Activer /fast bascule automatiquement la session vers Opus 4.6 si vous étiez sur un autre modèle ; désactiver /fast vous laisse sur Opus 4.6 jusqu’à ce que vous changiez via /model. Le mode rapide n’est pas disponible sur Opus 4.7, Sonnet, Haiku ou via Bedrock/Vertex/Foundry. Il nécessite un usage supplémentaire à activer et, pour Team/Enterprise, l’activation par l’administrateur.

Quand utiliser le mode rapide : - Itérer rapidement sur de petits changements où la latence est le goulot d’étranglement - Générer des tests, du boilerplate ou du code répétitif où la vitesse compte plus que le coût - Travailler séquentiellement sur une liste de tâches similaires

Quand NE PAS utiliser le mode rapide : - Tâches agentiques de longue durée (le coût s’accumule rapidement à 6× les tarifs) - Travail de subagent en arrière-plan (personne n’attend la sortie) - Sessions soucieuses du budget

Le mode rapide d’Opus 4.6 inclut la fenêtre complète de contexte de 1M (v2.1.50+). La tarification du mode rapide est uniforme sur le contexte de 1M — pas de surcoût supplémentaire pour le contexte long.¹⁰³¹⁵⁶

Astuce d’expert : Le mode rapide ne se combine pas avec opusplan (opusplan mélange déjà Opus et Sonnet ; le mode rapide n’affecte qu’Opus 4.6). Utilisez le mode rapide directement lorsque la latence compte plus que le coût, et désactivez-le pour le travail autonome ou par lots. /fast nécessite un usage supplémentaire ; les administrateurs Team/Enterprise peuvent avoir besoin de l’activer en premier (correction v2.1.37).⁹³¹⁵⁶

Contrôle de l’effort (v2.1.111+, Opus 4.7)

Opus 4.7 introduit un nouveau cadran d’effort qui ajuste le compromis vitesse/intelligence. Utilisez /effort pendant une session :

> /effort              # ouvre un curseur interactif (touches fléchées + Entrée)
> /effort xhigh        # définir directement

Claude Code utilise désormais par défaut l’effort xhigh pour Opus 4.7. xhigh est exclusif à Opus 4.7 — les autres modèles retombent à high. Claude Managed Agents gère l’effort automatiquement ; le paramètre d’effort est un concept de l’API Messages.¹⁵²¹⁵³

Mode Auto sur Max (v2.1.111+)

Le mode Auto — un remplacement plus sûr pour --dangerously-skip-permissions — est disponible pour les abonnés Max sur Opus 4.7 via Anthropic API sans --enable-auto-mode.¹⁵³ Un classifieur Sonnet-4.6 examine chaque action avant son exécution, vérifiant la correspondance d’intention et la sécurité. Note (v2.1.111+) : le drapeau --enable-auto-mode a été supprimé ; démarrez plutôt une session en mode Auto avec --permission-mode auto. Le mode Auto n’est pas disponible sur Pro ; selon la documentation des modes de permission d’Anthropic, il est actuellement réservé à Anthropic-API direct uniquement — Bedrock, Vertex et Foundry ne sont pas encore pris en charge.

Règles personnalisées sans perdre les valeurs par défaut (v2.1.118+). Les versions précédentes rendaient autoMode.allow, autoMode.soft_deny et autoMode.environment exclusifs : définir votre propre liste signifiait perdre les règles de sécurité intégrées. La sentinelle $defaults résout cela — elle s’étend en ligne à la liste intégrée à l’emplacement exact où vous la placez, vous permettant ainsi de superposer des règles personnalisées autour d’elles :¹⁵⁹

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // vos ajouts, préfixés
      "$defaults",                // liste allow intégrée insérée ici
      "Bash(git push:origin/feature/*)"  // ajoutés à la suite
    ]
  }
}

Option « Ne plus demander » (v2.1.118+). L’invite d’opt-in du mode Auto offre désormais une option « Ne plus demander », permettant aux utilisateurs fréquents de supprimer l’explicateur sans avoir à scripter un drapeau.¹⁵⁹

Nouvelles commandes en v2.1.105–v2.1.114¹⁵³¹⁵⁷

Récapitulatif de session (v2.1.108+)

Une nouvelle fonctionnalité au niveau de la session qui fait remonter le contexte lorsque vous revenez à une session en pause. Activée par défaut et désactivable via /config ou CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. Le modèle peut également invoquer des commandes slash intégrées (/init, /review, /security-review) via l’outil Skill — étendant le pattern subagent/skill.¹⁵³

Notifications push (v2.1.110+)

Lorsque Remote Control est configuré avec « Push when Claude decides » activé, Claude peut désormais envoyer des notifications push mobiles à sa propre discrétion via un nouvel outil de notification push. À associer à la surface mobile/web Remote Control existante.¹⁵³ /context, /exit et /reload-plugins fonctionnent désormais également depuis les clients Remote Control.

Outil Windows PowerShell (v2.1.111+, déploiement)

Claude Code déploie un outil natif Windows PowerShell. Sur Linux/macOS, activez-le avec CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (nécessite pwsh dans le PATH). Sur Windows, la même variable contrôle l’opt-in/opt-out pendant le déploiement.¹⁵³

Auto-approbation en mode permission (v2.1.119+). Les commandes de l’outil PowerShell peuvent désormais recevoir une auto-approbation en mode permission de la même manière que les commandes Bash. Les règles d’autorisation comme PowerShell(Get-*:*) et la syntaxe de motif existante contournent désormais l’invite pour les opérations en lecture seule, correspondant à l’ergonomie d’opérateur que les équipes obtiennent déjà sur Linux/macOS.¹⁵⁹

Réduction des permissions : Bash en lecture seule (v2.1.111+)

Les motifs Bash en lecture seule avec arguments glob (par ex. ls *.ts, cat src/*.md) et les commandes commençant par cd <project-dir> && ne déclenchent plus d’invite de permission.¹⁵³ Combiné avec /less-permission-prompts, attendez-vous à beaucoup moins d’interruptions dans les flux de travail quotidiens.

Traçage distribué (v2.1.110+)

SDK et les sessions sans tête lisent désormais TRACEPARENT et TRACESTATE depuis l’environnement, liant les exécutions Claude Code aux traces distribuées. À associer avec OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) pour émettre les corps complets des requêtes/réponses API en tant qu’événements de log OpenTelemetry pour le débogage.¹⁵³

Distribution binaire native (v2.1.113+)¹⁵⁷

v2.1.113 modifie la façon dont CLI se lance : claude invoque désormais un binaire natif Claude Code via une dépendance optionnelle par plateforme au lieu d’exécuter JavaScript groupé. Les commandes d’installation et de mise à jour restent les mêmes, et les équipes n’ont pas besoin de modifier les scripts de déploiement.

Raccourcis de l’éditeur de prompts (v2.1.113+)¹⁵⁷

L’éditeur de prompts gagne une navigation de style readline en saisie multiligne, ainsi qu’un défilement de la fenêtre d’affichage en plein écran :

Ces fonctionnalités sont activées par défaut. Aucune configuration de raccourci clavier requise.

Délai d’expiration de blocage des subagents (v2.1.113+)¹⁵⁷

Les subagents qui bloquent en cours de flux échouent désormais avec une erreur claire après 10 minutes au lieu de rester silencieusement bloqués. À associer avec CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) pour une couverture plus large des processus bloqués sur les APIs en streaming.

Correctif de stabilité v2.1.114¹⁵⁷

v2.1.114 (18 avril 2026) ne livre qu’un seul correctif : la boîte de dialogue de permission pouvait planter lorsqu’un coéquipier agent-teams demandait la permission d’un outil. Effectuez la mise à niveau si vous utilisez Agent Teams.

Combien coûte Claude Code ?

Comprendre et maîtriser les coûts est essentiel pour une utilisation durable de Claude Code. Consultez également Sélection du modèle pour les capacités des modèles et Cadres décisionnels pour choisir le bon modèle selon la tâche.

Consulter les coûts

> /cost

Sortie :

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Les utilisateurs abonnés voient une ventilation par modèle et par cache-hit dans /cost, montrant précisément quels modèles ont consommé des tokens et combien ont été servis depuis le cache (v2.1.92+).¹⁴⁴

Formules d’abonnement

Limites de débit (août 2025) : Anthropic a introduit des limites de débit hebdomadaires pour les abonnés payants. Les abonnés Max peuvent acheter de l’utilisation supplémentaire au-delà de la limite de débit aux tarifs standard API.²¹

Tarification des tokens API (avril 2026)¹¹⁵¹

Pour les utilisateurs facturés à l’API, tarification par million de tokens :

Tarification du contexte 1M (avril 2026) : Opus 4.7, Opus 4.6, Sonnet 4.6 et Mythos Preview incluent tous le 1M aux tarifs par-MTok standard — pas de surcoût long-contexte.¹⁵⁵ Il s’agit d’une consolidation récente ; les anciennes indications selon lesquelles Opus 4.6 ou Sonnet 4.6 payaient 2× en entrée / 1,5× en sortie au-delà de 200K tokens d’entrée ne sont plus d’actualité. Les modèles hérités Opus 4.5 et antérieurs conservent leurs structures tarifaires d’origine.

Tarification de la résidence des données : Spécifier l’inférence uniquement aux États-Unis via inference_geo ajoute un multiplicateur de 1,1× à toute la tarification des tokens, y compris les lectures et écritures du cache (modèles Opus 4.6+).¹⁵⁵

Le prompt caching réduit considérablement les coûts d’entrée répétés : les écritures de cache coûtent 1,25× la base (cache 5 min) ou 2× (cache 1 h), mais les lectures de cache ne coûtent que 0,1×, soit 90 % d’économies. Pour les systèmes RAG et les assistants de code avec contexte répété, le caching peut réduire les coûts de 88 à 95 %.

Batch API offre 50 % de remise avec un délai de 24 heures pour les tâches non urgentes comme les suites de tests nocturnes.

Politique des comptes multiples⁵⁹

Pouvez-vous avoir plusieurs comptes Claude ? Oui, pour des cas d’usage légitimes. Anthropic autorise explicitement les comptes multiples lorsqu’ils servent des objectifs distincts.

Ce qui est autorisé :

Limites techniques : - Jusqu’à 3 comptes peuvent être vérifiés avec le même numéro de téléphone - Plusieurs abonnements payants depuis la même IP/réseau sont explicitement pris en charge - Les comptes sont complètement séparés ; aucun transfert de chat ou de projet entre eux

Ce qui est interdit (selon la Usage Policy) : - Créer des comptes pour contourner des bannissements après avoir été banni - Coordonner des activités malveillantes entre comptes pour échapper à la détection - Utiliser plusieurs comptes pour contourner les limites de débit ou les crédits du palier gratuit

Note concrète : En janvier 2026, l’utilisateur expérimenté Jeffrey Emanuel (@doodlestein) a vu ses 22 comptes Max automatiquement signalés et temporairement bannis. L’employé Anthropic Thariq (@trq212) a résolu la situation en 4 heures après avoir confirmé un usage légitime. Si vous utilisez Claude Code de manière intensive à la fois pour des projets professionnels et personnels sur plusieurs comptes, c’est précisément ce à quoi le service est destiné, mais n’essayez pas de détourner le système.

En cas de doute : Contactez le support Anthropic pour confirmer votre configuration spécifique par écrit.

Facteurs de coût

Exemples concrets de coûts

Astuce d’économie : Utiliser Haiku pour les subagents d’exploration et Sonnet pour l’implémentation réduit généralement les coûts de 40 à 50 % par rapport à une utilisation exclusive de Sonnet.

Gestion des coûts en équipe

TPM/RPM recommandés selon la taille de l’équipe :

Frais d’outils cachés

Au-delà de la tarification au token, certains outils entraînent des frais distincts :¹⁶

Ces frais s’accumulent dans les boucles d’agent. Un cycle de débogage de 100 itérations avec Bash coûte environ 24 500 tokens d’entrée supplémentaires rien qu’en surcoût.

Stratégies d’économie

1. Utilisez Haiku pour les subagents : la plupart des explorations n’ont pas besoin de Sonnet
2. Activez le prompt caching : par défaut, mais vérifiez qu’il n’est pas désactivé
3. Définissez un nombre maximal de tours : claude --max-turns 5 empêche les conversations incontrôlées
4. Utilisez le mode plan pour l’exploration : aucune exécution = aucune opération coûteuse accidentelle
5. Compactez de manière proactive : contexte plus petit = moins de tokens
6. Limitez la sortie : export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Batch API pour les tâches non urgentes : 50 % de remise sur les tokens d’entrée et de sortie

Suivi de l’utilisation

• Console Claude : platform.claude.com (nécessite le rôle Admin ou Billing)
• Limites de workspace : définissez des limites de dépenses par workspace
• Bedrock/Vertex : utilisez le suivi natif des coûts cloud
• LiteLLM : pour un suivi détaillé par utilisateur avec des fournisseurs tiers

Utilisation des tokens en arrière-plan

Certaines opérations consomment des tokens en arrière-plan : - Résumé de conversation pour /resume - Commandes /cost et /status - Compactage automatique

Généralement sous 0,04 $ par session.

Claude Code Analytics API (Team/Enterprise)⁵³

Accédez par programmation aux analyses d’utilisation et aux métriques de productivité Claude Code de votre organisation via l’Admin API.

Endpoint : GET /v1/organizations/usage_report/claude_code

Prérequis : - Clé Admin API (sk-ant-admin...) - Formule Team ou Enterprise - Rôle Admin, Billing ou Developer

Métriques disponibles :

Exemple de requête :

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Cas d’usage : - Analyse de la productivité des développeurs (sessions, commits, PR) - Métriques d’utilisation des outils (taux d’acceptation/rejet pour Edit, Write, etc.) - Suivi et répartition des coûts entre équipes - Justification du ROI pour les outils de codage IA

Note : Les données apparaissent dans l’heure qui suit la fin de l’activité. Seules les données plus anciennes qu’une heure sont incluses dans les réponses pour garantir la cohérence.

Cadres de décision

Savoir que des fonctionnalités existent ne suffit pas. Vous devez savoir quand utiliser chacune d’elles. Ces arbres de décision transforment la connaissance en action.

Quel modèle dois-je utiliser ?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 4.7 (xhigh effort default)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

Règle générale : Opus 4.7 est le modèle par défaut pour Max et Team Premium. Sur Pro/Team Standard/Enterprise/API, Sonnet 4.6 est le modèle par défaut (Enterprise + Anthropic API basculent vers Opus 4.7 le 23 avril 2026).¹⁵⁴ Passez à Haiku pour les subagents. Passez à Opus lorsque la réponse de Sonnet vous semble superficielle. Avec les équipes d’agents (v2.1.32+), Opus peut coordonner plusieurs agents travaillant en parallèle sur différentes sous-tâches.⁸⁶

Commande, Skill, Subagent ou Équipe d’agents ?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook ou Prompt ?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

Quand utiliser le raisonnement étendu ?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

Basculez avec Alt+T pendant la session. Des budgets de raisonnement plus élevés coûtent plus cher ; commencez par le minimum et n’augmentez que si les réponses semblent précipitées.

Raisonnement adaptatif d’Opus 4.6 : Opus 4.6 ajuste automatiquement la profondeur de raisonnement selon la complexité du problème. Pour la plupart des tâches, le contrôle explicite du budget de raisonnement n’est pas nécessaire — Opus monte en puissance pour les problèmes difficiles et reste rapide pour les simples. Le basculement manuel du raisonnement est surtout utile avec Sonnet lorsque vous voulez forcer une analyse plus approfondie.

Quelle surface d’exécution ?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Équipes d’agents, Subagents ou Sessions parallèles

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

Quel type de hook ?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

Quand utiliser /fast ?

Is response speed more important than depth right now?
│
├── YES → Use /fast
│         Same Opus 4.6 model, faster output
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast active le mode rapide pour la session en cours. Il utilise le même modèle (Opus 4.6) avec une vitesse de sortie optimisée — il ne bascule PAS vers un modèle moins cher.

Comment fonctionne le système de permissions ?

Le système de permissions de Claude Code offre un contrôle granulaire sur les opérations pouvant être exécutées. Le comprendre est essentiel tant pour la sécurité que pour l’efficacité du flux de travail. Consultez également Enterprise Deployment pour les paramètres gérés qui appliquent les permissions à l’échelle de l’organisation.

Niveaux de permissions

Outils en lecture seule (auto-approuvés) : - Read - Lire le contenu d’un fichier - Glob - Trouver des fichiers par motif - Grep - Rechercher dans le contenu des fichiers - WebSearch - Effectuer des recherches sur le web - LSP - Intelligence du code (aller à la définition, trouver les références, documentation au survol)²⁵

Capacités de l’outil LSP (v2.0.74+) : L’outil LSP fournit une intelligence du code semblable à celle d’un IDE : - Aller à la définition : Sauter à l’endroit où un symbole est défini - Trouver les références : Lister toutes les utilisations d’un symbole dans la base de code - Documentation au survol : Obtenir des informations de type et de la documentation pour n’importe quel symbole - Fonctionne avec TypeScript, Python, Go, Rust et d’autres langages prenant en charge LSP - Nécessite qu’un serveur de langage soit disponible (généralement installé avec votre chaîne d’outils)

Outils de modification (nécessitent une approbation) : - Edit - Modifier des fichiers existants - Write - Créer de nouveaux fichiers - Bash - Exécuter des commandes shell - WebFetch - Récupérer le contenu d’une URL - NotebookEdit - Modifier des notebooks Jupyter

La première fois qu’un outil de modification s’exécute, Claude Code demande une approbation. Les approbations persistent pour la session sauf si configuré explicitement autrement.

Modes de permissions

Auto Mode (v2.1.85+) : Un remplacement plus sûr pour --dangerously-skip-permissions. Un modèle classificateur séparé (Sonnet 4.6) examine chaque action avant l’exécution, vérifiant qu’elle correspond à l’intention de l’utilisateur et qu’elle est sûre.¹³¹

Comment cela fonctionne : - Les actions en lecture seule et les modifications de fichiers dans le répertoire de travail sont auto-approuvées - Les règles personnalisées allow/deny sont résolues en premier - Tout le reste est soumis au classificateur pour évaluation - Si bloqué, Claude tente automatiquement une approche alternative

Bloqués automatiquement par défaut : curl | bash, force-push vers main, déploiements/migrations en production, suppressions massives dans le cloud, modifications IAM/permissions, envoi de données sensibles à l’extérieur.¹³²

Disjoncteur : 3 blocages consécutifs ou 20 au total dans une session font basculer en mode invite manuelle.¹³²

# Enable at startup
claude --enable-auto-mode

# Or cycle into it during a session
Shift+Tab  # Cycles through: default → acceptEdits → auto → plan

Disponibilité : Utilisateurs du plan Team en premier, suivis par Enterprise et API. Nécessite Sonnet 4.6 ou Opus 4.6.¹³¹

YOLO Mode (v2.0.68+) : Pour un fonctionnement entièrement autonome sans aucun classificateur de sécurité, utilisez le drapeau --dangerously-skip-permissions. Le drapeau dit oui à tout : modifications de fichiers, commandes bash, tous les appels d’outils. Le mot « dangerous » est intentionnel. Auto Mode est l’alternative recommandée pour la plupart des cas d’usage.⁶¹

claude --dangerously-skip-permissions

Définir le mode via CLI :

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

Basculer pendant la session :

Shift+Tab  # Cycles through modes

Dans settings.json :

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Syntaxe des règles de permissions

Des règles granulaires contrôlent des opérations spécifiques. Les règles sont évaluées dans l’ordre : la première correspondance l’emporte.

Motifs de commandes Bash :

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

L’astérisque permet la correspondance de préfixe : Bash(npm run test:*) autorise npm run test, npm run test:unit et npm run test:integration.

Limitation importante : Les motifs Bash ne correspondent qu’à des préfixes, pas à des regex. Un motif tel que Bash(curl http:*) ne correspondra pas à curl -X GET http://... car les options viennent avant l’URL. Pour un blocage fiable, refusez la commande entièrement : Bash(curl:*).

Motifs d’opérations sur fichiers :

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Syntaxe des chemins : - Chemins relatifs : Edit(src/**) - relatifs au répertoire de travail - Absolus depuis le fichier de paramètres : Edit(/build/**) - relatifs à l’emplacement du fichier de paramètres - Véritablement absolus : Edit(//tmp/**) - commencent par // - Répertoire personnel : Read(~/.zshrc)

Motifs d’outils MCP :

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Utilisez la syntaxe avec joker mcp__server__* pour autoriser ou refuser tous les outils d’un serveur MCP spécifique.³⁹ La syntaxe avec joker est utile pour activer rapidement tous les outils de serveurs de confiance ou bloquer des serveurs entiers provenant de sources non fiables.

Motifs WebFetch :

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Répertoires supplémentaires

Étendez l’accès de Claude au-delà du projet actuel :

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Les répertoires supplémentaires sont essentiels pour les monorepos ou lorsque Claude doit référencer du code dans des répertoires frères.

Mode Sandbox

Activer l’isolation du système de fichiers et du réseau :

> /sandbox

Ou configurez dans les paramètres :

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

En mode sandbox : - Accès au système de fichiers restreint au répertoire du projet - Accès au réseau contrôlé - Certaines commandes exclues des restrictions du sandbox - Commandes Bash auto-autorisées si autoAllowBashIfSandboxed est à true

Astuce d’expert : Le mode sandbox est excellent pour exécuter Claude sur des bases de code non fiables. Activez-le lorsque vous explorez des projets inconnus ou quand vous voulez une couche de protection supplémentaire. Les tests internes d’Anthropic ont constaté que le sandbox réduit les invites de permission de 84 %.⁴⁵ Le sandbox utilise des primitives au niveau du système d’exploitation (seatbelt sur macOS, bubblewrap sous Linux) pour l’isolation du système de fichiers et du réseau, de sorte que même une injection de prompt réussie est entièrement contenue. Anthropic a publié en open source le runtime du sandbox pour les équipes qui construisent leurs propres agents.⁸⁹

Notes de sécurité (v2.1.34+) : Les commandes exclues du sandboxing via sandbox.excludedCommands ou dangerouslyDisableSandbox pouvaient auparavant contourner la règle de demande de permission Bash lorsque autoAllowBashIfSandboxed était activé ; cela a été corrigé dans v2.1.34.⁹⁴ Depuis v2.1.38, les écritures dans .claude/skills sont bloquées en mode sandbox, empêchant l’injection de prompt de modifier les définitions de skills.⁹⁵ v2.1.77 ajoute un paramètre de système de fichiers sandbox allowRead pour ré-autoriser l’accès en lecture dans les régions denyRead — utile lorsque vous voulez bloquer la majeure partie d’une arborescence de répertoires mais autoriser des sous-répertoires spécifiques.¹²⁶

Exemption de configuration d’agent .claude/ (v2.1.121+) : --dangerously-skip-permissions n’invite plus pour les écritures dans .claude/skills/, .claude/agents/ et .claude/commands/.¹⁶¹

Renforcement de la sécurité dans v2.1.113 :¹⁵⁷

• sandbox.network.deniedDomains bloque des hôtes spécifiques même lorsqu’un joker allowedDomains plus large les autoriserait par ailleurs. Utilisez la liste de blocage pour couper les pastebins, dépôts de fichiers ou hôtes connus comme malveillants sans réécrire toute votre politique d’autorisation.
• Règles de refus pour les commandes wrapper. Les règles de refus Bash correspondent désormais aux commandes encapsulées dans env, sudo, watch, ionice, setsid et autres wrappers d’exécution similaires. Des règles comme Bash(rm:*) attrapent désormais env rm -rf, sudo rm -rf et les motifs de contournement frères.
• Les règles d’autorisation Bash(find:*) n’auto-approuvent plus find -exec ou find -delete. Ces drapeaux exécutent des commandes et suppriment des fichiers, donc Claude Code les fait passer par le chemin de permission normal.
• Protection contre les suppressions sur macOS. Les règles d’autorisation Bash(rm:*) traitent désormais /private/etc, /private/var, /private/tmp et /private/home comme des cibles de suppression dangereuses. /var, /etc et /tmp sont des liens symboliques vers /private/, donc la forme de règle précédente manquait les cibles canoniques.

Comment fonctionnent les hooks ?

Les hooks exécutent des commandes shell déterministes à des points précis du flux de travail de Claude Code. Contrairement à demander à Claude d’effectuer des actions, les hooks garantissent l’exécution indépendamment du comportement du modèle. Ils sont essentiels pour faire respecter les standards d’équipe et automatiser les tâches répétitives. Consultez Decision Frameworks pour l’arbre de décision « Quel type de hook ? » couvrant les hooks de commande, de prompt et d’agent.

Pourquoi les hooks plutôt que les prompts : dire à Claude « exécutez toujours Prettier après avoir édité des fichiers » fonctionne parfois. Mais Claude peut oublier, privilégier la rapidité ou décider que la modification est « trop petite ». Les hooks garantissent l’exécution : chaque Edit ou Write déclenche votre formateur, à chaque fois, sans exception. Pour la conformité, la sécurité et les standards d’équipe, le déterministe l’emporte sur le probabiliste.⁷

Événements disponibles

Configuration des hooks

Définissez les hooks dans settings.json ou un hooks.json dédié :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

Le champ matcher détermine quels outils déclenchent un hook :

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Protocole d’entrée/sortie des hooks

Les hooks reçoivent du JSON sur stdin :

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Enrichissement des événements de hook (v2.1.69+) : tous les événements de hook incluent désormais les champs agent_id et agent_type lorsqu’ils sont déclenchés depuis un subagent ou une session --agent, ainsi qu’un champ worktree dans les commandes de hook de la barre d’état.¹¹⁷

Les hooks Stop/SubagentStop (v2.1.47+) reçoivent un champ supplémentaire last_assistant_message contenant le texte de la réponse finale de Claude, afin que les hooks puissent inspecter la sortie sans analyser les fichiers de transcription :

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

Les codes de sortie contrôlent le comportement : - 0 : succès : l’opération se poursuit. La sortie standard est affichée en mode verbeux (Ctrl+O). Pour UserPromptSubmit et SessionStart, la sortie standard est ajoutée au contexte. - 2 : erreur bloquante : l’opération s’arrête. La sortie d’erreur devient le message d’erreur renvoyé à Claude. - 1, 3, etc. : erreur non bloquante : l’opération continue. La sortie d’erreur est affichée comme avertissement en mode verbeux.

Pour un contrôle avancé, les hooks peuvent produire du JSON :

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

Contrôle de décision PreToolUse (format préféré) : les hooks PreToolUse utilisent hookSpecificOutput pour un contrôle plus riche : trois résultats (allow/deny/ask) ainsi que la possibilité de modifier l’entrée de l’outil et d’injecter du contexte :⁹⁶

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Note : les champs decision et reason de niveau supérieur sont obsolètes pour PreToolUse. Utilisez plutôt hookSpecificOutput.permissionDecision et hookSpecificOutput.permissionDecisionReason. Les autres événements (PostToolUse, Stop, etc.) utilisent toujours decision au niveau supérieur.⁹⁶

Titre de session UserPromptSubmit (v2.1.94+) : les hooks UserPromptSubmit peuvent définir le titre de la session via hookSpecificOutput.sessionTitle.¹⁴⁷

Hooks asynchrones (janvier 2026)

Les hooks peuvent désormais s’exécuter en arrière-plan sans bloquer l’exécution de Claude Code. Ajoutez async: true à la configuration de votre hook :⁸⁸

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Quand utiliser des hooks asynchrones : - Notifications (Slack, e-mail, Pushover) qui ne devraient pas ralentir la session - Journalisation et télémétrie qui peuvent s’exécuter en arrière-plan - Post-traitement non critique (analytique, sauvegardes)

Quand NE PAS utiliser des hooks asynchrones : - Formatage (doit se terminer avant la prochaine édition) - Validation (doit bloquer en cas d’échec) - Tout hook qui doit modifier l’entrée/sortie de l’outil

Hooks basés sur prompt et sur agent (v2.1.32+)

Au-delà des hooks de commande shell (type: "command"), Claude Code prend en charge deux types de hooks alimentés par LLM qui évaluent les conditions à l’aide du raisonnement IA plutôt que de scripts.⁹⁶

Les hooks prompt (type: "prompt") envoient un prompt à un seul tour à un modèle Claude rapide. Le modèle retourne { "ok": true } pour autoriser ou { "ok": false, "reason": "..." } pour bloquer :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Les hooks HTTP (type: "http") envoient l’entrée JSON de l’événement comme requête POST à une URL et reçoivent du JSON en retour. Utilisez-les pour les webhooks, les services de notification externes ou la validation basée sur API (v2.1.63+) :¹¹¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Les hooks HTTP utilisent le même format de décision que les hooks de commande (retourner du JSON avec decision et reason). Ils sont routés via le proxy réseau de la sandbox lorsque le sandboxing est activé. Non pris en charge pour les événements SessionStart/Setup.

Les hooks d’agent (type: "agent") lancent un subagent avec accès aux outils (Read, Grep, Glob) pour une vérification multi-tours. Utilisez-les lorsque la vérification nécessite l’inspection de fichiers réels ou de la sortie des tests :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Utilisez $ARGUMENTS comme placeholder pour l’entrée JSON du hook. Les deux types prennent en charge les champs model (par défaut le modèle rapide) et timeout. Événements pris en charge : PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle ne prend pas en charge les hooks prompt/agent.

Hooks d’outil MCP (v2.1.118+)

Les hooks peuvent désormais invoquer un outil MCP directement via type: "mcp_tool", évitant le besoin d’envelopper un sous-processus Bash qui appelle le serveur.¹⁵⁹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

Cela s’associe bien avec les serveurs MCP que les utilisateurs ont déjà configurés : tout outil accessible depuis /mcp devient appelable par hook.

duration_ms dans les hooks PostToolUse (v2.1.119+)

Les entrées de hook PostToolUse et PostToolUseFailure incluent désormais duration_ms, le temps d’exécution de l’outil hors prompts de permission et hooks PreToolUse.¹⁵⁹ Utile pour la détection d’outils lents, les journaux d’audit et les métriques de latence par outil :

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

updatedToolOutput pour tous les outils (v2.1.121+)

Dans la v2.1.118, les hooks d’outil MCP ont gagné la possibilité de remplacer la sortie de l’outil via hookSpecificOutput.updatedToolOutput. Depuis la v2.1.121, ce même champ fonctionne pour tout hook PostToolUse — outils intégrés (Bash, Read, Edit, Glob, Grep, etc.), outils de subagent et outils MCP. Cas d’usage : censurer le contenu sensible de la sortie de tout outil, normaliser la structure pour les consommateurs en aval, injecter des métadonnées avant que l’agent ne lise le résultat.¹⁶¹

Variables d’environnement des hooks

Les hooks ont accès à des variables d’environnement pour résoudre les chemins :⁹⁶

Persister des variables d’environnement depuis SessionStart :

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Sécurité des hooks HTTP (v2.1.51+) : les hooks HTTP qui interpolent des variables d’environnement dans les en-têtes nécessitent désormais une liste explicite allowedEnvVars. Cela empêche l’exfiltration arbitraire de variables d’environnement via les valeurs d’en-tête. Les hooks HTTP sont également routés via le proxy réseau de la sandbox lorsque le sandboxing est activé, ce qui applique la liste blanche de domaines. Les hooks HTTP ne sont pas pris en charge pour les événements SessionStart/Setup.¹⁰⁵

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Confiance de l’espace de travail des hooks (v2.1.51+) : les commandes de hook statusLine et fileSuggestion exigent désormais l’acceptation de la confiance de l’espace de travail avant de s’exécuter en mode interactif, fermant ainsi un vecteur de sécurité potentiel.¹⁰⁵

Exemples pratiques de hooks

Formater automatiquement les fichiers TypeScript après édition :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Journaliser toutes les commandes bash :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

Bloquer l’accès aux fichiers sensibles :

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

Exécuter les tests après les modifications de code :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Système de notification personnalisé :

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Injecter du contexte dynamique dans les prompts :

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Débogage des hooks

Activez le mode debug pour résoudre les problèmes des hooks :

claude --debug

Le mode debug enregistre : - Les temps d’exécution des hooks - Les données d’entrée/sortie - Les messages d’erreur et les traces de pile - Les résultats de décision (allow/reject/ask)

Affichage de la source du hook (v2.1.75+) : lorsqu’un hook nécessite une confirmation utilisateur, l’invite de permission affiche désormais la source du hook (paramètres, plugin ou skill), ce qui facilite l’identification du composant qui demande l’accès.¹²⁴

Hooks à portée de composant (v2.1.0+)

Les hooks peuvent être définis directement dans les Skills, subagents et commandes slash via le frontmatter. Ces hooks sont limités au cycle de vie du composant et ne s’exécutent que lorsque ce composant est actif.⁴¹

Skill avec hooks intégrés :

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

Événements pris en charge : PreToolUse, PostToolUse, Stop

L’option once (skills et commandes slash uniquement) garantit que le hook ne s’exécute qu’une seule fois par session, ce qui est utile pour les tâches de nettoyage ou de finalisation.

Stratégie pour les sessions longues

Pour les sessions Claude Code nocturnes ou sans surveillance, configurez les hooks pour maintenir Claude sur la bonne voie sans intervention manuelle. L’idée clé : utiliser les hooks de linting et de test comme garde-fous qui forcent Claude à corriger les problèmes avant de continuer.⁶⁴

Le pattern « Don’t Stop Until Tests Pass » :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

Stratégie pour les sessions nocturnes :

1. Vérification préalable : utilisez un hook Setup pour vérifier que l’environnement est prêt
2. Validation continue : les hooks PostToolUse exécutent les tests après chaque modification
3. Porte de complétion : les hooks Stop vérifient tous les critères d’acceptation avant que Claude ne déclare « terminé »
4. Notification : les hooks Stop peuvent vous notifier via Slack/Pushover quand Claude termine ou se bloque

Combinez avec --dangerously-skip-permissions dans un conteneur sandboxé pour des exécutions nocturnes entièrement autonomes. Claude continuera d’itérer jusqu’à ce que les tests passent ou qu’il ait épuisé ses options.

Qu’est-ce que MCP (Model Context Protocol) ?

MCP étend Claude Code avec un accès à des outils externes, des bases de données, des APIs et des services via un protocole standardisé. L’écosystème a explosé : MCP compte désormais 100 millions de téléchargements mensuels et plus de 3 000 serveurs indexés sur MCP.so (janvier 2026), consolidant sa position en tant que standard du secteur pour connecter l’IA aux outils et aux données.³⁵⁴ Comprendre MCP est essentiel pour intégrer Claude dans votre chaîne d’outils existante.

Pourquoi MCP est important pour les développeurs : Sans MCP, Claude Code ne peut que lire des fichiers et exécuter des commandes bash. Avec MCP, Claude peut interroger votre base de données de production, créer des tickets Jira, examiner des PR GitHub, vérifier les erreurs Sentry et interagir avec n’importe quel API utilisé par votre équipe, le tout à partir de requêtes en langage naturel. Le protocole standardise la manière dont les outils d’IA se connectent aux services externes, évitant ainsi le verrouillage par fournisseur. Consultez Decision Frameworks pour des conseils sur le choix entre MCP et d’autres mécanismes d’extension.

Prise en charge des serveurs MCP distants (juin 2025)

Claude Code prend désormais en charge les serveurs MCP distants avec une authentification OAuth native.²⁸ Connectez-vous à des outils et des sources de données sans gérer de serveurs locaux. Authentifiez-vous une seule fois et Claude Code gère automatiquement le rafraîchissement des jetons.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

SDK mcp_authenticate redirectUri (v2.1.121+) : Le mcp_authenticate de l’Agent SDK accepte un paramètre redirectUri pour finaliser OAuth sur des schémas d’URI personnalisés — requis pour les applications de bureau et les flux de connecteurs claude.ai qui ne peuvent pas utiliser la redirection en boucle locale par défaut.¹⁶¹

Connecteurs MCP claude.ai (v2.1.46+)

Claude Code peut désormais utiliser les connecteurs MCP configurés dans votre compte claude.ai. Cela comble le fossé entre le web et CLI : les serveurs MCP que vous avez configurés via l’interface claude.ai sont automatiquement disponibles dans Claude Code sans avoir à les reconfigurer localement.¹⁰²

Désactivation : Définissez ENABLE_CLAUDEAI_MCP_SERVERS=false dans votre environnement ou dans le bloc env de settings.json pour empêcher le chargement des serveurs MCP claude.ai.¹¹¹

Recherche d’outils MCP (v2.1.7+)

À mesure que les serveurs MCP ont gagné en capacités (certains exposant plus de 50 outils), les descriptions d’outils ont commencé à consommer un contexte excessif. La Recherche d’outils MCP résout ce problème en chargeant dynamiquement les descriptions d’outils uniquement lorsque cela est nécessaire, une forme de chargement paresseux pour les outils d’IA.⁵⁴

Impact sur les performances : Les benchmarks internes montrent des améliorations spectaculaires en matière de précision : - Opus 4 : 49 % → 74 % sur les évaluations MCP - Opus 4.5 : 79,5 % → 88,1 % sur les évaluations MCP - Réduction de la surcharge de jetons : 85 %

Comment cela fonctionne : Lorsque les descriptions d’outils MCP dépassent 10 % de la fenêtre de contexte (seuil par défaut), Claude Code diffère le chargement des descriptions complètes jusqu’à ce qu’elles soient réellement nécessaires. Claude voit les noms des outils mais récupère les descriptions à la demande.

Configuration :

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

Valeurs : - true - Toujours activer la recherche d’outils - false - Toujours désactiver (charger toutes les descriptions d’outils dès le départ) - auto:N - Activer lorsque les outils dépassent N % du contexte (0-100)

Conseil d’expert : Avec la Recherche d’outils activée, vous pouvez vous connecter à beaucoup plus de serveurs MCP sans vous soucier des limites de contexte. La réduction de 95 % du contexte signifie que les serveurs qui se disputaient auparavant le contexte coexistent désormais paisiblement.

Surcharge de chargement permanent MCP (v2.1.121+)

La Recherche d’outils diffère le chargement des descriptions complètes jusqu’à ce qu’un outil soit nécessaire (seuil : mcpToolSearchAutoEnable, par défaut auto:10). Pour les serveurs de confiance dont vous prévoyez d’utiliser les outils à chaque tour, désactivez cette option par serveur avec alwaysLoad: true — chaque outil de ce serveur est chargé dans le prompt au démarrage de la session, sans aller-retour ToolSearch :¹⁶¹

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

Nouvelle tentative automatique au démarrage MCP (v2.1.121+) : Un serveur qui rencontre une erreur lors du démarrage est désormais réessayé jusqu’à 3 fois avant d’être marqué comme déconnecté — utile pour les serveurs stdio qui font la course avec un processus parent lent ou les serveurs HTTP derrière un backend à démarrage à froid.¹⁶¹

Élicitation MCP (v2.1.76+)

Les serveurs MCP peuvent désormais demander une saisie structurée à l’utilisateur en cours de tâche via des dialogues interactifs.¹²⁵ Lorsqu’un serveur MCP a besoin d’informations supplémentaires (par exemple, sélectionner une branche, saisir un nom de projet, confirmer une action), il envoie une demande d’élicitation que Claude Code rend sous forme de champs de formulaire ou d’URL de navigateur.

Intégration des hooks : Deux nouveaux événements de hook — Elicitation (avant l’apparition du dialogue) et ElicitationResult (après la réponse de l’utilisateur) — vous permettent d’intercepter, de valider ou de remplacer les réponses d’élicitation de manière programmatique. Cela permet des flux de travail d’entreprise où les invites du serveur MCP sont pré-remplies ou contraintes par une politique.

Surcharge de la taille des résultats MCP (v2.1.91+)

Les résultats des outils MCP sont tronqués par défaut. Les serveurs peuvent remplacer ce comportement par résultat en utilisant l’annotation _meta["anthropic/maxResultSizeChars"], autorisant jusqu’à 500 000 caractères.¹⁴³ Ceci est utile pour renvoyer des charges utiles volumineuses telles que des schémas de bases de données, des réponses API ou des contenus de fichiers sans troncature.

Assistant interactif de configuration MCP

Exécutez claude mcp add sans arguments pour lancer une interface étape par étape pour ajouter des serveurs MCP. L’assistant vous guide à travers la sélection du type de transport, l’authentification et la configuration.¹⁵

Types de transport

HTTP (recommandé pour les serveurs distants) :

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (déprécié mais fonctionnel) :

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (serveurs locaux) :

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows nécessite un wrapper cmd pour stdio :

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Gestion des portées

Les serveurs MCP existent à trois portées avec une précédence claire (local prime sur projet, qui prime sur utilisateur) :

Spécifiez la portée lors de l’installation :

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Format du fichier de configuration

Le fichier .mcp.json définit les serveurs au niveau du projet :

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

Les variables d’environnement sont développées en utilisant la syntaxe ${VAR} avec des valeurs par défaut optionnelles : ${VAR:-default}.

Commandes de gestion MCP

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

Authentification OAuth

Pour les serveurs nécessitant OAuth :

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Utilisation des ressources et invites MCP

Ressources de référence :

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

Invites MCP en tant que commandes slash :

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Limites de sortie

Claude Code limite la sortie MCP pour éviter le débordement de contexte : - Seuil d’avertissement : 10 000 jetons - Maximum par défaut : 25 000 jetons

Augmentez si nécessaire :

export MAX_MCP_OUTPUT_TOKENS=50000

Serveurs MCP populaires

Modèles MCP pratiques

Flux de travail GitHub :

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Requêtes de base de données :

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Surveillance des erreurs :

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

Configuration MCP d’entreprise

Les administrateurs système peuvent appliquer des politiques MCP via managed-mcp.json :