Dissection complète du fonctionnement interne de Claude Code — de la boucle agentique au chargement du contexte

Voici l’essentiel sur le fonctionnement de Claude Code dans le terminal, à partir de la documentation officielle (réorganisée sur Mintlify par VineeTagarwaL).

Comment fonctionne Claude Code ?
En une phrase, c’est une boucle qui « lit → réfléchit → utilise des outils → observe le résultat → recommence ».
Les 6 étapes de la boucle agentique

1. L’utilisateur saisit un message dans le terminal (ou le transmet via --print / stdin)
2. Assemblage du prompt système — date actuelle, état git, fichier CLAUDE.md, liste des outils disponibles
3. Appel à l’API Anthropic → le modèle génère un bloc tool_use (nom de l’outil + entrée JSON)
4. Vérification des permissions — décision entre approbation automatique / demande de confirmation / blocage
5. Exécution de l’outil → le résultat (contenu de fichier, sortie de commande, etc.) est ajouté à la conversation en tant que tool_result
6. Le modèle, après avoir reçu le résultat, effectue un appel d’outil supplémentaire ou produit une réponse finale — la boucle se répète jusqu’à ce qu’il n’y ait plus d’appel d’outil
   La boucle ne s’exécute que dans le processus terminal local. Sauf pour les outils qui appellent explicitement l’extérieur, comme WebFetch, WebSearch ou un serveur MCP, les fichiers, le shell et les informations d’authentification ne quittent pas la machine.

Comment le contexte est-il construit ?
Au démarrage de la conversation, deux blocs sont assemblés et préfixés à tous les appels API.

• Contexte système — branche actuelle, 5 derniers commits, résultat de git status --short (tronqué au-delà de 2 000 caractères)
• Contexte utilisateur — fichier mémoire CLAUDE.md (exploration hiérarchique en 4 étapes), date du jour (Today's date is YYYY-MM-DD)
  Les deux blocs sont mis en cache à l’échelle de la conversation via lodash/memoize. Lors d’un appel à setSystemPromptInjection(), le cache est immédiatement réinitialisé.

Modèle de permissions — quand les outils sont-ils exécutés ?

Résultat	Comportement
allow	Exécution immédiate, résultat ajouté à la conversation
ask	Pause → affichage d’une boîte de dialogue de confirmation
deny	Refus → retour d’une erreur au modèle

• Mode bypassPermissions : toutes les vérifications sont ignorées
• Mode acceptEdits : les modifications de fichiers sont approuvées automatiquement, mais bash demande toujours confirmation
• Les outils en lecture seule comme Read, Glob et Grep sont approuvés automatiquement par défaut dans tous les modes

Sous-agents (outil Task)
Claude peut lancer des sous-agents avec l’outil Task (AgentTool). Les sous-agents exécutent leur propre boucle agentique dans une conversation isolée, avec éventuellement un ensemble d’outils restreint, puis renvoient leur résultat à l’agent parent une fois le travail terminé. Ils peuvent s’exécuter en local (in-process) ou sur un calcul distant.

Sauvegarde et restauration des conversations
Les conversations sont enregistrées sous forme de fichiers de transcription JSON dans ~/.claude/.

• --resume <session-id> ou --resume seul permet de reprendre une conversation précédente
• Lors de la reprise : chargement de tout l’historique des messages, nouvelle exploration des fichiers CLAUDE.md, réinitialisation du mode de permissions selon les valeurs par défaut de la configuration
• Les longues conversations sont compactées périodiquement — les anciens messages sont résumés pour gérer la fenêtre de contexte. La transcription source complète reste conservée sur le disque

Ce que fait le moteur de requête
Chaque « tour » est piloté par query.ts.

• Affichage en temps réel du streaming de tokens dans le terminal
• Distribution des blocs tool_use vers les handlers appropriés
• Gestion du budget de tokens et d’appels d’outils par tour
• Déclenchement de la compaction lorsque la fenêtre de contexte est pleine
• Chaque outil possède une propriété maxResultSizeChars — si le résultat dépasse cette limite, il est enregistré dans un fichier temporaire et seul le chemin du fichier est transmis au modèle (pour éviter un débordement de la fenêtre de contexte)

Original : How Claude Code works — Mintlify
Référence : il s’agit d’un document miroir non officiel dans lequel VineeTagarwaL a réorganisé la documentation officielle de Claude Code sur Mintlify.