Budget de tokens d'un agent IA de code : le fixer

On fixe un budget de tokens pour un agent IA de code en trois couches : un plafond par tâche, un seuil par session et une limite stricte par mois chez le fournisseur. Chaque couche a son propre garde-fou. L'agent peut arrêter une tâche, un compteur peut vous alerter en pleine session, et seul le fournisseur peut refuser de vous facturer au-delà d'un montant.

La plupart des gens ne règlent que la dernière, quand ils la règlent, et découvrent le coût d'une session en fin de mois. Un budget qu'on ne voit qu'après coup, c'est un reçu, pas un budget. La version utile vous informe pendant que l'agent tourne encore.

Les flags, commandes et réglages de console cités ici ont été lus dans les documentations officielles de Claude Code, de la Claude Platform, d'OpenAI et de ccusage le 15/10/2026. Laisser un agent tourner seul toute la nuit est un problème à part, avec ses propres pièges : il est traité dans empêcher un agent de nuit de brûler votre budget. Ce guide-ci porte sur la tâche et la session du quotidien.

Que doit plafonner un budget de tokens pour un agent IA de code ?

Un budget de tokens doit plafonner trois choses, parce qu'elles dérapent de trois façons différentes :

Le plafond par tâche est le plus précis. Le plafond par session est celui qui fait économiser le plus au quotidien, car le coût de chaque tour augmente avec le transcript. Le plafond mensuel est le plus grossier, et le seul qu'un bug de l'agent ne peut pas contourner.

Je budgète en dollars plutôt qu'en tokens bruts. Un token lu depuis le cache et un token d'output neuf n'ont pas du tout le même prix, donc « 500k tokens » ne dit pas grand-chose de la facture. Tous les outils ci-dessous affichent de toute façon une estimation en dollars.

Quelle taille donner au budget ?

Dimensionnez le budget à partir d'une semaine de votre propre usage mesuré, pas d'un chiffre que vous aimeriez dépenser. Travaillez normalement quelques jours, lisez les montants par session, et fixez le plafond par tâche un peu au-dessus de ce que coûte une tâche typique de ce genre.

S'il vous faut un point de départ avant d'avoir des données, Anthropic en publie un pour les équipes.

Son guide des coûts indique que, sur l'ensemble des déploiements entreprise, Claude Code revient en moyenne à environ 13 $ par développeur et par jour actif, et 150 à 250 $ par mois, 90 % des utilisateurs restant sous 30 $ par jour actif (docs Claude Code, Manage costs, lu le 15/10/2026). C'est une moyenne sur des postes entreprise, pas un objectif pour un développeur solo.

La règle pratique que j'applique :

1. Par tâche : environ 1,5 fois le coût médian des tâches similaires passées. Assez serré pour attraper une boucle, assez large pour ne pas couper un travail normal.
2. Par session : le montant à partir duquel vous préférez ouvrir une session neuve plutôt que continuer. Pour moi, c'est quand le contexte est surtout fait d'anciennes lectures de fichiers.
3. Par mois : votre vrai plafond, le montant auquel vous voulez que le trafic s'arrête.

Comment obtenir ces chiffres passés : voir comment mesurer l'usage de tokens d'un agent.

Comment limiter l'usage de tokens de Claude Code par session ?

Dans Claude Code, on limite une session de deux façons : des plafonds stricts pour les exécutions non interactives, et un compteur en direct pour les sessions interactives. Les plafonds stricts sont des flags de claude -p ; il n'existe pas d'arrêt strict équivalent pour une session interactive, où l'on s'appuie donc sur ce qui s'affiche à l'écran.

Plafonds stricts pour les tâches non interactives

Deux flags plafonnent une exécution non interactive (référence CLI, lue le 15/10/2026) :

• --max-budget-usd arrête l'exécution quand la dépense API estimée atteint le montant. La dépense des subagents compte.
• --max-turns limite le nombre de tours agentiques et sort en erreur quand il est atteint. Il n'y a pas de limite par défaut.

Les deux ne fonctionnent qu'en mode print. Une tâche scriptée ressemble à ceci :

Lisez les petites lignes avant de vous fier au chiffre. La doc précise que le plafond est vérifié par rapport à l'estimation de coût calculée côté client par Claude Code, qui peut différer de votre facture, et que la dépense peut dépasser le plafond.

Dans l'Agent SDK, où les mêmes contrôles existent sous les noms maxTurns et maxBudgetUsd, la doc explique pourquoi : la réponse qui atteint le plafond va quand même jusqu'au bout (doc de la boucle agent, lue le 15/10/2026). Gardez de la marge.

Un compteur en direct pour les sessions interactives

En interactif, la lecture à vérifier est /usage. La commande affiche le coût de la session, les limites d'usage du forfait et des statistiques d'activité, et /cost en est un alias (référence des commandes, lue le 15/10/2026). Le montant est calculé en local à partir du nombre de tokens au prix catalogue : c'est une estimation.

Sur Pro et Max, la doc précise que ce coût de session n'est pas ce qui vous est facturé. Je le surveille quand même : c'est l'indicateur le plus direct de la vitesse à laquelle une session entame les limites du forfait. Le guide limites de Claude Code détaille les fenêtres de 5 heures et hebdomadaire derrière ces limites.

Taper une commande tous les trois tours, ça ne tient pas. Une status line, si, parce qu'elle reste visible. Claude Code lui transmet un objet JSON qui contient cost.total_cost_usd et context_window.used_percentage (doc de la status line, lue le 15/10/2026). Ce script affiche le coût de la session face à un budget :

Puis déclarez-le dans vos settings :

Quand la ligne affiche BUDGET DÉPASSÉ, je termine la sous-tâche et je lance /clear. Depuis la v2.1.211, les totaux de session sont remis à zéro par /clear, donc le coût de la session suivante repart de 0 $ (Manage costs).

La place des hooks

Les hooks peuvent bloquer un appel d'outil : un hook PreToolUse peut renvoyer un permissionDecision à "deny" (référence des hooks, lue le 15/10/2026). En revanche, ils ne reçoivent pas de montant, seulement des champs comme transcript_path. Un budget fondé sur des hooks suppose de parser le transcript vous-même, et la doc prévient que ce fichier peut avoir du retard sur le tour en cours.

Je ne construis pas de budget sur des hooks. Je m'en sers pour rendre chaque appel moins cher, ce que détaille les hooks Claude Code qui réduisent les tokens.

Comment budgéter Codex et les autres agents ?

Codex fournit un compteur mais, dans la doc que j'ai lue, pas de plafond de dépense par exécution. Sa commande /status affiche la configuration de la session et l'usage de tokens, dont le contexte restant, et /usage montre l'activité en tokens du compte par jour, par semaine ou en cumul (commandes développeur Codex, lues le 15/10/2026).

Pour Codex, le budget par session repose donc sur la même habitude qu'en Claude Code interactif : vérifier /status, lancer /compact après les longs échanges, repartir à zéro à votre seuil. L'arrêt strict passe chez le fournisseur, juste en dessous.

Pour les autres agents, je n'ai pas trouvé de flag de dépense par session documenté que j'aie pu vérifier, donc je n'en cite pas. Le principe reste le même : un compteur dans la session, un plafond chez le fournisseur. ccusage lit les logs locaux de beaucoup d'entre eux, comme on le verra plus bas.

Où fixer une limite de dépense stricte chez le fournisseur ?

La limite de dépense du fournisseur est le seul budget qu'un agent ne peut pas dépasser de beaucoup : réglez-la avant toutes les autres couches. Son emplacement dépend de la façon dont vous payez.

Claude Console (clé API). L'usage de Claude Code se gère par workspaces, et la première fois que vous vous authentifiez avec un compte Console, un workspace nommé « Claude Code » est créé pour vous (Manage costs).

Dans la page Workspaces de la Console, sélectionnez le workspace puis ouvrez Spend limits pour plafonner la dépense mensuelle et ajouter des alertes à certains seuils (doc des workspaces, lue le 15/10/2026). La page Rate limits permet aussi de plafonner les tokens d'input et d'output par minute pour un workspace.

Claude Pro ou Max. Les limites d'usage du forfait sont le plafond par défaut. Si vous activez les crédits d'usage pour continuer au-delà, vous pouvez fixer une limite de dépense mensuelle pour ces crédits, et /usage affiche la dépense du mois face à cette limite (Manage costs).

Claude Team ou Enterprise. L'allocation de chaque poste est le plafond par défaut. Les admins peuvent activer les crédits d'usage et fixer des limites de dépense au niveau de l'organisation, d'un groupe ou d'un membre (Manage costs).

API OpenAI. Vous pouvez fixer une hard spend limit pour l'organisation ou pour un projet. Quand la dépense suivie l'atteint, les requêtes renvoient une erreur 429 avec le code organization_spend_limit_exceeded ou project_spend_limit_exceeded (spend limits OpenAI, lu le 15/10/2026). OpenAI précise que l'application n'est pas instantanée : la dépense enregistrée peut légèrement dépasser la limite.

Deux habitudes rendent ces limites utiles plutôt que simplement présentes :

• Des alertes sous le plafond. Une alerte à 50 % et une à 80 % vous disent que le mois se passe mal tant que vous pouvez encore changer quelque chose.
• Un workspace ou un projet séparé pour les expériences. Une nouvelle configuration d'agent reçoit sa propre petite limite, et une mauvaise semaine ne mange pas le budget de votre vrai travail.

Comment suivre la dépense face au budget ?

On suit la dépense avec un compteur qui lit ce que l'agent a déjà journalisé. ccusage est le choix standard : il lit les logs locaux des agents et produit des rapports par jour, par semaine, par mois et par session, avec des coûts estimés d'après le prix des modèles (guide ccusage, lu le 15/10/2026).

Pour Claude Code, il propose aussi une vue blocks pour la fenêtre de facturation de 5 heures et un mode statusline compact (ccusage, source Claude Code, lu le 15/10/2026). Si ccusage ne colle pas à votre façon de travailler, les alternatives à ccusage comparent les autres options.

Relisez-le une fois par semaine face aux trois plafonds. Si les tâches finissent souvent près du plafond par tâche, soit le plafond est trop serré, soit les tâches sont trop grosses. Si les sessions atteignent souvent leur seuil, le problème vient en général de ce qui s'accumule dans le contexte.

Comment faire tenir le budget ?

Un budget tient quand chaque tour coûte moins, pas quand vous écrivez moins de prompts. Un agent relit tout le transcript à chaque tour, donc une grosse lecture de fichier en début de session est repayée à chaque tour suivant. Le token le moins cher est celui qui n'entre jamais dans le contexte.

Les leviers, dans l'ordre où je les applique :

1. Une tâche, une session. /clear entre deux tâches sans rapport. Un contexte neuf n'a rien d'ancien à relire.
2. Compacter entre les sous-tâches, pas à l'alerte. /compact résume les tours précédents, donc la sous-tâche suivante part d'un contexte plus petit.
3. Filtrer les sorties de commandes. Un test qui déverse des milliers de lignes n'a besoin que de l'assertion en échec.
4. Chercher plutôt que lire des fichiers entiers. Demandez la fonction, pas le module.
5. Prendre un modèle plus petit quand il suffit. Le guide des coûts d'Anthropic suggère model: haiku dans la configuration des subagents simples.
6. Déconnecter les serveurs MCP dont la tâche n'a pas besoin. Leurs définitions d'outils occupent du contexte à chaque tour.

La liste complète, avec le mécanisme derrière chaque levier, se trouve dans comment réduire l'usage de tokens de Claude Code.

Appliquer tout cela à la main, à chaque session, c'est ce qu'on abandonne en premier sous la pression. Tokenade l'automatise dans l'agent : recherche sémantique au lieu de lire des fichiers entiers, sorties de commandes filtrées, lecture en squelette des gros fichiers, compaction de la sortie des serveurs MCP. Sur le benchmark THOL, il réduit le coût des sessions de 39 % sur les sessions longues (méthodologie). La compaction tourne sur l'ordinateur où vous travaillez, et Tokenade lui-même est gratuit et open source (MIT/Apache-2.0) : il n'ajoute aucune ligne au budget.

Ce qui tourne mal (anti-patterns)

L'échec habituel, c'est un budget qui existe sur le papier et n'applique rien. Méfiez-vous de ceci :

• Un seul chiffre mensuel. Vous découvrez une mauvaise semaine en fin de mois. Ajoutez le compteur de session.
• Croire le plafond au centime près. --max-budget-usd comme les limites du fournisseur peuvent être légèrement dépassés. Réglez-les sous ce que vous pouvez vraiment vous permettre.
• Budgéter en tokens bruts. Les lectures en cache et les tokens d'output neufs ne coûtent pas du tout pareil. Utilisez l'estimation en dollars.
• Relever le plafond au lieu de lire la session. Une tâche qui bute sans cesse sur son plafond est souvent coincée à relire le même contexte. Regardez /context avant de lui donner plus d'argent.
• Un seul workspace pour tout. Une expérience et votre travail quotidien partagent alors la même limite. Séparez-les.

FAQ

Peut-on fixer une limite stricte de tokens sur une session interactive de Claude Code ?

Pas avec un flag documenté. --max-budget-usd et --max-turns ne s'appliquent qu'en mode print (claude -p). En interactif, utilisez /usage ou une status line qui affiche cost.total_cost_usd, et ouvrez une session neuve quand vous atteignez votre seuil. La limite de dépense du fournisseur reste l'arrêt strict.

--max-budget-usd correspond-il à ma facture réelle ?

Pas exactement. Claude Code compare le plafond à sa propre estimation côté client au prix catalogue, qui peut différer de ce qui vous est facturé, et la réponse qui franchit le plafond va quand même au bout. Gardez de la marge, et considérez la page Usage de la Console comme le chiffre qui fait foi.

Que se passe-t-il quand une hard spend limit OpenAI est atteinte ?

Les requêtes API concernées renvoient une erreur 429 avec le code organization_spend_limit_exceeded ou project_spend_limit_exceeded. Le trafic reprend quand vous relevez ou supprimez la limite, ou au cycle mensuel suivant. L'application n'est pas instantanée : la dépense peut légèrement dépasser la limite.

Le budget de tokens est-il différent pour les abonnés Pro ou Max ?

Oui. Sur Pro et Max, les limites d'usage du forfait sont votre plafond, et le coût de session en dollars n'est pas ce qui vous est facturé. Le budget porte sur la vitesse à laquelle vous consommez les fenêtres de 5 heures et hebdomadaire. Une limite de dépense mensuelle ne compte que si vous activez les crédits d'usage.

Comment empêcher un agent de trop dépenser pendant la nuit ?

Ce cas demande plus qu'un compteur de session, puisque personne ne regarde. Le guide empêcher un agent de nuit de brûler votre budget le traite.

Voir aussi :

• Empêcher un agent IA de nuit de brûler votre budget : le cas sans surveillance.
• Limites de Claude Code : comment rester en dessous : les fenêtres de 5 heures et hebdomadaire.
• Comment mesurer l'usage de tokens d'un agent : les chiffres dont part votre budget.
• Alternatives à ccusage : d'autres compteurs, et des outils qui font baisser le chiffre.
• Comment réduire l'usage de tokens de Claude Code : tous les leviers qui font durer un budget.