← Blog

Claude Code mods : quand le harnais devient programmable

Un mod, ce sont quelques lignes de TypeScript qui s'insèrent entre vous, Claude et ses outils. Ce que ça change, cinq cas concrets, les risques, et par où commencer.

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.

Le cycle d'un tour dans Claude Code avec un mod Le prompt passe par le mod avant d'atteindre le modèle. La demande d'outil du modèle passe par le mod avant d'atteindre l'outil. Le résultat de l'outil repasse par le mod avant de revenir au modèle. Le mod peut aussi dessiner dans l'interface. Vousle prompt Modèleraisonne, demande Outilfichier, shell, MCP modprompt.submit modtool.check · tool.call modrésultat caviardé mod · ui.render un panneau, une ligne d'état dans l'interface
Un tour de Claude Code avec un mod : à chaque passage, le mod observe, réécrit ou répond à la place.

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-mod liste, 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-mode lance une session sans mods installés. "disableAllHooks": true les coupe partout.

Par où commencer

  1. Vérifier et lire. claude --version doit afficher 2.1.287 ou plus. Clonez un des mods d’exemple d’Anthropic (dépôt anthropics/claude-code-playground, par exemple blast-radius, qui retient une commande risquée et montre ce qu’elle changerait), passez-le à claude plugin validate, lisez son code.
  2. É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.
  3. 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.

Cet article vous a été utile ?

BCUB3 est une petite structure. Si vous pensez à un collègue ou un partenaire qui pourrait en tirer quelque chose, la meilleure manière de nous aider est de partager le lien. Et si vous avez un cas concret à discuter, parlons-en directement.

Prendre un RDV de cadrage