Une session Claude Code d'une heure sur un repo moyen peut coûter de quelques dollars à plusieurs dizaines de dollars selon le modèle et la structure de tes prompts. Le prompt caching à 10 % du tarif input explique une grande partie de l'écart. Le choix Sonnet contre Opus explique l'autre moitié. Le reste vient de sous-agents lancés sans budget et de CLAUDE.md de 800 lignes qu'on relit à chaque tour.
Cet article te donne la lecture directe des commandes, réglages et endroits à surveiller pour reprendre la main sur ta facture. On suppose que tu as déjà installé Claude Code et fait tourner quelques sessions. Si ce n'est pas le cas, va d'abord voir le guide complet Claude 2026 pour caler ton environnement avant de te battre avec les coûts.
Pourquoi le coût de Claude Code surprend les dirigeants
Un chat classique dans Claude.ai coûte zéro à l'usage, l'abonnement Pro à 20 € par mois plafonne tout. Claude Code passe par l'API, facturée au token, et le compteur tourne dès qu'un fichier est lu. Une session agentique typique fait trois choses coûteuses en parallèle : elle relit ton repo pour cadrer le contexte, elle réinjecte ce contexte à chaque tour de conversation, et elle lance des sous-tâches qui répliquent tout ou partie de ce contexte.
Les tarifs API à connaître pour cet article, en dollars par million de tokens : Sonnet 5 est à 2 $ en entrée et 10 $ en sortie (tarif standard confirmé permanent depuis l'annonce Anthropic du 10 août 2026, la hausse à 3 $ / 15 $ n'aura pas lieu, voir l'annonce du prix définitif). Opus 5 est à 5 $ en entrée et 25 $ en sortie. Fable 5 grimpe à 10 $ / 50 $. Au-dessus s'ajoutent deux mécaniques qui pèsent lourd sur la facture réelle : les écritures de cache 5 minutes sont facturées 1,25x le tarif input standard, et les lectures de cache sont facturées 10 % du tarif input. Ce dernier chiffre est le levier central : bien câblé, il divise la facture d'un facteur trois à dix sur une longue session.
Dernier réflexe utile : passe l'API de comptage de tokens d'Anthropic sur tes propres prompts pour connaître ton volume réel, plutôt que de te fier à une règle générique.
La commande /cost : lecture directe pendant une session
Dans le terminal Claude Code, tape /cost. La commande renvoie le coût cumulé de la session en cours, la ventilation par type de token (input, output, cache creation, cache read) et la durée écoulée. Une sortie typique ressemble à ça :
Total cost: $4.83
Total duration (API): 12m 41s
Total duration (wall): 47m 22s
Total code changes: 1247 lines added, 318 lines removed
Usage by model:
claude-sonnet-5: input: 8.2k, output: 41k, cache read: 2.4M, cache write: 180kLa ligne cache read à 2,4 millions de tokens face à 8,2 k tokens input frais, c'est le signe qu'une session est correctement structurée : Claude relit un contexte stable au tarif préférentiel plutôt que de le renvoyer plein tarif à chaque tour. Depuis la version 2.1.251 sortie fin août 2026, /cost affiche aussi une ligne dédiée au cache de prompt par session : taux de succès (hit ratio), caches manqués, tokens re-mis en cache, état chaud ou froid. C'est ce qui permet de repérer un cache froid persistant sans sortir les logs bruts.
/cost se réinitialise à chaque nouvelle session. Le total historique se lit dans la Console Anthropic, on y revient. Complémentaire utile : /status affiche le modèle actif, le contexte restant dans la fenêtre et le mode de permission (auto, plan, restreint). Un contexte à 85 % de saturation explique souvent pourquoi la session suivante démarre avec un cache write massif.
Lire le cache de prompt : cache write vs cache read
Le prompt caching d'Anthropic marque certains blocs comme cacheables : le system prompt, les définitions d'outils, les fichiers de repo lourds. Ces blocs sont stockés cinq minutes (ou une heure sur l'option étendue, facturée 2x en écriture) et relus à 10 % du tarif input pendant la fenêtre. La première fois que le bloc apparaît dans une session, tu paies l'écriture à 1,25x. Les tours suivants, tu paies la lecture à 0,1x. Sur un system prompt de 30 k tokens réutilisé vingt fois, la différence est massive : environ 750 $ facturés en plein tarif contre 60 $ en cache read.
La règle pratique : si sur une session longue le cache read pèse moins de 50 % de tes tokens input totaux, ta structure de prompt est en cause. Trois symptômes fréquents. Le premier, une fenêtre glissante mal gérée qui pousse le contenu stable hors du cache toutes les cinq minutes. Le deuxième, un CLAUDE.md remanié en cours de session, ce qui invalide le bloc caché. Le troisième, l'ajout de fichiers via l'outil Read en tête de contexte plutôt qu'en fin, ce qui déplace le point de coupure du cache.
Le tableau ci-dessous montre l'ordre de grandeur pour une session de refactoring d'une heure sur un repo de 40 k tokens de contexte stable :
| Configuration | Tokens facturés | Coût estimé Sonnet 5 |
|---|---|---|
| Sans cache, prompt renvoyé plein tarif | 800 k input, 60 k output | environ 2,20 $ |
| Cache mal structuré, 30 % de hit | 560 k input, 240 k cache read, 60 k output | environ 1,77 $ |
| Cache bien structuré, 85 % de hit | 120 k input, 680 k cache read, 60 k output | environ 1,00 $ |
Les chiffres sont indicatifs, mais l'ordre de grandeur tient : entre une session non optimisée et une session bien cachée, le coût est grossièrement divisé par deux sur cet exemple Sonnet 5 ; le même rabais de cache (10 % en lecture, 1,25x en écriture) s'applique proportionnellement quel que soit le modèle.
Fixer un spend limit sur la clé API
Direction Anthropic Console, Settings, Limits. Trois niveaux à connaître. Le plafond mensuel du workspace couvre tout ce qui passe par ce workspace. La limite par clé API permet d'isoler un projet ou un développeur. Les alertes email se déclenchent à des seuils configurables (typiquement 50 %, 80 %, 100 %). Le plafond bloque les requêtes une fois atteint, ce qui protège si un agent part en boucle.
La bonne pratique : une clé par projet, ou par développeur, plutôt qu'une clé partagée. Exemple concret : clé workspace-refactoring-clientA plafonnée à 200 $ par mois, alerte à 100 $ puis 160 $. Si un sous-agent part en vrille, la facture s'arrête à 200 $ et tu es prévenu avant.
Depuis le 27 août 2026, la Console distingue clés personnelles et clés de compte de service, en plus des anciennes clés workspace. Une clé personnelle porte l'identité du compte qui l'a créée et meurt avec lui. Une clé de compte de service représente un service (pipeline CI, agent en production) et survit aux mouvements de personnel. Pour une équipe de plus de deux personnes, cette séparation vaut le quart d'heure de setup : tu sais qui ou quoi consomme quand tu vois un pic. Pour aller plus loin sur la partie technique, va voir la page clé API Anthropic.
Le dashboard Usage : voir ce que /cost ne montre pas
Console Anthropic, onglet Usage. Vue historique par jour, par modèle, par clé. Filtre par défaut sur les sept derniers jours pour repérer les pics d'usage. Les colonnes à lire : Input Tokens, Output Tokens, Cache Creation, Cache Read. Multiplie chaque colonne par le tarif correspondant du modèle pour retomber sur ton coût réel.
Un décalage à connaître : les données remontent avec quelques minutes de latence. Si /cost affiche 4,83 $ sur ta session en cours et que le dashboard n'a rien pour cette heure, attends dix minutes avant de suspecter un bug. Pareil pour la ventilation par clé, elle se stabilise après quelques heures.
Point utile pour piloter dans la durée : exporte l'usage mensuel en CSV et regarde la répartition Sonnet vs Opus. Si Opus représente plus de 40 % de tes tokens de sortie sur un mois, il y a un choix de modèle à revoir. Pour un panorama plus large sur l'orchestration d'agents autonomes avec Claude, la page pilier couvre la logique de découpage tâche par tâche.
Cinq leviers concrets pour diviser la facture
Le premier levier, choisir le bon modèle par tâche. Sonnet 5 tient largement 80 % des tâches de code courantes : refactoring, ajout de tests, corrections de bugs identifiés. Opus 5 se garde pour l'architecture, le debug de comportements émergents, les migrations complexes. Fable 5 pour les cas où tu as vraiment besoin de raisonner sur des chaînes d'inférence longues. La différence entre Sonnet et Opus, c'est un facteur 2,5 sur le tarif input et output.
Le deuxième levier, structurer les prompts pour maximiser le cache hit. Parties stables en haut (system prompt, définitions d'outils, fichiers de référence rarement modifiés), variables en bas (la tâche du moment, les fichiers en cours d'édition). Un CLAUDE.md bien organisé, court, avec des sections figées en tête, cache mieux qu'un fichier qui bouge à chaque commit.
Le troisième levier, /clear entre deux tâches non liées. Traîner le contexte d'une correction de bug en base de données quand tu passes ensuite à un composant React, c'est payer pour du contexte inutile à chaque tour. /clear réinitialise la session, coûte zéro, gagne beaucoup.
Le quatrième levier, borner les boucles agentiques. Dans les scripts qui appellent l'API directement, fixe un max_turns ou un budget de tokens explicite. Sans limite, une chaîne d'agents peut consommer 500 $ en une nuit sur une tâche qui aurait dû s'arrêter au bout de dix tours.
Le cinquième levier, externaliser la doc lourde via MCP plutôt que la coller dans le prompt. Un serveur MCP qui expose ta doc technique en lecture à la demande évite de recharger 60 k tokens à chaque tour. Claude appelle l'outil quand il en a besoin, paie l'appel, et rend la main. C'est aussi un des sujets couverts dans le setup de Claude Code.
Alerte pratique : ce qui coûte cher sans qu'on le voie
Trois pièges reviennent régulièrement sur ce type de facture. Premier piège, le CLAUDE.md trop long. Un fichier de 800 lignes lu à chaque tour d'une session de deux heures, c'est plusieurs millions de tokens facturés en pure perte. Symptôme dans /cost : cache write élevé, cache read faible en proportion, coût cumulé qui grimpe vite sans que le code avance. Fix : coupe CLAUDE.md à l'essentiel (moins de 200 lignes), déporte le reste dans des fichiers que Claude lira à la demande.
Deuxième piège, les sous-agents lancés en parallèle. Chaque sous-agent charge son propre contexte, souvent une copie partielle du contexte parent. Trois sous-agents lancés en parallèle, c'est potentiellement trois fois la facture pour la même tâche. Symptôme : la ligne Usage by model dans /cost montre plusieurs entrées avec des volumes cache write élevés. Fix : n'utilise les sous-agents que quand les tâches sont vraiment indépendantes, et pense à la limite par session (voir la gestion des sessions en arrière-plan).
Troisième piège, les outils MCP mal configurés qui renvoient des payloads massifs. Un outil qui retourne 40 k tokens à chaque appel, appelé quinze fois dans une session, c'est 600 k tokens de résultats d'outils facturés en input. Symptôme : les tokens input frais explosent alors que ta tâche est petite. Fix : passe l'outil en mode paginé, renvoie des résumés, ou ajoute un paramètre max_results côté serveur MCP.
Passer à la pratique
Le bon réflexe pour la semaine qui vient : ouvre Claude Code sur ton projet courant, lance /cost après quinze minutes de travail, vérifie ton ratio cache read. Si tu es en dessous de 50 %, réordonne ton prompt système et ton CLAUDE.md dans l'heure. Va sur la Console Anthropic, pose un spend limit à un montant qui te laisse dormir tranquille, et sépare tes clés par projet. Ça prend une demi-journée, ça se rentabilise sur le premier mois de facturation.
Une fois que tes coûts unitaires sont sous contrôle, la question suivante devient plus intéressante : quels agents autonomes tu veux mettre en production pour que Claude Code travaille pendant que tu fais autre chose. C'est exactement ce qu'on outille dans le programme Claude Agent, où on te montre comment concevoir, déployer et piloter vos agents autonomes avec un vrai budget maîtrisé et des livrables opérationnels.