Les mods de Claude Code : un petit fichier qui réécrit ce que vous voyez

Imaginez que vous tournez une vidéo de cuisine chez vous. Derrière vous, la porte du frigo est couverte de papiers : une facture d’électricité, une fiche de paie, le calendrier de l’école avec le prénom de votre enfant. Vous n’avez pas envie de tout décrocher ; vous voudriez juste que la caméra floute ces papiers pendant qu’elle filme. La cuisine reste telle quelle. Seule l’image change.

C’est le problème que j’ai eu en enregistrant ma première démo de Claude Code. Le terminal, c’est la cuisine : des valeurs de .env défilent, une adresse e-mail apparaît dans le résultat d’un outil, un montant s’affiche dans un fichier. Les mods de Claude Code, c’est la caméra qui floute.

En une phrase : un mod est un petit fichier JavaScript ou TypeScript qui tourne dans votre session Claude Code, où il peut observer ce qui se passe, répondre à la place de Claude Code, ou réécrire ce qui s’affiche à l’écran.

Ce qu’est un mod, concrètement

Réglages, permissions, commandes slash, skills, ligne de statut : Claude Code se règle déjà beaucoup. Les mods vont plus loin. D’après le guide officiel, un mod est un plugin Claude Code dont le comportement vit dans un module JavaScript ou TypeScript. Le dossier est un plugin normal avec un manifeste .claude-plugin/plugin.json, le fichier hooks/hooks.json désigne un seul module sous modules, et ce module exporte register(on, options).

Dans register, chaque appel à on(event, matcher?, hook) ajoute un hook. Les événements couvrent les appels d’outils, le prompt envoyé, le début et la fin des tours, l’ouverture et la fermeture de session, les commandes slash, et ui.render, déclenché pour chaque morceau de l’interface au moment où il est dessiné. Le module tourne dans son propre bac à sable, sans DOM ni Node : tout ce qu’il fait à l’extérieur passe par $, l’API des mods.

Différence avec les hooks des réglages : ces derniers lancent une commande shell à chaque événement et échangent du JSON par stdin et stdout. Un mod, lui, est chargé une fois et reste dans la session : il garde un état, dessine une interface qui se met à jour au fil des événements, ouvre un panneau, lance un processus, enregistre une commande slash ou un outil que le modèle peut appeler. Anthropic s’en sert d’ailleurs : le support d’AGENTS.md et le panneau /diff sont des mods, publics dans anthropics/claude-code, sous mods/.

Il faut Claude Code 2.1.287 ou plus récent. Les mods y sont activés par défaut, mais l’API peut changer d’une version à l’autre : à chaque chargement, Claude Code écrit les déclarations de types de votre version dans le dossier .claude-plugin/types/ du mod, et ce sont elles qui font foi.

Un maillon dans une chaîne

Tous les hooks ont la même forme. Voici l’exemple du guide, tel quel :

on("tool.call", { tool: "Bash" }, async ($, e, next) => {
  // $    the mods API: ui, session, state, store, fs, process, clock, http, tool, command, model, ...
  // e    this event's input, as plain data
  // next passes e to the other plugins and then to Claude Code's own behavior
  return next(e);
});

Les hooks forment une chaîne, comme des middlewares : votre hook s’exécute, next(e) passe l’événement au plugin suivant, et au bout, Claude Code fait ce qu’il aurait fait de toute façon. Un hook a donc trois gestes possibles.

Observer : appeler await next(e) d’abord, puis regarder le résultat, par exemple pour prendre une mesure après chaque tour. Réécrire : transmettre un événement modifié, next({ ...e, command }), pour que la suite de la chaîne voie autre chose. Répondre : renvoyer { deny } sans appeler next, ce qui refuse un appel d’outil ou sert soi-même une commande.

Deux exemples du guide officiel

Le guide construit Token Weather, environ 80 lignes, qui dessine une ligne au-dessus du prompt : une météo en direct de la fenêtre de contexte. ☀ Clear sous 25 %, ☁ Cloudy, ☂ Showers, ☇ Storm à partir de 75 %, ↯ Compact soon dès 90 %. En trois tours de démo, elle passe de 18 % à 67 % puis 81 % d’une fenêtre de 200k. Observation pure : il lit $.session.usage() après chaque tour et redessine.

Le second, Blast Radius, utilise le troisième geste. Quand Claude appelle Bash avec rm -rf, git reset --hard, git clean, un force push ou une migration de base de données, il retient l’appel, calcule ce que la commande toucherait, et ouvre un panneau avec Proceed et Cancel. Dans la démo, il retient rm -rf build et liste les 9 fichiers (1,1 Mo) qui seraient supprimés. Le guide reconnaît sa limite : il lit le texte de la commande, donc $(…), les alias et les scripts qui appellent rm passent au travers. C’est un filet de sécurité, pas un système de permissions ; pour un vrai blocage, utilisez les règles de permission.

Recording Mode : l’écran change, pas les données

Le mod qui résout mon problème de cuisine ne vient pas du guide. Recording Mode vient d’un dépôt communautaire de Nate Herk, sous licence MIT. Vous tapez /rec avant de lancer l’enregistrement, et il s’applique à toutes les conversations ouvertes en 3 secondes ; /rec off le coupe partout.

Tant qu’il est actif, il masque à l’écran les clés d’API et les tokens, toutes les valeurs d’un .env du projet ou de ses dossiers parents, les e-mails, les noms, les numéros de téléphone, les adresses, les numéros de carte et de compte, les montants, et les chiffres voisins de mots comme revenue ou payroll. /rec strict masque en plus tous les grands nombres et les pourcentages. Il garde fermés les .env, les clés SSH et cloud, le dossier mémoire de Claude et les documents financiers, et un ● REC rouge s’affiche au-dessus du prompt.

Le point clé, selon le README : les résultats des outils de mail, d’agenda, de CRM ou de finance sont cachés à l’écran, mais Claude reçoit toujours le vrai résultat. La cuisine n’a pas bougé, la caméra floute.

Pour essayer

D’abord, vérifiez votre version : 2.1.287 ou plus récent.

claude --version

Ajoutez ensuite le dépôt de mods de la communauté, après l’avoir lu.

claude plugin marketplace add nateherkai/claude-code-mods

Installez Recording Mode, ouvrez un nouveau chat, puis tapez /rec avant d’enregistrer.

claude plugin install recording-mode@nateherk-mods

Pour l’adapter, /rec config crée un config.json dans ~/.claude/mods-data/recording-mode/ : noms à toujours masquer, votre nom à garder visible, chemins privés interdits pendant l’enregistrement.

Écrire le sien

Nul besoin d’apprendre l’API. Lancez claude, décrivez le mod voulu avec vos mots, et acceptez le hot reload quand il le propose : le mod apparaît à la fin du tour, et chaque retouche se recharge sur place. Le guide conseille de garder les données dans $.state plutôt que dans des variables du module, car chaque rechargement relance register. Un mod étant un plugin, un dépôt GitHub avec un fichier de marketplace suffit pour le partager.

En bref

Un mod est un maillon de la chaîne entre ce qui se passe dans votre session et ce que Claude Code fait ou affiche. Observer, réécrire, répondre : trois gestes suffisent pour une météo du contexte, un garde-fou devant rm -rf ou une caméra qui floute vos secrets. Commencez par Recording Mode avant votre prochaine démo, puis décrivez le vôtre à Claude.