Présentation

Tokendoctor est un plugin pour Claude Code qui analyse les paramètres d’une session, identifie les réglages coûteux et propose un diff à appliquer. Le développeur indique une réduction maximale de 38 % du nombre de tokens consommés, ce qui se traduit par une économie directe sur les facturations liées à l’usage du modèle.

Fonctionnement et architecture

Le plugin s’exécute entièrement sur la machine de l’utilisateur ; il ne possède aucun serveur MCP et n’envoie aucun appel de modèle pour les commandes d’audit. Les hooks sont intégrés au module ToolSearch et ne sont listés que lorsqu’une commande /tokendoctor:optimize les charge. Un hook asynchrone tokendoctor-record démarre en arrière‑plan au lancement d’une session, consigne les totaux journaliers dans ~/.claude/tokendoctor/history.jsonl et n’ajoute aucun token supplémentaire.

Les données collectées comprennent le nombre de tokens par jour, par modèle (opus, sonnet, haiku ou identifiant claude‑…), par effort, par fil principal et par sous‑agent, ainsi que la taille du contexte et le projet associé. Ces métriques sont exposées via la commande /tokendoctor:dashboard, qui génère un tableau détaillé sans coût supplémentaire, car la réponse provient du plugin lui‑même.

tokendoctor-audit [--project ] [--json]

tokendoctor-sessions [--days ] [--by day|week] [--json]

tokendoctor-set --list ||--unset [--scope user|project|local]

Le cœur de l’optimisation repose sur 38 vérifications de paramètres. Chaque vérification est classée : erreur (paramètre incorrect ou ignoré), avertissement (potentiel coût monétaire) ou information (à examiner). Les règles dépendant d’une version précise de Claude Code sont ignorées sur les versions antérieures, garantissant la compatibilité.

Analyse des économies et limites

Le développeur estime un coût permanent d’environ 235 tokens pour le fonctionnement du plugin, répartis sur les cinq outils fournis. Cette charge est négligeable comparée aux économies potentielles lorsqu’une session dépasse les 400 k tokens. Cependant, le gain dépend fortement du modèle utilisé, du niveau d’effort (nombre d’appels) et de la taille du contexte. Si une session reste en dessous de ce seuil, le plugin peut même coûter plus que ce qu’il économise, car le résumé final peut dépasser la fenêtre économisée.

Le plugin ne peut pas modifier les agents intégrés de Claude Code ni les clés critiques du fichier settings.json (par ex. autoCompactWindow, env, permissions). Il se contente de copier des modèles de scripts (templates/statusline.sh) et de trois sous‑agents génériques (Explore, test‑runner, docs‑lookup) dans le répertoire utilisateur (~/.claude/agents/) avant d’appliquer les changements. Cette approche garantit la sécurité des paramètres mais limite l’étendue des optimisations possibles.

Enfin, la fiabilité de l’audit repose sur la lecture en temps réel de la documentation officielle (code.claude.com) au format Markdown. Cette méthode évite les listes figées dans le plugin, mais introduit une dépendance à la disponibilité du site et à la synchronisation des versions de Claude Code.

Installation et utilisation

L’installation s’effectue via le marketplace Claude : claude plugin marketplace add localixai/tokendoctor puis claude plugin install tokendoctor@tokendoctor. Une mise à jour se réalise avec claude plugin marketplace update tokendoctor. Pour les utilisateurs qui préfèrent le code source, il suffit de cloner le dépôt et de lancer Claude avec l’option --plugin-dir /chemin/vers/tokendoctor. Toutes les commandes du plugin sont accessibles depuis l’interface Claude Code en préfixant /tokendoctor, ce qui assure une utilisation sans frais additionnels.