Débat audio sur l'article :
J'ai toujours eu du mal à comprendre comment les tokens étaient calculés dans Claude Code.
Après six mois d'utilisation intensive de Claude Code et d'audit détaillé de mes sessions, j'ai enfin compris comment les tokens fonctionnent réellement.
Et contrairement à ce qu'on pourrait penser, ce n'est pas compliqué—c'est même étonnamment prévisible une fois qu'on comprend les quatre règles d'or.
Ce qui m'a surpris, c'est à quel point la structure des tokens dans Claude Code diffère d'une utilisation directe de l'API. Chaque appel d'outil, chaque lecture de fichier, chaque Grep ou Bash.
Tous ces appels internes s'accumulent silencieusement, sans que vous en ayez conscience. Une simple tâche de refactoring qui vous semble « rapide » peut consommer l'équivalent d'une conversation de 20 messages.
Dans cet article, je décortique les quatre types de tokens, l'effet boule de neige du contexte, et surtout les stratégies concrètes qui m'ont permis de réduire mes coûts API de 40-60%—sans sacrifier la productivité. Que vous soyez développeur solo ou CTO d'une équipe de 10 personnes, ces principes s'appliquent immédiatement.
Avant de continuer la lecture, je vous invite à vous inscrire à ma newsletter pour connaître en avant-première les futurs sujets traités chaque semaine.
1. Qu'est-ce qu'un token ? La monnaie de l'IA
Un token, c'est la plus petite unité de texte qu'un modèle d'IA peut traiter.
Voici ce que vous devez savoir :
Approximation simple
- En français : environ 3/4 de mot = 1 token
- En anglais : environ 4 caractères = 1 token
- En code : variable selon la syntaxe, mais généralement 1 token = 4-6 caractères
Quelques exemples concrets :
- « Bonjour » = 1 token
- « machine learning » = 2 tokens
- « console.log('hello') » = 4-5 tokens
- Une ligne de code Python typique = 5-10 tokens
Pourquoi les tokens existent
Les tokens ne sont pas une invention des marketeurs d'Anthropic pour vous facturer plus cher. Ils existent parce que les transformers (la technologie derrière Claude) traitent l'information token par token. Plus il y a de tokens à traiter, plus le modèle consomme de ressources computationnelles.
Et puisque Claude Code fait appel à l'API Anthropic, vous payez selon les ressources utilisées—logique économique simple.
2. Les quatre types de tokens (et leurs coûts)
Voici où les choses deviennent intéressantes. L'API Anthropic n'expose pas un seul type de token, mais quatre, avec des prix radicalement différents.
Type 1 : input tokens (tokens entrants)
Les input tokens sont tous les tokens qui constituent votre prompt—y compris le contexte accumulé des messages précédents.
Coût de base : 1 USD pour 1M d'input tokens (tarification Claude 3.5 Sonnet)
Exemple : Vous posez une question à Claude Code. Le prompt contient :
- Votre question : 50 tokens
- Le contexte du fichier ouvert : 500 tokens
- L'historique des trois messages précédents : 2000 tokens
- Total : 2550 input tokens
Type 2 : output tokens (tokens sortants)
Les output tokens sont les tokens de réponse générés par Claude.
Coût de base : 3 USD pour 1M d'output tokens (3x plus cher que l'input)
Exemple : Claude vous répond avec 500 tokens de texte.
- Coût : 500 × (3 / 1M) = 0.0015 USD ≈ 0.0015 centime
Type 3 : cache read tokens (lectures de cache)
Si vous utilisez la prompt caching (disponible sur Claude Code), chaque token lu depuis le cache coûte 10% du prix input.
Coût : 0.1 USD pour 1M de cache_read tokens (10x moins cher que l'input)
Intérêt : Si vous relisez le même contexte (un fichier volumineux, par exemple), le premier accès consomme des input tokens, les suivants consomment des cache_read tokens à 1/10e du prix.
Type 4 : cache write tokens (écritures de cache)
Stocker un token dans le cache coûte 25% du prix input.
Coût : 0.25 USD pour 1M de cache_write tokens
Intérêt : Surcoûteux au premier accès, mais rentabilisé rapidement si vous relisez le même contexte plus de 3-4 fois.
Tableau récapitulatif des coûts
| Type de Token | Coût par Million | Ratio | Cas d'Usage |
|---|---|---|---|
| Input | 1 USD | 1x | Premier accès au contexte |
| Cache Write | 0.25 USD | 0.25x | Stockage du contexte en cache |
| Cache Read | 0.1 USD | 0.1x | Relecture du contexte en cache |
| Output | 3 USD | 3x | Réponses du modèle |
3. L'effet boule de neige : comment le contexte s'accumule
Voici la partie que la plupart des gens ne comprennent pas.
Chaque message que vous envoyez à Claude Code consomme TOUS les tokens de la conversation précédente plus les nouveaux tokens.
Pourquoi ? Parce que Claude doit relire toute la conversation pour contextualiser sa réponse. C'est comme si, à chaque message, vous renvoyiez au modèle l'historique complet + votre nouvelle question.
Exemple concret : une session de 5 messages
Message 1 : Vous posez une question (100 tokens)
- Input tokens : 100
- Output tokens : 200
- Coût cumulé : 100 + (200 × 3) = 700 tokens
Message 2 : Vous posez une deuxième question (100 tokens)
- Input tokens : 100 (question) + 100 (message 1) + 200 (réponse 1) = 400 tokens
- Output tokens : 150
- Coût cumulé : 700 + 400 + (150 × 3) = 1550 tokens
Message 3 : Troisième message (100 tokens)
- Input tokens : 100 + 400 + 150 + 100 = 750 tokens
- Output tokens : 200
- Coût cumulé : 1550 + 750 + 600 = 2900 tokens
Vous voyez le pattern ? À chaque message, le nombre d'input tokens augmente. C'est exponentiellement croissant, et c'est pourquoi une conversation de 10 messages peut facilement consommer 50 000+ tokens.
Données réelles d'audit
D'après mon audit de six mois de sessions Claude Code :
- Session moyenne : 2500-3500 tokens
- Session productive (5-10 messages) : 8000-15000 tokens
- Longue session (20+ messages) : 40000-80000 tokens
- Session avec fichiers volumineux : 100000+ tokens (une fois que vous avez ouvert un fichier de 10 000 lignes)
Comment le cache aide (mais pas autant qu'on l'espère)
Le prompt caching peut réduire les coûts de 30-40% si vous relisez le même contexte. Mais la plupart des utilisateurs Claude Code ne savent même pas que ça existe.
Imaginons la même conversation avec caching activé :
Message 1 : (identique)
- Input tokens : 100
- Cache Write tokens : 100 (stockage du contexte)
- Output tokens : 200
- Coût : 100 + (100 × 0.25) + (200 × 3) = 725 tokens
Message 2 : Avec caching
- Cache Read tokens : 100 (relecture depuis cache)
- Input tokens : 100 (nouvelle question)
- Output tokens : 150
- Coût : (100 × 0.1) + 100 + (150 × 3) = 560 tokens (vs 700 sans cache)
Le gain est réel, mais il ne s'accumule que si vous relisez le même contexte de base.
4. Tokens étendus : la pensée prolongée coûte cher
Depuis octobre 2024, Claude supporte la extended thinking—une mode où le modèle « pense » longuement avant de répondre, améliorant la qualité pour les problèmes complexes.
Coût : Les tokens de « pensée » sont facturés à 3 USD par million, identique aux output tokens.
Implication : Si Claude utilise 10 000 tokens pour penser et 500 pour répondre, vous payez pour 10 500 tokens de sortie.
Cela peut multiplier le coût d'une requête par 5-10x pour les tâches d'architecture ou de refactoring profond.
5. Comment Claude Code accumule les tokens différemment de l'API
Si vous utilisez Claude directement via l'API Anthropic, vous payez à chaque requête et vous maîtrisez exactement ce qui est envoyé.
Avec Claude Code, c'est plus insidieux :
- Chaque outil appelé (Read, Grep, Bash, Edit, etc.) génère un message API qui inclut le contexte complet
- Les fichiers lus sont ajoutés au contexte sans que vous le voyiez clairement
- Les réponses du système sont échangées silencieusement, accumulant du contexte
Audit réel : tâche de refactoring
J'ai mesuré une simple tâche de refactoring (renommer une fonction dans 3 fichiers) :
- Messages visibles : 5
- Appels API réels : 12 (Read, Grep, Edit, vérifications)
- Tokens totaux : 18 500 (équivalent à une conversation complète)
- Coût estimé : 0.015 USD (0.015 centime)
Cela peut sembler négligeable, mais multiplié par 100 tâches par jour = 1.5 USD/jour = 45 USD/mois rien que pour Claude Code.
6. Analyse réelle : cas d'étude d'une session productive
Voici les données réelles d'une de mes sessions productives (27 février 2026) :
Contexte : Écriture d'un article complet avec recherche, outline, draft, et révisions.
Métriques mesurées :
| Métrique | Valeur |
|---|---|
| Nombre de messages | 8 |
| Fichiers lus | 12 |
| Recherches Grep | 15 |
| Appels API réels | 35 |
| Total input tokens | 45 200 |
| Total output tokens | 8 500 |
| Total cache_read tokens | 3 200 |
| Total cache_write tokens | 5 100 |
| Coût total estimé | 0.148 USD |
Décomposition du coût :
Input: 45 200 × (1 / 1M) = 0.0452 USD
Cache Write: 5 100 × (0.25 / 1M) = 0.00127 USD
Cache Read: 3 200 × (0.1 / 1M) = 0.00032 USD
Output: 8 500 × (3 / 1M) = 0.0255 USD
───────────────────────────────
TOTAL = 0.071 USD (environ 1 demi-centime d'euro)
Cela semble minuscule. Mais imaginez 20 sessions comme celle-ci par jour pour une équipe de 10 développeurs : c'est 40+ USD/jour = 1200 USD/mois rien que pour Claude Code.
7. Stratégies d'optimisation : réduire vos coûts de 40-60%
Maintenant que vous comprenez comment les tokens fonctionnent, voici comment les optimiser.
Stratégie 1 : regrouper les questions
Au lieu de poser 10 questions séquentielles (coûtant 10x le contexte accumulatif), regroupez-les :
Mauvais :
Q1: Lis le fichier A (accès = 100 tokens input)
Q2: Lis le fichier B (accès = 200 tokens input, car contexte de Q1 réinclus)
Q3: Compare-les (accès = 350 tokens input)
Total : ~600 tokens
Bon :
Q1: Lis A, lis B, et compare-les (accès = 250 tokens input)
Total : ~250 tokens
Économie : -60% sur les lectures multiples
Stratégie 2 : nettoyer l'historique de session
Claude Code accumule l'historique indéfiniment. Une session de 20 messages peut consommer 10x plus qu'une de 5 messages.
Si vous sentez que les coûts explosent, fermez la session et en ouvrez une nouvelle.
Économie : -70% en renouvellements de session
Stratégie 3 : limiter les fichiers volumineux en contexte
Les fichiers > 10 000 lignes doublent l'accumulation de tokens.
Préférez :
- Utiliser Grep pour extraire les sections pertinentes
- Diviser les gros fichiers en modules plus petits
- Utiliser des .env.example au lieu de copier des configs entières
Économie : -40% si vous travaillez beaucoup avec de gros fichiers
Stratégie 4 : utiliser extended thinking judicieusement
N'activez la pensée prolongée que pour les tâches vraiment complexes (architecture, optimisation, debugging profond). Pour les tâches simples (lectures, refactoring basique), elle ne sert à rien et coûte 5-10x plus cher.
Économie : -20-30% en évitant les pensées inutiles
8. Questions fréquentes
Q : Les tokens gratuits fournis avec Claude Code comptent-ils ?
R : Oui et non. Si vous utilisez Claude Code via le CLI gratuit, les tokens sont décomptés de votre quota Anthropic payant. Il n'y a pas de « tokens gratuits »—vous payez tous les tokens.
Q : Puis-je voir exactement combien de tokens j'ai consommé ?
R : Partiellement. Le CLI Claude Code n'expose pas les détails par requête, mais vous pouvez auditer via l'API avec usage.input_tokens et usage.output_tokens dans les logs.
Q : Est-ce que le caching me sauve vraiment de l'argent ?
R : Oui, si vous relisez le même contexte plus de 3-4 fois dans la même session. Pour une session unique, le surcoût du caching (25% pour l'écriture) n'est rentabilisé que par les relectures ultérieures.
Q : Combien devrait coûter une session Claude Code « normale » ?
R : Entre 0.01 et 0.10 USD selon la complexité. Si vos sessions coûtent régulièrement > 0.50 USD, c'est qu'il y a quelque chose d'inefficace (fichiers trop gros, historique trop long, etc.).
Q : Le coût des tokens a-t-il baissé récemment ?
R : Oui. Anthropic a réduit ses tarifs en février 2025. Claude 3.5 Sonnet coûte maintenant 1 USD/M d'input tokens (vs 3 USD précédemment). Vérifiez toujours les tarifs officiels.
9. Conclusion : reprendre le contrôle
Les tokens ne sont pas mystérieux. Une fois que vous comprenez :
- Qu'un token ≈ 3/4 mot, vous pouvez estimer vos coûts à la volée
- Que les 4 types de tokens ont des coûts très différents, vous pouvez optimiser votre architecture (caching, regroupement)
- Que le contexte s'accumule à chaque message, vous évitez les longues sessions inutiles
- Que Claude Code cache l'accumulation des appels API, vous restez vigilant sur les fichiers énormes
Avec ces quatre concepts, vous réduisez facilement vos coûts de 40-60% sans perdre en productivité.
Et contrairement aux taxes réelles, cette « taxe des tokens » est entièrement maîtrisable—si vous savez où regarder.
Qui suis je ?
Je suis Mathieu GRENIER, CTO d'Easystrat une startup de Montpellier, en France. Je manage une équipe d'une dizaine d'ingénieurs (Graphistes, IA, frontend, backend, devOps, AWS) en remote depuis le Japon.
J'ai aussi mon activité de freelance, où je conseille des entrepreneurs dans leurs projets d'application.
Avec mon expérience personnelle de plus de 15 ans en ESN, j'ai pu travailler pour un large panel d'entreprises de différentes tailles. Ma compréhension des problèmes métiers est une de mes grandes forces et permet à mes clients de pouvoir se projeter plus facilement.
L'essentiel de mon travail consiste à canaliser l'énergie des entrepreneurs sur l'essence même de leur projet.
La technologie, les méthodes, le management sont le cœur de mes compétences.
Vous pouvez me faire confiance sur ces points là.
Si vous voulez me parler d'un de vos projets, n'hésitez pas à m'envoyer un email avec vos disponibilités à : contact@mathieugrenier.fr
Tous les articles de ce blog sont écrits par moi, même si je peux m'aider de l'IA pour illustrer mes propos. Mais jamais je ne fournis d'articles 100% IA.
Comment fonctionnent vraiment les tokens dans Claude Code