Vérifier que ça marche : première session

Pour vérifier que Tokenade fonctionne, lancez tokenade healthcheck, utilisez votre agent normalement quelques minutes, puis regardez tokenade hooks tail et tokenade gain. Si les hooks se déclenchent et que le registre des économies grossit, Tokenade fait son travail. Inutile de changer votre façon de rédiger vos demandes.

1. Lancer le bilan de santé

tokenade healthcheck

healthcheck (alias health et doctor) vérifie l'installation et affiche une ligne par contrôle. Les lignes OK passent, les lignes -- sont informatives, et une ligne en échec indique sa correction. Exemple abrégé :

─── tokenade healthcheck ───

OK gain ledger writable at ~/.tokenade/gain.jsonl
OK all agent-config hook paths resolve
OK every hook runs the same tokenade binary
OK installed hook commands match the expected tokenade shape
OK Codex hooks trusted — compaction active (6 hook(s))
OK license active — plan: free · used … tokens saved (this month)
OK agent detected: claude-code

Le code de sortie 0 signifie que tous les contrôles passent (certains peuvent afficher des lignes -- purement informatives) ; 1 signifie qu'au moins un contrôle a échoué. Pour les scripts et la CI, utilisez tokenade healthcheck --json : chaque contrôle porte un id stable (binary, gain_ledger, agent_detect, hook_installed, mcp_entry, wrapped_mcps, semantic_model, stale_mcp_procs).

Les lignes à surveiller en priorité :

license active : la machine est activée. Sinon, lancez tokenade login (détails).
Une ligne par agent branché, par exemple opencode plugin active — tool-result compaction firing ou Codex hooks trusted.

Claude Code : acceptez la demande de confiance du dossier

Claude Code n'exécute aucun hook, ceux de Tokenade compris, dans une session interactive ouverte dans un dossier dont vous n'avez pas accepté la demande de confiance. Depuis la 1.2.1, healthcheck le signale :

-- Claude Code has not trusted /path/to/project — in an interactive session here, it runs none of its hooks (tokenade's included)
accept the trust prompt when Claude Code opens this folder; `claude -p` runs are not affected

Ouvrez le dossier dans Claude Code et acceptez la demande. Voir Claude Code.

2. Voir quel agent Tokenade détecte

tokenade detect

claude-code
coverage: hooks (PostToolUse) — command output is compacted and the saving is measured
mcp config hint: .mcp.json (third-party servers only)

La ligne coverage: décrit le canal qu'utilise ce type d'agent, pas le fait qu'il soit installé sur votre machine. C'est healthcheck qui répond à cette seconde question.

3. Utiliser votre agent

Ouvrez une session comme d'habitude et confiez à l'agent une tâche qui produit de la sortie : lancer les tests, un build, git log, lire un gros fichier, chercher sur le web. Rien ne change de votre côté. Les sorties longues arrivent au modèle repliées, avec une courte bannière qui indique à l'agent comment récupérer les octets complets s'il en a besoin (voir La compaction des sorties et le stash).

4. Regarder les hooks se déclencher

tokenade hooks status # hooks Claude Code installés
tokenade hooks tail # les 20 derniers déclenchements, lus dans ~/.tokenade/debug.log
tokenade hooks tail 50 # les 50 derniers

hooks status liste chaque hook installé avec son événement, puis l'activité récente : combien de fois les hooks se sont déclenchés, et quand pour la dernière fois.

Si la liste d'activité reste vide alors que vous avez utilisé l'agent, les hooks ne tournent pas : voir Dépannage.

5. Consulter vos économies

tokenade gain

gain lit le registre local des économies (~/.tokenade/gain.jsonl) et affiche le nombre d'opérations, les tokens avant et après, et le détail par opération. Variantes utiles :

tokenade gain --history # une ligne par entrée du registre, après le résumé
tokenade gain --by-source # répartition par source : cli / hook / mcp / proxy
tokenade dashboard # vue d'ensemble sur un écran (alias : stats)

Tout ce qu'affichent gain et dashboard est calculé sur votre machine. La façon dont les chiffres sont comptés, et ce qui en est exclu, est expliquée dans Comment les économies sont mesurées.

Toujours rien ?

Relancez tokenade install : il est idempotent et répare les hooks manquants.
Vérifiez que vous n'avez pas lancé l'installation avec sudo (elle écrirait dans /root, et refuse par défaut).
Vérifiez que TOKENADE_HOOK_DISABLED n'est pas défini dans l'environnement de votre agent.
Vérifiez les étapes propres à votre agent : confiance du dossier pour Claude Code, approbation des hooks pour Codex.