TL;DR
- Un mod est un plugin dont le code tourne à l’intérieur de Claude Code. Il s’abonne à des événements (un prompt envoyé, un appel d’outil, un morceau d’interface dessiné) et peut les observer, les réécrire ou y répondre à la place du comportement normal.
- Ce que ça ouvre : un pare-feu de permissions écrit en code, des secrets masqués avant lecture, un outil capricieux rejoué. Aussi : un panneau d’état à côté du chat, un prompt enrichi par le contexte métier.
- Pour aller plus loin : un mod voit toute la trajectoire d’une session. Il devient l’endroit où l’on mesure le harnais, et où on le fait évoluer avec une règle écrite à l’avance.
- Le prix : un mod n’est pas sandboxé. Il s’exécute avec vos droits. On le traite comme une dépendance de production.
Un mod, en une image
Jusqu’ici, on encadrait Claude Code de l’extérieur : des règles de permission, des hooks shell déclarés dans settings.json, des serveurs MCP qui ajoutent des outils. Le harnais lui-même, la boucle entre votre prompt, le modèle et les outils, restait fermé.
Un mod l’ouvre. C’est un plugin qui contient un module JavaScript ou TypeScript, chargé dans le processus de Claude Code. Le module enregistre des gestionnaires sur des événements nommés. prompt.submit : vous envoyez un message. tool.call : Claude s’apprête à utiliser un outil. tool.check : une permission se décide. ui.render : l’interface se dessine. Chaque gestionnaire reçoit l’événement et une fonction next : il peut laisser passer, passer une version modifiée, ou répondre lui-même.
L’image la plus juste : un poste de contrôle programmable sur chaque route qui relie vous, le modèle et vos outils.
Côté fichiers, un mod tient en trois pièces : le manifeste .claude-plugin/plugin.json, un hooks/hooks.json qui désigne le module, et le module lui-même, qui exporte une fonction register. Les mods sont actifs par défaut dans le terminal à partir de Claude Code v2.1.287. Exemple minimal, un garde sur le shell :
export function register(on) {
on('tool.call', { tool: 'Bash' }, ($, e, next) =>
/git push --force|rm -rf \//.test(e.command)
? { deny: "Commande destructive refusée par le mod de l'équipe." }
: next(e),
)
}
Le modèle reçoit le refus comme un résultat d’erreur, et il adapte son plan.
Cinq usages concrets
1. Un pare-feu de permissions écrit en code. Les règles allow / ask / deny sont des listes. Un gestionnaire tool.check est une fonction. Il peut autoriser toute lecture dans le dépôt courant, demander confirmation dès qu’une commande vise la production, refuser toute écriture dans un .env. La décision se prend avec le contexte complet de l’appel, et pas seulement avec un motif.
2. Masquer les secrets avant que Claude les lise. Anthropic le cite explicitement : un mod peut « caviarder les secrets de la sortie d’un outil avant que Claude la lise ». Le gestionnaire laisse l’outil tourner (await next(e)), puis remplace dans le résultat tout ce qui ressemble à une clé d’API ou à un jeton. Le modèle ne voit que la version masquée. C’est celle-là qui entre dans le contexte.
3. Rejouer un outil capricieux. Un serveur MCP qui expire une fois sur vingt fait perdre un tour entier au modèle, qui diagnostique une panne qui n’en est pas une. Le mod lit le résultat. S’il s’agit d’une erreur transitoire connue, il relance l’appel une fois avant de rendre la main. Une seule fois, et en le journalisant : un rejeu sans limite ne fait que cacher une vraie panne.
4. Un panneau d’état à côté du chat. Un mod peut ouvrir un panneau à côté de la conversation, ou une ligne au-dessus du prompt. On y met ce qu’on veut suivre pendant que Claude travaille : le remplissage du contexte, les fichiers touchés, les appels refusés, le budget consommé.
5. Réécrire le prompt selon le contexte métier. Avec prompt.submit, le mod réécrit le message avant qu’il parte. Avec prompt.compose, il ajoute une section au prompt système. Exemple : dans le dépôt d’un client en maintenance industrielle, injecter le glossaire maison (GMAO, MTBF, codes défaut) et les conventions de l’équipe, sans les recoller à chaque conversation.
Aller au-delà : un harnais qui se mesure
Le point le plus intéressant n’est pas l’un de ces cinq usages. C’est qu’un mod voit toute la trajectoire : chaque prompt, chaque appel d’outil, chaque refus, chaque rejeu. Le harnais devient un système qu’on mesure.
Notre pratique chez BCUB3 tient en trois règles :
- Un mod par domaine métier. Le dépôt d’un ERP, celui d’un site, celui d’une chaîne de données n’ont ni les mêmes risques ni le même vocabulaire. Un mod ciblé se relit en dix minutes.
- Un journal des trajectoires. Le mod écrit, pour chaque tâche, ce qui s’est passé : nombre de tours, outils appelés, refus, rejeux, durée. Sans ce journal, toute « amélioration » du prompt ou des règles reste une impression.
- Une règle garder / revenir écrite avant le changement. Avant de modifier une règle ou une section de prompt, on écrit l’indicateur suivi et le seuil. Par exemple : « si le nombre de tours par tâche ne baisse pas sur les cinquante prochaines sessions, on revient à la version précédente ». Le mod est versionné dans git, donc revenir en arrière coûte un
git revert.
Côté performance, nous avons mesuré un même contrôle : environ 2 ms dans un mod, 90 à 190 ms dans un hook shell relancé à chaque appel. À plusieurs centaines d’appels par session, l’écart se sent.
Risques et hygiène
La documentation d’Anthropic est nette : un mod s’exécute avec vos droits. Il peut lire et écrire vos fichiers, lancer des programmes et appeler le réseau. Vos variables d’environnement lui sont lisibles, clés d’API comprises. Chaque prompt et chaque appel d’outil passent sous ses yeux. Un mod peut même approuver un appel avant qu’on vous le demande, et il consomme votre quota de modèle. Il n’est pas sandboxé : si vous activez le sandbox de Claude Code, il isole les commandes Bash de Claude, pas les processus qu’un mod démarre.
Les règles d’hygiène découlent de là :
- Provenance. N’installer que des mods d’auteurs et de marketplaces de confiance. En entreprise, une marketplace interne et, côté admin, les réglages gérés qui limitent les mods chargés.
- Revue avant installation.
claude plugin validate ./le-modliste, sans l’exécuter, les événements que le mod écoute (hooks:) et ce qu’il demande à Claude Code (calls:). - Revue de code comme pour n’importe quelle dépendance : versions figées, changements relus, pas de mise à jour automatique sur un poste qui touche à la production.
- Un interrupteur connu de tous.
claude --safe-modelance une session sans mods installés."disableAllHooks": trueles coupe partout.
Par où commencer
- Vérifier et lire.
claude --versiondoit afficher 2.1.287 ou plus. Clonez un des mods d’exemple d’Anthropic (dépôtanthropics/claude-code-playground, par exempleblast-radius, qui retient une commande risquée et montre ce qu’elle changerait), passez-le àclaude plugin validate, lisez son code. - Écrire un mod qui observe seulement. Demandez à Claude Code de vous l’écrire : il sait le faire et le recharger à chaud dans la session. Commencez par compter et journaliser, sans rien bloquer.
- Ajouter un seul garde-fou, et le mesurer. Un refus sur une commande destructive ou sur un fichier sensible. Deux semaines de journal, la règle garder / revenir écrite avant. Puis le suivant.
On peut en parler
BCUB3 intègre des agents IA, du RAG et des LLM dans les outils des PME et ETI industrielles, harnais compris : quels garde-fous, quelle mesure, quel domaine d’abord. Pas de licence à vendre.
Prendre 30 minutes pour en parler →
Sources : la documentation Claude Code, « Mods overview », et l’annonce d’Anthropic.