Mods Claude Code : verdict sourcé, mesures et checklist du lundi

En bref

• Gardez trois des dix mods : collision-guard, model-router et auto-handoff. Chacun a montré un surcoût mesuré proche de zéro sur une tâche de lecture en headless, et chacun résout un problème que vous pouvez nommer.
• Supprimez next-steps. Il fork la session après chaque réponse éligible et a coûté +250 tokens de sortie et +2850 ms par tour dans notre run, y compris sur les surfaces qui n'affichent jamais ses suggestions.
• Supprimez cache-keeper (+1589 ms, pings payants au modèle), recording-mode (il masque l'affichage, pas l'historique stocké) et session-bookmarks (un marque-page qui peut appeler le modèle, lancer des processus et écrire des fichiers).
• Supprimez goal-meter, repo-heatmap et flight-recorder, sauf si vous voulez le visuel. Ils ne coûtent presque rien et n'ont montré aucun bénéfice mesuré.
• Tout mod de garde échoue en mode ouvert par défaut. Sans gestionnaire .catch, une garde qui lève une erreur est ignorée et la commande s'exécute.
• Les mods ne sont pas isolés dans un sandbox. Lisez la sortie de claude plugin validate avant d'en installer un.

Ce que disent les mesures

Buzz et échelle. Le tweet de lancement affichait 4,138,918 vues, 20,021 likes et 13,440 signets à notre capture du 2026-10-03 s11. Le catalogue communautaire liste 1018 mods dans 873 dépôts candidats, scannés le 2026-10-03 sur Claude Code 2.1.288 s9.

Un mod est une fonction qui s'accroche à un événement. Elle peut s'exécuter avant, après, à la place de l'événement, ou l'enrober s1. Les mods demandent Claude Code v2.1.287 ou plus et sont activés par défaut s2.

La sécurité d'abord. Formulation d'Anthropic : "Mods run with the same access to your machine as Claude Code itself. They aren't sandboxed" s1. Un processus lancé par un mod s'exécute hors du sandbox même quand vous l'activez s2. Avec Read(.env) refusé, un mod peut quand même lire ce fichier avec $.fs.read ou lancer un programme qui le fait s6. Dans le scan du catalogue, 409 mods lancent des processus hôtes, 167 écrivent des fichiers, 150 accèdent au réseau et 28 échouent à la validation sur cette version s9.

Portée contre promesse. Dans notre audit statique, session-bookmarks appelle $.model.complete, $.process.run et $.fs.write, la plus grande portée du lot pour une fonction de marque-page. next-steps avait la plus petite empreinte : pas de fs, pas de process, pas d'env. claude plugin validate affiche les lignes calls: et env reads: utilisées pour cet audit s6.

Le mod phare a un coût par tour. next-steps fork la session avec $.model.fork sur turn.complete, et le README dit que le fork "costs about one short reply" s10. Les suggestions ne s'affichent que dans le terminal ; les autres surfaces n'affichent rien s10. Le fork n'a aucune option de désactivation. Dans notre run headless, il a ajouté +250 tokens de sortie et +2850 ms, le fork se retrouvant dans l'usage de la session alors que rien n'était affiché s10.

Plafonds documentés. Le temps d'exécution d'un hook est plafonné à 10 secondes par événement, les lectures et écritures $.fs à 4 MiB par fichier, et $.store à 4 MiB de JSON au total s3.

Les gardes échouent en mode ouvert. La doc dit qu'un hook sans gestionnaire .catch qui lève une erreur, dépasse le délai ou renvoie un mauvais format est ignoré, et le gestionnaire suivant s'exécute à sa place s7. Nous l'avons reproduit : une garde Bash qui lève une erreur, sans .catch, a laissé touch ./marker-failopen.txt créer le fichier. La même garde avec un .catch renvoyant {deny} n'a créé aucun fichier. Un retour terrain a décrit une garde activée et en marche mais qui ne faisait rien, alors que plugin list affichait toujours "enabled" s8.

Un bug ouvert sur 2.1.288 : un deny renvoyé après await next(e) n'arrête pas l'outil, et le fichier a été écrit 3 fois sur 3 alors que le modèle apprenait que l'écriture avait échoué s5.

Mods contre hooks de settings. Un hook de settings lance un processus par appel. Nous avons mesuré le lancement à 2.2 ms pour un binaire true, 8.3 ms pour bash -c 'exit 0', 26.1 ms pour python3 -c 'pass' et 43.1 ms pour node -e ''. Sur 5,993 appels d'outils par semaine, le hook node coûte 258 s. Un mod en processus ne paie rien de tout cela. La doc recommande un hook de settings quand vous avez déjà un script qui bloque, autorise ou journalise un événement s2. Un retour de migration est passé de 27 hooks shell à 5 mods s8.

Le masquage n'est que visuel. recording-mode réécrit ce que ui.render dessine. ~/.claude/history.jsonl garde le prompt tel que tapé, et un testeur a retrouvé sa chaîne canari 7 fois dans les entrées queue-operation du transcript s5.

Là où les mods ne tournent pas. Le mode headless claude -p et l'Agent SDK exécutent les hooks mais n'affichent rien ; une session Desktop WSL n'exécute ni l'un ni l'autre s2.

Confiance dans le catalogue. Un testeur a publié un mod dont le bouton lançait un programme avec $.process.run et écrivait un fichier dans son dossier personnel. Il s'est installé comme n'importe quel mod, sans avertissement s5. C'était une preuve de concept publiée par lui-même, pas une attaque observée dans la nature.

Mesures

Corpus : les 7 derniers jours d'une vraie configuration, 85 sessions, 4 projets, 882 prompts utilisateur, 11,010 tours d'assistant, 5,993 appels d'outils. Benchmark exécuté sur Claude Code 2.1.288 (macOS).

Les lignes marquées * sont probablement de la variance de réponse. recording-mode était désactivé pendant le run et n'injecte rien quand il est désactivé.

Protocole pour le rejouer :

1. Installez un mod à la fois et vérifiez qu'il passe claude plugin validate.
2. Lancez la même tâche en lecture seule en headless avec claude -p sur haiku, 3 répétitions par config, et prenez la médiane de la durée et des tokens de sortie.
3. Ne citez que les écarts de durée et de tokens de sortie. Le coût en USD varie avec l'ordre du cache entre les configs, ignorez-le.
4. Pour le coût de lancement, chronométrez 30 lancements du corps de chaque hook et prenez la médiane, puis multipliez par votre nombre hebdomadaire d'appels d'outils.

À faire lundi

• Lancez claude plugin validate sur chaque mod installé et lisez les lignes calls: et env reads:.
• Désactivez tout mod dont la portée (process, écriture fs, appel au modèle) dépasse sa tâche.
• Désactivez next-steps si vous travaillez surtout en headless, dans le panneau VS Code ou avec le SDK, où ses suggestions ne s'affichent jamais.
• Ajoutez un gestionnaire .catch qui renvoie { deny: ... } à chaque mod de garde sur lequel vous comptez.
• Prouvez que chaque garde échoue en mode fermé : faites-la lever une erreur, lancez une commande qui crée un fichier témoin, et vérifiez que le fichier n'apparaît pas.
• Ne comptez pas sur un mod de masquage pour garder les secrets hors de ~/.claude/history.jsonl ou du transcript. Vérifiez les deux sur le disque.
• Remplacez les hooks shell par appel qui lancent node ou python par un mod en processus, ou par un binaire compilé, si le coût de lancement s'accumule sur vos appels d'outils hebdomadaires.
• Apprenez les interrupteurs : désactiver un mod dans /plugin, --safe-mode pour une session, "disableAllHooks": true dans ~/.claude/settings.json pour partout.

Aller plus loin

• Construire le vôtre : un tutoriel pratique d'un mod d'environ 80 lignes, avec les pièges qui comptent (l'état au niveau du module est réinitialisé au rechargement à chaud, gardez donc les données dans $.state) s4.
• Choisir entre mod, hook, skill ou settings à partir de votre propre historique : un praticien suggère de fouiller d'abord vos logs de session pour trouver les problèmes récurrents s12.
• Lire la liste complète des événements et des limites avant d'écrire une garde s3.
• La gestion à l'échelle d'une organisation est hors sujet ici. Le seul point pour un développeur solo : sec-default se charge quand la machine a des settings managés ou que vous êtes connecté avec un plan Team ou Enterprise, et il n'ajoute aucune autre restriction s6.
• L'origine du design, dont un bug d'isolation de worktree corrigé en 2.1.288 et le fonctionnement interne du runtime, se trouve dans le fil ouvert s5.
• Des mods d'exemple d'Anthropic (token-weather, blast-radius, replay-theater) sont listés comme partagés sans support s2.

Sources

• Customize Claude Code with mods, Anthropic blog. Pourquoi le lire : la définition officielle et l'avertissement sur l'absence de sandbox, dans les mots d'Anthropic.
• Mods overview, docs. Pourquoi le lire : la comparaison mods contre hooks, la matrice des surfaces et les interrupteurs.
• Mods reference, docs. Pourquoi le lire : la liste complète des événements et les limites documentées.
• Getting started with Claude Code mods, claude.dev (Addy Osmani). Pourquoi le lire : le meilleur tutoriel pratique, avec des pièges qu'aucune autre source ne couvre.
• Mods issue #91870, GitHub. Pourquoi le lire : retours terrain sur l'isolation, le mode fermé et les fuites d'historique.
• Manage mods for your organization, docs. Pourquoi le lire : l'audit validate et les limites de chaque contrôle de sécurité.
• React to events with a mod, docs. Pourquoi le lire : l'ordre de la chaîne de middleware et le mode ouvert par défaut.
• The Guard I Installed Was Enabled, Running, and Doing Nothing, blog. Pourquoi le lire : le seul retour de migration, de 27 hooks shell à 5 mods.
• awesome-claude-code-mods, GitHub. Pourquoi le lire : la taille de l'écosystème et une méthode d'audit prête à l'emploi.
• next-steps plugin source, GitHub. Pourquoi le lire : la vraie mécanique du mod phare, y compris le fork à chaque tour.
• ClaudeDevs release tweet, X. Pourquoi le lire : l'annonce de lancement et sa portée.
• Avid's session-log mining workflow, X. Pourquoi le lire : une méthode pour décider quoi construire ou installer avant d'installer quoi que ce soit.

FAQ

Les mods sont-ils isolés dans un sandbox ?

Non. Anthropic dit que les mods s'exécutent avec le même accès à votre machine que Claude Code lui-même s1. Les programmes lancés par un mod s'exécutent aussi hors du sandbox s2.

Que se passe-t-il si ma garde plante ?

Sans gestionnaire .catch, elle est ignorée et la commande s'exécute s7. Ajoutez un .catch qui renvoie { deny: ... } pour qu'elle échoue en mode fermé.

Un mod coûte-t-il des tokens ?

Seulement s'il appelle le modèle. Sur les dix que nous avons lancés, next-steps et cache-keeper ont montré un coût mesurable ; les autres n'ont montré aucun surcoût robuste dans notre run.

Comment désactiver rapidement les mods ?

Désactivez-en un dans /plugin, démarrez une session avec --safe-mode, ou mettez "disableAllHooks": true dans ~/.claude/settings.json s2. Aucun de ces moyens n'arrête les mods intégrés.

Puis-je vérifier ce que fait un mod avant de l'installer ?

Oui. claude plugin validate liste les hooks, les appels d'API et les variables d'environnement qu'il lit s6.