tokenade
GitHubenfr
Installer

Dépannage

Mis à jour le

TL;DR — Commencez par tokenade healthcheck : chaque ligne a un identifiant stable et une correction, et la commande sort avec le code 1 si une vérification échoue. tokenade hooks status et tokenade hooks tail montrent ce que les hooks ont fait. La plupart des pannes se règlent avec tokenade install ou tokenade ensure-hooks.

Quand les économies restent à zéro ou que votre agent cite un message de Tokenade, commencez par une seule commande :

tokenade healthcheck

Elle vérifie le binaire, les hooks de chaque agent et les magasins locaux, affiche une ligne par vérification, et sort avec le code 1 si l'une d'elles échoue. tokenade health et tokenade doctor sont des alias. Ajoutez --json pour obtenir un objet structuré (version, failures, ok, checks[]) où chaque vérification porte un id stable, pratique dans un script :

tokenade healthcheck --json | jq '.checks[] | select(.id == "hook_installed")'

Les lignes OK sont passées, -- sont informatives, !! sont des échecs.

Lignes du diagnostic et corrections

idCe que signale un échec ou un avertissementCorrection
binaryIndique quel tokenade s'exécute, et prévient si plusieurs copies sont dans votre PATH.Supprimez la copie inutile, ou placez la bonne en premier dans le PATH.
gain_ledger~/.tokenade/gain.jsonl n'est pas inscriptible : aucune économie n'est enregistrée.Corrigez le propriétaire ou les droits de ~/.tokenade/ (souvent créé par un lancement sous sudo).
agent_detectAucun agent IA détecté dans l'arborescence courante (information).Lancez-la depuis un projet où vous utilisez votre agent.
hook_installedClaude Code n'a pas les hooks de Tokenade : jamais installés, ou retirés par un autre outil ou une mise à jour de l'agent.tokenade ensure-hooks si Tokenade était installé, sinon tokenade install.
pretool_readLes hooks de Tokenade dans les réglages de Claude Code ne couvrent pas les lectures de fichiers : l'optimisation des lectures ne se déclenche jamais.tokenade ensure-hooks.
hook-integrityDes commandes de hook Tokenade ne correspondent plus à la forme installée. Une dérive peut signaler une altération.tokenade install.
binary_pathsDes configurations d'agent pointent vers un binaire tokenade qui n'existe plus : ces hooks sont morts sans bruit.tokenade install pour réécrire les chemins.
hook_binaries_agreeVos hooks exécutent un autre tokenade que celui de votre PATH.tokenade install depuis la copie à garder.
codex-hook-trustCodex n'a pas approuvé les hooks de Tokenade, qui ne font donc rien.Voir Hooks Codex non approuvés.
claude-workspace-trustClaude Code n'a pas approuvé le dossier courant : en session interactive, il n'y exécute aucun hook.Acceptez la demande de confiance quand Claude Code ouvre le dossier. Les lancements claude -p ne sont pas concernés.
mcp_entryUne ancienne entrée tokenade traîne dans les mcpServers d'un agent ; elle lance la commande retirée tokenade mcp.tokenade install la supprime.
wrapped_mcpsDes serveurs MCP tiers enveloppés par mcp-wrap pointent vers un ancien chemin de Tokenade.tokenade unwrap-mcps && tokenade install.
stale_mcp_procsDes processus MCP Tokenade tournent encore sur un ancien binaire.Redémarrez votre agent.
semantic_modelLe modèle d'embeddings n'est pas encore téléchargé (information). Il l'est une fois, au premier semantic ou --prompt.Rien à faire.
posix-shellWindows uniquement : ni sh ni bash trouvé, la compaction des commandes shell est coupée.Installez Git for Windows.
web_transportcurl introuvable ; la récupération web marche, en mode dégradé (information).Installez curl.
filter-syntaxDes fichiers de compacteur sont illisibles et ne s'appliquent jamais.Corrigez ou supprimez le fichier indiqué dans le détail.
project-filtersDes compacteurs de projet attendent votre approbation (information).tokenade trust-filters (inspectez d'abord avec --list).
ledger-integrityDes lignes du registre d'économies violent les règles de comptabilité.tokenade audit-gains donne le détail.
disk-footprintPlace occupée par Tokenade, plus gros éléments en tête.tokenade evict-stale purge les entrées de cache périmées.

Les autres lignes informatives (activité des plugins par agent, leviers jamais déclenchés, nombre de contournements) décrivent l'usage de Tokenade et n'appellent pas de correction.

Voir ce qu'ont fait les hooks

tokenade hooks status # chaque hook Claude Code installé
tokenade hooks tail 50 # les 50 derniers événements de hook de ~/.tokenade/debug.log (20 par défaut)

Les deux acceptent --json. Le journal de débogage est un fichier JSON à une ligne par événement, avec ts, component, event et details. Il est actif par défaut après tokenade install (sauf installation avec --no-debug-log) et tourne à 16 Mio. Pour l'écrire ailleurs, posez TOKENADE_DEBUG_LOG=<path> là où l'agent démarre.

Les hooks ne bloquent jamais votre agent : si Tokenade échoue, l'appel d'outil passe tel quel. Pour mettre Tokenade hors de cause pendant un débogage, posez TOKENADE_HOOK_DISABLED=1, ou préfixez une commande par tokenade raw.

Votre agent dit que Tokenade est en pause

Tokenade 2.0 ne se met jamais en pause : il n'y a ni licence ni quota à vérifier. Si votre agent relaie un avis qui commence par tokenade — et parle de compte, de licence, de facturation ou de tokenade.net injoignable, cette machine tourne encore sur une version 1.x. Mettez-la à jour :

npm i -g @tokenade/cli@latest

Voir Installer Tokenade, section « Passer de la 1.x à la 2.0 ».

Hooks Codex non approuvés

Codex n'exécute pas un hook tant que vous ne l'avez pas approuvé. tokenade install approuve les hooks qu'il écrit en inscrivant leur approbation dans ~/.codex/config.toml. Si la ligne codex-hook-trust échoue, réappliquez-la :

tokenade codex-trust

La commande affiche trusted N Codex hook(s) in ~/.codex/config.toml. Vous pouvez aussi les approuver depuis Codex avec /hooks. Tant que les hooks ne tournent pas, le proxy LLM de Tokenade couvre Codex pour le repli des sorties, le masquage des identifiants et la note de style ; dès que les hooks tournent, rien n'est fait deux fois. Voir Codex.

Claude Code ignore les hooks dans un dossier

Claude Code n'exécute aucun hook dans une session interactive ouverte dans un dossier dont la demande de confiance n'a pas été acceptée. Les hooks de Tokenade n'y échappent pas : rien n'y est compacté. La ligne claude-workspace-trust le signale ; acceptez la demande quand Claude Code ouvre le dossier.

tokenade install refuse sous sudo

✗ running under sudo: this would install into /root, not your own HOME —
your AI agent would never see the hooks (and everything would LOOK fine).
Re-run WITHOUT sudo: tokenade install
(intentional root install: TOKENADE_ALLOW_ROOT=1 tokenade install)

Lancez-la avec votre propre utilisateur. Si vous utilisez vraiment votre agent en root, posez TOKENADE_ALLOW_ROOT=1.

Les hooks ont disparu après une mise à jour de l'agent

Certaines mises à jour d'agent ou d'autres outils réécrivent le fichier de réglages. Tokenade vérifie et répare ses hooks tout seul de temps en temps. Pour réparer tout de suite :

tokenade ensure-hooks --force

Signaler un bug

Si rien de tout cela n'aide, ouvrez un ticket sur GitHub. Indiquez votre tokenade --version, la sortie de tokenade healthcheck et les lignes utiles de tokenade hooks tail ; relisez-les pour retirer toute donnée privée avant de les coller.

Pour comprendre le comportement des hooks de Claude Code, lisez Les hooks de Claude Code.

Voir aussi