Astuces pour économiser cachées dans le code source de Claude Code : divisez votre facture d’API par deux

Difficulté : moyenne | Durée : 25 minutes | À la clé : maîtriser 7 astuces d’économie au niveau du code source, avec une réduction de 30-60 % sur la facture d’API

Profil des lecteurs visés

Vous utilisez Claude Code en mode intensif, ou comptez l’utiliser profondément : des ingénieurs full-stack, en particulier les développeurs indépendants et les petites équipes qui suivent de près la maîtrise des coûts API. Si votre compréhension de Claude Code s’arrête à l’idée « il suffit de l’installer et ça marche », cet article vous montrera combien de paramètres réglables se cachent derrière.

Dépendances et environnement clés

• Node.js 18+
• Claude Code 2.1.88
• Bases en TypeScript (il suffit de pouvoir lire les définitions de types)
• npm ou pnpm
• Une ANTHROPIC_API_KEY valide

Arborescence complète du projet

# Structure du code source de Claude Code (répertoires liés)
src/
├── cost-tracker.ts              # Suivi du coût : cœur du mécanisme
├── costHook.ts                  # Hook de sortie du coût
├── Tool.ts                      # Fabrique d’abstractions d’outils
├── tools.ts                     # Enregistrement et filtrage des outils
├── tools/
│   ├── BashTool/                # Outil d’exécution Shell
│   │   └── BashTool.tsx
│   │   └── readOnlyValidation.ts # Logique de détection en lecture seule
│   ├── FileReadTool/            # Lecture de fichiers
│   ├── FileEditTool/            # Édition de fichiers
│   └── ...
├── services/
│   ├── compact/                 # Service de compression du contexte
│   │   └── compact.ts
│   └── tools/
│       └── toolOrchestration.ts # Partitionnement de la concurrence des outils
├── skills/
│   └── loadSkillsDir.ts         # Chargement des compétences
├── types/
│   └── permissions.ts           # Définition des modes de permission
├── upstreamproxy/               # Proxy en amont (niveau entreprise)
│   ├── upstreamproxy.ts
│   └── relay.ts
└── utils/
    └── git.ts                   # Outils Git / Worktree

---

I. Comment la facture de Claude Code finit par coûter plus cher

Avant de parler d’économies, clarifions d’abord comment l’argent est dépensé. La facture d’API de Claude Code est principalement pilotée par trois éléments :

1. Le volume total des jetons de contexte

À chaque conversation, Claude Code regroupe l’historique des messages, les résultats des appels d’outils et le contenu des fichiers pour les envoyer à l’API. Plus le contexte est grand, plus le coût unitaire de chaque requête augmente. Dans cost-tracker.ts, la consommation de chaque session est suivie avec précision :

// src/cost-tracker.ts
interface ModelUsage {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;    // Lecture depuis cache (moins cher)
  cacheCreationInputTokens: number; // Création de cache (coût ponctuel)
  webSearchRequests: number;
  costUSD: number;
}

Deux points sont essentiels ici : cacheReadInputTokens coûte environ 10 fois moins que les jetons d’entrée « ordinaires », tandis que cacheCreationInputTokens correspond à un coût unique lors de la création du cache. C’est ce qui détermine directement la stratégie de compression abordée plus loin.

2. La fréquence des appels d’outils

En moyenne, chaque conversation déclenche des dizaines d’appels d’outils. Chaque appel d’outil génère une requête API (tool use en mode streaming). Plus il y a d’outils et plus les appels sont fréquents, plus le contexte gonfle rapidement.

3. Le nombre de workers / agents en concurrence

Lorsque vous lancez un sous-agent via AgentTool, ou lorsque, dans le mode Coordinator, vous répartissez simultanément plusieurs Worker, chaque instance correspond à une session indépendante — et le coût est alors multiplié par deux.

Claude Code intègre cost-tracker.ts pour suivre ces dépenses en temps réel. À la sortie, il persiste les données dans la configuration du projet :

// src/costHook.ts
// Enregistrement et affichage automatique du récapitulatif de facture à la sortie du processus
process.on('exit', () => {
  if (hasConsoleBillingAccess()) {
    console.log(formatTotalCost()); // Affiche la facture avec une décomposition par modèle
  }
  saveCurrentSessionCosts(getFpsMetrics?.());
});

---

II. Astuce d’économie 1 : Compression du contexte avec Compact, -30 à -50 %

Claude Code inclut un service compact qui « compresse » les conversations historiques en résumés, afin de maintenir le contexte dans une taille raisonnable. Les paramètres clés du code source sont clairement visibles :

// src/services/compact/compact.ts
const POST_COMPACT_TOKEN_BUDGET = 50_000;           // Limite du nombre total de jetons après compression
const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000;      // Par fichier : au maximum 5K jetons
const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000;      // Par Skill : au maximum 5K jetons
const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000;      // Toutes les Skills réunies : limite 25K
const POST_COMPACT_MAX_FILES_TO_RESTORE = 5;          // Après compression : au maximum 5 fichiers restaurés

Le processus de compression se déroule en trois étapes : déclenchement → résumé API → ré-attachement des fichiers clés. Il déclenche d’abord les hooks pre_compact, appelle l’API de compression (une requête API distincte), déclenche ensuite les hooks post_compact, puis rattache les fichiers lus récemment.

Conseil pratique : ajuster le seuil de déclenchement permet de contrôler la fréquence de compression, donc de contrôler le coût.

// settings.json — sous le répertoire racine du projet, dans .claude/
{
  "compact": {
    "autoCompactThreshold": 0.85  // Compression déclenchée dès que le contexte atteint 85 %, valeur par défaut
  }
}

Baisser le seuil (par exemple 0.7) entraîne une compression plus fréquente : le coût de chaque compression est plus faible, mais la qualité du résumé peut légèrement baisser. L’augmenter (0.95) fait l’inverse.

---

III. Astuce d’économie 2 : Exploiter intelligemment les outils en lecture seule pour éviter les dépenses inutiles

Chaque outil de Claude Code possède une méthode isReadOnly() : elle détermine si l’outil a des effets secondaires. Le planificateur d’outils se sert de ce drapeau pour décider s’il autorise l’exécution concurrente :

// src/Tool.ts — par défaut, les outils sont prudents (fail-closed)
const TOOL_DEFAULTS = {
  isConcurrencySafe: (_input) => false,  // par défaut : pas sûr, donc pas de concurrence
  isReadOnly: (_input) => false,          // par défaut : a des effets secondaires
  isDestructive: (_input) => false,        // par défaut : non destructif
};

Le point clé : BashTool. Il contient une logique détaillée de classification des commandes :

// src/tools/BashTool/BashTool.tsx
// Liste blanche en lecture seule — ces commandes peuvent s’exécuter en concurrence sans modifier d’état
const BASH_SEARCH_COMMANDS = ['find', 'grep', 'rg', 'ag', 'ack', 'locate', 'which', 'whereis'];
const BASH_READ_COMMANDS   = ['cat', 'head', 'tail', 'less', 'more', 'wc', 'stat', 'file', 'strings', 'jq', 'awk', 'cut', 'sort', 'uniq', 'tr'];
const BASH_LIST_COMMANDS   = ['ls', 'tree', 'du'];
const BASH_SEMANTIC_NEUTRAL_COMMANDS = ['echo', 'printf', 'true', 'false', ':'];

Conseil pratique : lorsque vous exécutez une commande comme ls -la pour interroger la structure d’un répertoire, Claude Code sait que c’est une opération en lecture seule : il peut alors regrouper cette commande avec d’autres opérations en lecture seule et les exécuter en concurrence, ce qui réduit le temps d’attente. En revanche, si vous lancez rm -rf node_modules, l’outil est identifié comme destructif : il doit être traité en série, et vous devez confirmer à chaque fois.

En comprenant cette logique, vous pouvez organiser vos commandes vous-même pour déclencher une meilleure optimisation de concurrence :

# Bonne pratique : des opérations en lecture seule peuvent être combinées dans une seule commande pour réduire le nombre d’appels d’outils
find . -name "*.ts" | head -20 && wc -l src/**/*.ts

# Mauvaise pratique : mélanger des opérations destructives avec des commandes en lecture seule
find . -name "*.log" && rm -rf logs/  # celle-ci sera interceptée en série

---

IV. Astuce d’économie 3 : Le système Skills réduit les prompts répétés, donc économise des Prompt Tokens

Claude Code supporte le système de compétences (Skills). En essence, il s’agit d’un ensemble de fragments de prompts réutilisables. Si, à la racine de votre projet, vous créez un dossier skills/ contenant des fichiers Markdown, Claude Code les charge automatiquement :

your-project/
└── skills/
    └── my-workflow/
        └── SKILL.md   # Format : skill-name/SKILL.md

Les fichiers Skill contiennent un frontmatter de métadonnées :

---
name: my-skill
description: Processus standard de refactorisation de composants React
whenToUse: À utiliser quand il faut refactoriser un composant ou découper un gros composant
paths: ["src/**/*.tsx", "src/**/*.ts"]  # Activé uniquement pour ces chemins
allowedTools: [Read, Edit, Bash]       # Limiter les outils disponibles
arguments: [filePath, scope]
executionContext: inline               # inline ou fork
---
# Corps de la Skill — ici, vous écrivez votre prompt de processus standard de refactorisation

Pourquoi ça fait économiser ? À chaque nouvelle conversation, Claude Code doit insérer dans le system prompt la description de tous les outils, les règles et le contexte. Skills permet de standardiser les workflows courants : vous réduisez ainsi la longueur de prompt à recopier à chaque fois — vous économisez la partie de prompt que vous auriez dû copier-coller manuellement.

Le champ paths est l’élément crucial d’activation conditionnelle : la Skill n’apparaît dans la liste des candidats que lorsqu’un chemin correspondant est détecté. Cela évite la pollution du contexte par des Skills sans rapport :

// src/skills/loadSkillsDir.ts
// Activation conditionnelle selon un matching façon gitignore
activateConditionalSkillsForPaths(filePaths, cwd) {
  // Après accès à des fichiers src/**/*.tsx, les Skills liées à React s’activent
}

---

V. Astuce d’économie 4 : Partitionnement de la concurrence pour réduire les retries, donc économiser la consommation liée aux Rate Limits

Claude Code n’exécute pas tous les appels d’outils en série. Il dispose d’un partitionneur intelligent : il regroupe dans un lot les outils « exécutables en même temps », et traite à part ceux qui doivent attendre.

// src/services/tools/toolOrchestration.ts
// Lecture de la limite de concurrence, par défaut 10
function getMaxToolUseConcurrency() {
  return parseInt(process.env.CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY ?? '10', 10);
}

// Partitionnement : si les appels consécutifs sont en lecture seule, on fusionne ; sinon, on démarre un nouveau lot
function partitionToolCalls(toolUseMessages, toolUseContext): Batch[] {
  return toolUseMessages.reduce((acc, toolUse) => {
    const isConcurrencySafe = tool.isConcurrencySafe(parsedInput.data);
    if (isConcurrencySafe && acc[acc.length-1]?.isConcurrencySafe) {
      acc[acc.length-1].blocks.push(toolUse); // Concurrence sûre : fusion
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] }); // Nouveau lot
    }
    return acc;
  }, []);
}

Conseil pratique : si vos outils MCP supportent la concurrence, déclarez explicitement isConcurrencySafe: true lors de leur définition. S’il n’est pas déclaré, l’outil est traité par défaut en série : lorsqu’un outil en série rencontre une Rate Limit, les retries gaspillent des Token de façon indirecte. Accumulés, cela représente un coût significatif.

// settings.json — déclarer la sécurité de concurrence pour vos outils MCP
{
  "mcpServers": {
    "my-mcp": {
      "command": "npx",
      "args": ["-y", "my-mcp-tool"],
      "isConcurrencySafe": true  // Déclaré : peut s’exécuter en concurrence avec d’autres outils en lecture seule
    }
  }
}

La limite de concurrence peut aussi être augmentée via une variable d’environnement :

# À utiliser si la machine est performante et si vous avez suffisamment d’allocations API
export CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=20

---

VI. Astuce d’économie 5 : Worktree pour isoler au lieu de cloner tout le dépôt, et alléger le contexte de collaboration

Claude Code intègre la prise en charge de Worktree. Git Worktree vous permet d’extraire plusieurs branches dans des répertoires différents au sein du même dépôt, sans cloner plusieurs fois. La fonction findCanonicalGitRoot de Claude Code analyse automatiquement les chemins liés aux worktrees :

// src/utils/git.ts
// Résolution sûre du répertoire racine Worktree
function resolveCanonicalRoot(gitRoot: string): string {
  const gitDirContent = readFileSync(path.join(gitRoot, '.git'), 'utf8');
  // Format du fichier .git : gitdir: /path/to/.git/worktrees/<name>
  const commonDir = extractCommonDir(gitDirContent);
  // Validation de sécurité : worktreeGitDir doit être un sous-répertoire de commonDir/worktrees/
  // Empêche qu’un dépôt malveillant détourne le sandbox via le fichier .git
  validateWorktreeSecurity(worktreeGitDir, commonDir);
  return mainRepoRoot;
}

Principe d’économie : si votre équipe a l’habitude de cloner une fois le dépôt pour chaque branche de fonctionnalité, chaque clone contient son propre répertoire .git (parfois plusieurs Go), et Claude Code l’inclut dans l’analyse du contexte. En mode Worktree, il n’y a qu’un seul dossier .git : la taille scannée du contexte est fortement réduite.

# Créer un Worktree (au lieu de cloner une nouvelle copie)
git worktree add ../feature-sidebar feature/sidebar

# Claude Code reconnaît automatiquement le Worktree et partage le contexte du dépôt principal
# En changeant de worktree, il suffit de cd dedans pour lancer claude
cd ../feature-sidebar && claude

---

VII. Astuce d’économie 6 : Optimiser le mode Permission pour réduire les confirmations

Claude Code dispose d’un système de permissions complet : 5 modes déterminent à quel moment les outils ont besoin de votre confirmation.

// src/types/permissions.ts
type PermissionMode =
  | 'acceptEdits'   // Accepte automatiquement les éditions
  | 'bypassPermissions' // Contourne totalement les vérifications (dangereux mais plus rapide)
  | 'default'       // Demande selon les règles
  | 'dontAsk'       // Ne demande jamais
  | 'plan'          // Mode Plan
  | 'auto';         // L’IA classe automatiquement (quand TRANSCRIPT_CLASSIFIER est activé)

Conseil pratique : pour les répertoires entièrement dignes de confiance (vos propres projets, dont le code est déjà dans git), vous pouvez affiner la configuration dans settings.json :

// ~/.claude/settings.json (niveau utilisateur) ou .claude/settings.json (niveau projet)
{
  "permissions": {
    "defaultMode": "auto",
    "allow": [
      { "toolName": "Bash", "ruleContent": "pnpm*" },
      { "toolName": "Read" },
      { "toolName": "Glob" },
      { "toolName": "Grep" }
    ],
    "deny": [
      { "toolName": "Bash", "ruleContent": "rm -rf /" }
    ],
    "ask": [
      { "toolName": "Bash", "ruleContent": "git push" }
    ]
  }
}

Le mode auto est le compromis entre confort et sécurité : il utilise le classificateur IA pour évaluer si une action est sûre, ce qui évite les fenêtres de confirmation inutiles. À chaque confirmation de moins, vous économisez aussi des Token liés aux changements de contexte.

---

VIII. Astuce d’économie 7 : Cache de proxy en amont côté entreprise pour réduire les appels API répétés

Le module upstreamproxy de Claude Code fournit un routage par proxy pour Claude Code Connect (CCR, version entreprise). Dans le code source, la valeur NO_PROXY_LIST mérite votre attention :

// src/upstreamproxy/upstreamproxy.ts
const NO_PROXY_LIST = [
  'localhost', '127.0.0.1', '::1',
  '169.254.0.0/16', '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16',
  'anthropic.com', 'github.com', '*.github.com',
  // npm / PyPI / Rust registry : tout est dans la liste blanche, pas besoin de passer par le proxy
  'registry.npmjs.org', 'pypi.org', 'files.pythonhosted.org',
  'index.crates.io', 'proxy.golang.org'
];

Conseil pratique : même si vous n’utilisez pas la version entreprise, comprendre cette logique peut vous aider à optimiser votre configuration locale. Si vous êtes sur le réseau de l’entreprise, Claude Code achemine automatiquement le trafic via le proxy d’entreprise. Côté proxy, on peut mettre en place un cache et la réutilisation des Token — c’est un mécanisme de base qui fait économiser les utilisateurs CCR entreprise.

Pour un service MCP auto-hébergé, vous pouvez activer un cache de réponses dans la configuration MCP :

// settings.json
{
  "mcpServers": {
    "local-knowledge": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "MCP_CACHE_TTL": "3600"  // Cache pendant 1 heure, réduit les appels API répétés
      }
    }
  }
}

---

IX. Résolution des problèmes fréquents

Q1 : J’ai modifié une seule ligne, mais la facture reste très élevée ?

La facture élevée n’est pas forcément due aux opérations d’édition : elle peut venir du « gonflement du contexte ». Dans une longue conversation, même si vous ne modifiez qu’une ligne, l’historique avant la compression et les résultats des outils restent toujours dans le contexte. Méthode de vérification : à la fin de la session, regardez la sortie de formatTotalCost() et comparez inputTokens et outputTokens — plus inputTokens est grand, plus le contexte est « trop chargé ».

Q2 : La qualité de réponse baisse nettement après une compression Compact ?

C’est un problème de granularité de compression. Passez autoCompactThreshold de la valeur par défaut 0.85 à 0.95 : vous réduisez la fréquence de compression. En parallèle, assurez-vous que les décisions de conception importantes et les informations de contexte sont bien consignées clairement tôt dans la conversation : ainsi, la qualité du résumé après compression est meilleure.

Q3 : Le mode bypass est-il vraiment sûr ?

Non, mais il est maîtrisable dans un environnement isolé. Si vous devez utiliser bypass, il est recommandé de prévoir une règle de sécurité via permissions.deny en complément :

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "deny": [
      { "toolName": "Bash", "ruleContent": "sudo*" },
      { "toolName": "Bash", "ruleContent": "curl*|wget*" }
    ]
  }
}

Q4 : Comment surveiller ma consommation de Token au quotidien ?

Claude Code affiche automatiquement la facture à la fin de chaque session (si vous avez consoleBillingAccess). La méthode la plus systématique consiste à mettre en place un script de suivi au niveau du projet :

# Ajoutez un hook post-checkout dans le répertoire .git/hooks/ du projet
# Mais la méthode la plus utile est de regarder directement .claude/cost/<session-id>.json

Q5 : Les Skills consomment-elles à chaque fois des Token supplémentaires ?

Oui, mais c’est contrôlable. La consommation de Token des contenus de Skill est intégrée au budget POST_COMPACT_SKILLS_TOKEN_BUDGET (limite 25K). Plus il y a de Skills et plus elles sont détaillées, plus le contexte grossit : les règles d’écriture des Skills doivent donc être les suivantes : correspondance précise, informations minimales nécessaires. Utilisez bien le champ paths pour que la Skill ne se charge uniquement lorsque les fichiers concernés sont consultés.

Q6 : Après avoir utilisé Worktree, Claude Code se comporte de manière anormale ?

Worktree dispose d’un mécanisme de validation de sécurité : si le format du fichier .git n’est pas standard, Claude Code basculera (fallback) dans le répertoire courant. Vérifiez que le contenu du fichier .git correspond au format : gitdir: /absolute/path/to/.git/worktrees/<name>.

---

X. Lectures complémentaires / directions avancées

1. Écrire sa propre Skill pour réduire les répétitions d’ingénierie

Si vous remarquez que vous écrivez encore et encore, dans plusieurs projets, des prompts du type « écrire du code en respectant ce style », transformez-le en une Skill : placez-la dans ~/.claude/skills/ pour un effet global. Une seule écriture, puis des économies répétées.

2. Utiliser MCP pour construire une chaîne d’outils locale et remplacer les appels côté cloud

Les opérations qui consomment beaucoup de Token peuvent souvent être localisées : recherche de code, consultation de documents, opérations de base de données. En encapsulant ces capacités dans des outils MCP locaux, vous réduisez la dépendance à l’API de Claude, et améliorez aussi la vitesse de réponse.

3. Surveiller les logs de compact pour optimiser la stratégie du contexte en continu

Activez le mode verbose pour observer quand Compact se déclenche et quels effets produit la compression. Ajustez continuellement autoCompactThreshold pour trouver l’équilibre adapté à la taille de votre projet.

claude --verbose 2>&1 | grep -i compact

4. Comprendre le classificateur de permissions côté code source

Derrière le mode auto de Claude Code se trouve un classificateur IA (Transcript Classifier). Il évalue le niveau de risque en fonction du contenu de l’action. Si vous souhaitez approfondir, étudiez le type YoloClassifierResult défini dans src/types/permissions.ts.