DEV Community

Cover image for Comment Réduire les Coûts des Tokens d'Agent en Ligne de Commande (Guide 2026)
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment Réduire les Coûts des Tokens d'Agent en Ligne de Commande (Guide 2026)

#agents #ai #cli #productivity

Un agent de codage CLI paraît économique jusqu’au moment où la facture arrive. Vous lancez Claude Code ou Codex sur un dépôt, demandez une refactorisation, puis l’agent lit quarante fichiers, relance les tests plusieurs fois et consomme des centaines de milliers de jetons pour un contexte inutile. À l’échelle d’une équipe, ce n’est plus un détail. La bonne nouvelle : une grande partie de cette dépense se réduit depuis la ligne de commande, sans changer de modèle principal ni dégrader la qualité.

Essayez Apidog aujourd’hui

TL;DR

Pour réduire le coût des agents CLI :

  1. Limitez le contexte avant qu’il n’atteigne le modèle.
  2. Nommez explicitement les fichiers à modifier.
  3. Gardez les fichiers mémoire comme CLAUDE.md courts.
  4. Utilisez /compact ou /clear entre deux tâches.
  5. Activez la mise en cache des prompts pour les préfixes stables.
  6. Routez les sous-tâches simples vers un modèle moins cher.
  7. Réduisez la sortie des outils (npm test, pytest, git diff, etc.).
  8. Mesurez le coût par exécution au lieu d’attendre la facture mensuelle.

Introduction

Le problème se voit de deux façons : soit vous atteignez une limite de session ou de quota en plein travail, soit la facture API mensuelle déclenche une discussion budgétaire. Dans les deux cas, la cause est souvent la même : les agents CLI sont verbeux et curieux par défaut.

Ils lisent des fichiers complets alors que quelques lignes suffisent, rejouent toute la conversation à chaque tour, injectent des logs bruts dans le contexte et renvoient sans cesse le même prompt système. Une refactorisation qui demande réellement 2 000 jetons de code peut facilement embarquer 180 000 jetons de contexte.

Ce guide montre comment réduire ce gaspillage avec des pratiques directement applicables à Claude Code, Codex ou tout agent CLI facturé au jeton.

Un cas fréquent concerne les API internes. Quand un agent interagit avec une API instable ou mal documentée, il boucle : requêtes échouées, lecture des erreurs, inspection de la documentation, nouvelle tentative. Chaque itération coûte des jetons.

💡 Si vos agents manipulent des API, concevoir, simuler et tester ces API dans Apidog avant de les exposer à un agent réduit fortement les cycles d’essais-erreurs. L’agent travaille contre un contrat prévisible plutôt que contre un endpoint live surprenant.

Où partent réellement les jetons d’un agent CLI

Un tour d’agent envoie une entrée au modèle et reçoit une sortie. Vous payez les deux. En général, les jetons de sortie coûtent plus cher que les jetons d’entrée, mais c’est souvent l’entrée qui explose.

Les principaux postes de coût sont :

  • Prompt système et définitions d’outils : instructions de l’agent, schémas JSON des outils, règles globales.
  • Fichiers mémoire : CLAUDE.md, conventions du projet, consignes persistantes.
  • Historique de conversation : messages, réponses, appels d’outils et résultats précédents.
  • Fichiers lus par l’agent : un fichier de 1 200 lignes peut représenter 12 000 à 18 000 jetons.
  • Sortie d’outils : logs de tests, npm install, stack traces, diffs volumineux.

Le point critique : l’historique est renvoyé à chaque tour. Une session de 30 tours ne coûte pas 30 fois un tour fixe. Elle ressemble plutôt à une somme de contextes de plus en plus longs.

C’est pourquoi les sessions longues et non structurées coûtent cher. Une explication complémentaire est disponible ici : comment la fenêtre de jetons Claude Code se réinitialise.

1. Délimitez le contexte avant de lancer l’agent

Le jeton le moins cher est celui que vous n’envoyez pas.

Évitez les prompts vagues comme :

claude "refactor the billing logic"
Enter fullscreen mode Exit fullscreen mode

Préférez une instruction bornée :

claude "refactor the retry logic so it uses exponential backoff,
only in src/payments/retry.ts and src/payments/retry.test.ts"
Enter fullscreen mode Exit fullscreen mode

Cette différence est simple, mais importante : l’agent ne part pas explorer tout le dépôt pour trouver les fichiers pertinents.

Si vous devez lui laisser de la marge, limitez au moins le répertoire :

claude "inspect src/payments only and propose the smallest change needed
to make retries use exponential backoff"
Enter fullscreen mode Exit fullscreen mode

2. Gardez CLAUDE.md court

Un fichier mémoire comme CLAUDE.md est souvent injecté à chaque tour. Beaucoup d’équipes y mettent progressivement :

  • documentation d’onboarding ;
  • conventions générales ;
  • détails historiques ;
  • exemples obsolètes ;
  • consignes rarement utilisées.

Résultat : plusieurs milliers de jetons renvoyés en permanence.

Mesurez rapidement sa taille :

wc -c CLAUDE.md | awk '{print "≈", int($1/4), "tokens per turn"}'
Enter fullscreen mode Exit fullscreen mode

Un bon CLAUDE.md doit contenir uniquement :

  • commandes de build ;
  • commandes de test ;
  • conventions strictes ;
  • chemins vers la documentation détaillée ;
  • règles que l’agent doit toujours respecter.

Exemple plus efficace :

# Instructions agent

## Tests

- Unit tests: `npm test -- --runInBand`
- Lint: `npm run lint`
- Typecheck: `npm run typecheck`

## Conventions

- Ne pas modifier `generated/`.
- Ne pas éditer les fichiers de lock sauf demande explicite.
- Préférer des changements minimaux et ciblés.

## Documentation

- API payments: `docs/payments-api.md`
- Architecture billing: `docs/billing.md`
Enter fullscreen mode Exit fullscreen mode

Évitez de coller toute la documentation dans le fichier mémoire. Donnez plutôt les chemins que l’agent pourra lire à la demande.

3. Compactez ou réinitialisez les longues sessions

Si vous terminez une tâche puis en commencez une autre dans la même session, vous traînez tout l’ancien contexte.

Dans Claude Code :

/compact
Enter fullscreen mode Exit fullscreen mode

Utilisez /compact quand la session contient encore des informations utiles, mais que l’historique brut devient trop lourd.

Pour une nouvelle tâche indépendante :

/clear
Enter fullscreen mode Exit fullscreen mode

Règle pratique :

  • une tâche logique = une session ;
  • changement de sujet = /compact ou /clear ;
  • refactorisation terminée = nouvelle session pour la suite.

Les modèles de workflow présentés dans les flux de travail de Claude Code reposent largement sur cette discipline.

4. Ignorez les fichiers inutiles

Empêchez l’agent de lire ce qui n’a aucune valeur pour la tâche :

  • node_modules/
  • dist/
  • build/
  • fichiers générés ;
  • fichiers de lock volumineux ;
  • rapports de couverture ;
  • exports temporaires.

Exemple de fichier d’ignorance selon l’outil utilisé :

node_modules/
dist/
build/
coverage/
generated/
*.lock
package-lock.json
pnpm-lock.yaml
yarn.lock
Enter fullscreen mode Exit fullscreen mode

Si un fichier de lock doit être modifié, faites-le explicitement. Sinon, il peut polluer les diffs et le contexte.

5. Activez la mise en cache des prompts

La mise en cache des prompts permet au fournisseur de réutiliser un préfixe stable : prompt système, définitions d’outils, règles de projet, conventions.

Le principe :

contenu stable → cache
contenu variable → pas dans le cache
Enter fullscreen mode Exit fullscreen mode

L’ordre compte. Placez les éléments stables en premier :

outils → système → conventions projet → tâche utilisateur → fichiers récupérés
Enter fullscreen mode Exit fullscreen mode

Si vous appelez directement l’API depuis votre wrapper CLI, vous pouvez définir un point de cache :

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT + REPO_CONVENTIONS,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {
            "role": "user",
            "content": user_task,
        }
    ],
)

u = response.usage

print("cache write:", u.cache_creation_input_tokens)
print("cache read :", u.cache_read_input_tokens)
print("fresh input:", u.input_tokens)
Enter fullscreen mode Exit fullscreen mode

Points d’attention :

  • ne mettez pas d’horodatage dans le préfixe caché ;
  • ne changez pas dynamiquement les conventions projet ;
  • regroupez les exécutions proches pour garder un cache chaud ;
  • vérifiez les métriques cache_read_input_tokens.

Un bloc stable de 8 000 jetons utilisé 60 fois par jour devient beaucoup moins coûteux s’il est lu depuis le cache plutôt que retraité à chaque invocation.

Pour compléter cette approche, voir aussi l’exécution gratuite de GPT-5.5 via Codex, qui couvre d’autres stratégies de routage et de limites.

6. Routez les tâches simples vers un modèle moins cher

Toutes les actions ne nécessitent pas le modèle le plus puissant.

Exemples de tâches adaptées à un modèle économique :

  • générer un message de commit ;
  • résumer un diff ;
  • écrire une entrée de changelog ;
  • expliquer une erreur de lint ;
  • renommer une variable ;
  • produire un test standard.

Exemple CLI :

claude --model haiku "write a conventional-commit message for the staged diff"
Enter fullscreen mode Exit fullscreen mode

Réservez le modèle plus coûteux aux tâches qui demandent vraiment du raisonnement :

claude --model sonnet "redesign the caching layer for the payments service"
Enter fullscreen mode Exit fullscreen mode

Une bonne stratégie consiste à inverser le défaut habituel :

  • modèle économique par défaut ;
  • montée en gamme explicite quand la tâche est complexe.

Si votre framework supporte des sous-agents, donnez-leur :

  • un modèle moins cher ;
  • un contexte réduit ;
  • une mission précise.

Le parent coûteux ne reçoit ensuite qu’un résumé ou un résultat filtré. Les modèles décrits dans la commande "goal" entre Codex et Claude Code montrent comment structurer cette délégation.

Même avec une hausse de quota comme l’augmentation de la limite hebdomadaire de Claude Code, le routage reste nécessaire pour éviter de consommer le budget premium sur des tâches mécaniques.

7. Réduisez la sortie des outils

Les logs sont souvent réinjectés tels quels dans le contexte. Chaque ligne affichée par une commande peut devenir un coût répété aux tours suivants.

Tests

Au lieu de :

npm test
Enter fullscreen mode Exit fullscreen mode

Utilisez une sortie plus concise :

npm test --silent -- --reporter=dot
Enter fullscreen mode Exit fullscreen mode

Pour Python :

pytest -q
Enter fullscreen mode Exit fullscreen mode

Ou, si vous voulez uniquement la fin du log :

pytest -q 2>&1 | tail -n 30
Enter fullscreen mode Exit fullscreen mode

Installation de dépendances

Au lieu de :

npm install
Enter fullscreen mode Exit fullscreen mode

Préférez :

npm install --silent --no-audit --no-fund
Enter fullscreen mode Exit fullscreen mode

Diffs

Au lieu de renvoyer un diff complet :

git diff
Enter fullscreen mode Exit fullscreen mode

Commencez par :

git diff --stat
Enter fullscreen mode Exit fullscreen mode

Puis ciblez un fichier si nécessaire :

git diff src/payments/retry.ts
Enter fullscreen mode Exit fullscreen mode

Logs d’erreur

Filtrez avant que l’agent ne voie la sortie :

npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20
Enter fullscreen mode Exit fullscreen mode

L’objectif n’est pas de cacher l’information utile. C’est d’éviter d’envoyer 5 000 lignes quand 30 suffisent.

8. Préférez les lectures ciblées

Lire un fichier entier pour modifier une fonction est rarement nécessaire.

Prompt utile :

Trouve la fonction qui gère les retries.
Lis uniquement cette fonction et 40 lignes autour.
Ne lis pas le fichier entier sauf si nécessaire.
Enter fullscreen mode Exit fullscreen mode

Commande utile côté shell :

grep -n "function retry" src/payments/retry.ts
Enter fullscreen mode Exit fullscreen mode

Puis :

sed -n '120,190p' src/payments/retry.ts
Enter fullscreen mode Exit fullscreen mode

Sur un gros fichier, cette stratégie peut transformer une lecture de 18 000 jetons en quelques centaines de jetons.

9. Contraignez la récupération documentaire

Si votre agent utilise une recherche de codebase ou du RAG, limitez :

  • le nombre de fragments ;
  • la taille des fragments ;
  • les répertoires explorés ;
  • les types de fichiers.

Mauvais comportement :

Récupère toute la documentation billing et payments.
Enter fullscreen mode Exit fullscreen mode

Meilleur comportement :

Récupère au maximum 5 extraits de 200 jetons sur le retry policy payments.
Ignore les guides d’onboarding et les changelogs.
Enter fullscreen mode Exit fullscreen mode

Vous payez tous les jetons récupérés, même si le modèle n’en utilise qu’une petite partie.

10. Mesurez le coût par exécution

Sans mesure, vous ne savez pas si vos optimisations fonctionnent.

Si vous appelez directement une API, capturez l’objet usage :

u = response.usage

INPUT_RATE  = 3.00 / 1_000_000
OUTPUT_RATE = 15.00 / 1_000_000
CACHE_READ  = 0.30 / 1_000_000
CACHE_WRITE = 3.75 / 1_000_000

cost = (
    u.input_tokens * INPUT_RATE +
    u.output_tokens * OUTPUT_RATE +
    u.cache_read_input_tokens * CACHE_READ +
    u.cache_creation_input_tokens * CACHE_WRITE
)

print(
    f"coût ≈ ${cost:.4f} "
    f"(in={u.input_tokens}, out={u.output_tokens}, "
    f"cache_read={u.cache_read_input_tokens})"
)
Enter fullscreen mode Exit fullscreen mode

Les tarifs ci-dessus sont illustratifs. Remplacez-les par les tarifs réels de votre fournisseur.

Si vous utilisez uniquement une CLI :

claude /cost
Enter fullscreen mode Exit fullscreen mode

Autres pratiques utiles :

# Utiliser une clé API dédiée par projet ou agent.
# Cela évite de mélanger tous les coûts dans un seul total.

# Envelopper l’appel agent dans un script.
# Journaliser : timestamp, tâche, modèle, coût, jetons entrée/sortie.

# Comparer le coût par type de tâche :
# - refactorisation quotidienne
# - revue de PR
# - génération de tests
# - résumé de diff
Enter fullscreen mode Exit fullscreen mode

Exemple de CSV minimal :

timestamp,task,model,input_tokens,output_tokens,cache_read_tokens,cost_usd
2026-05-20T09:15:00Z,commit-message,haiku,1800,120,0,0.0031
2026-05-20T09:30:00Z,payments-refactor,sonnet,42000,2100,16000,0.1840
Enter fullscreen mode Exit fullscreen mode

Après une semaine, vous verrez rapidement quelles tâches consomment le plus.

Comparaison des tactiques

Tactique Économies typiques Effort
Nommer les fichiers à modifier 30–60% sur l’entrée par exécution Faible
Réduire CLAUDE.md 5–15% par tour Faible
Utiliser /compact ou /clear 40–80% sur longues sessions Faible
Mettre en cache le prompt stable ~90% sur le préfixe caché Moyen
Router les tâches simples 50–80% sur les sous-tâches Moyen
Filtrer la sortie des outils 20–50% sur les tâches intensives en outils Faible
Lire des fenêtres ciblées 70–95% sur gros fichiers Faible
Limiter la récupération RAG 30–60% sur agents documentaires Moyen
Mesurer le coût par exécution 0% direct, mais active toutes les optimisations Faible

Ces chiffres sont indicatifs. Les gains réels dépendent de votre niveau de gaspillage initial.

Checklist d’implémentation

À appliquer dans cet ordre :

[ ] Réduire CLAUDE.md aux instructions strictement nécessaires
[ ] Ajouter un fichier d’ignorance pour dist/, build/, node_modules/, coverage/
[ ] Modifier les prompts pour nommer les fichiers ciblés
[ ] Utiliser /compact ou /clear entre deux tâches
[ ] Rendre les commandes de test silencieuses
[ ] Remplacer git diff par git diff --stat par défaut
[ ] Router commit messages, résumés et changelogs vers un petit modèle
[ ] Activer la mise en cache des prompts si vous utilisez un wrapper API
[ ] Journaliser le coût par tâche pendant une semaine
Enter fullscreen mode Exit fullscreen mode

Conclusion

Les coûts des agents CLI viennent rarement d’une seule mauvaise décision. Ils viennent surtout d’un contexte trop large, de logs trop verbeux, d’un historique jamais nettoyé et de modèles trop puissants pour des tâches simples.

Commencez par les changements à faible effort : prompts ciblés, fichiers mémoire courts, sorties silencieuses et sessions compactées. Ajoutez ensuite la mise en cache et le routage des modèles. Vous réduirez la facture sans réduire la qualité du travail produit.

Top comments (0)