Mods de Claude Code : ce que c'est, et celui que nous livrons à chaque agent

Le 1er octobre 2026, Claude Code 2.1.287 est sorti avec une ligne de changelog : « Added Claude Mods ». Quatre jours plus tard, AgentsRoom chargeait l'un des nôtres dans les agents Claude qu'il fait tourner.

Cet article explique ce qu'est un mod, ce qu'il permet que les anciens points d'extension ne permettaient pas, comment en écrire, en charger et en tester un, et ce que nous avons appris en livrant un mod dans chaque agent Claude qu'AgentsRoom démarre. Les faits sur Claude Code viennent de sa documentation et de son changelog, lus le 9 novembre 2026, avec Claude Code 2.1.318 installé.

La réponse courte. Un mod est un plugin Claude Code qui contient un hooks module : un fichier JavaScript ou TypeScript dont Claude Code appelle les fonctions depuis son propre processus quand un événement se produit. Une fonction peut laisser passer l'événement, le modifier, ou y répondre à la place de Claude Code. C'est ainsi qu'un mod dessine un panneau, ajoute une commande ou arrête une commande shell avant qu'elle tourne.

Ce qu'est un mod

Claude Code avait déjà des plugins : un dossier avec un manifeste dans .claude-plugin/plugin.json, qui regroupe des skills, des sous-agents, des hooks de settings et des serveurs MCP pour qu'ils s'installent d'un bloc. Un mod est une chose de plus qu'un plugin peut contenir. Quand le fichier hooks/hooks.json du plugin nomme un fichier de code sous sa clé modules, Claude Code charge ce fichier et appelle la fonction register qu'il exporte. Le plugin s'appelle alors un mod.

Dans register, chaque appel à on(event, hook) attache une fonction à un événement : tool.call avant qu'un outil tourne, prompt.submit quand tu envoies un prompt, session.start, command.run pour une commande slash, ui.render quand Claude Code dessine une partie de son écran, et d'autres. Chaque hook reçoit trois choses :

• $, l'API des mods : tout ce qu'un mod peut faire hors de son propre code, comme $.ui, $.command, $.fs, $.process ou $.http.
• e, l'événement, en données simples : pour un appel d'outil, le nom de l'outil et ses arguments.
• next, qui passe l'événement aux autres mods puis au comportement de Claude Code, et renvoie le résultat.

Ce que le hook fait de next décide de la suite. Renvoie next(e) et tu n'as fait qu'observer. Appelle next avec une copie modifiée de e et tu as réécrit l'événement. Renvoie ton propre résultat sans appeler next et tu y as répondu : l'outil ne tourne jamais, ou Claude Code ne dessine jamais sa propre version.

La documentation appelle aussi ces fonctions des hooks. Ce ne sont pas les hooks que tu écris dans settings.json, que Claude Code appelle désormais settings hooks.

Mod, hook de settings, skill ou serveur MCP

Les quatre se recoupent, et le mod est le plus lourd. Choisis le plus léger qui fait le travail.

Un plugin peut contenir les quatre, donc un mod peut être livré à côté de la skill et du serveur MCP avec lesquels il travaille.

Les trois fichiers d'un mod

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json est le manifeste habituel d'un plugin : un nom, une version, une description. hooks.json pointe vers le code, { "modules": ["./register.ts"] }, un seul chemin, relatif à ce fichier. register.ts est le hooks module. Claude Code charge directement les .js et les .ts, sans bundler ni étape de build, et le seul import nu autorisé est claude-code, pour les types et quelques utilitaires.

Le mod que nous livrons : qui a modifié ce fichier ?

AgentsRoom fait tourner plusieurs agents de code sur le même dépôt et montre, dans son onglet Changements, quel agent a modifié quel fichier, pour que tu puisses relire et commiter le travail de chaque agent séparément. Les fichiers écrits avec les outils Edit et Write de Claude étaient faciles : Claude Code les signale par un hook de settings. Ceux écrits par une commande shell, non. Un sed -i, un heredoc, un codemod ou un rm ne passent jamais par un outil de fichier.

Avant les mods, on devinait. AgentsRoom lisait le transcript de session de l'agent pour savoir quand chaque commande Bash avait commencé et fini, puis comparait la date de modification du fichier à ces intervalles. Ça marchait la plupart du temps, et ça échouait de trois façons qu'on savait nommer :

• un fichier supprimé n'a plus de date de modification, donc une suppression n'était jamais attribuée ;
• une commande en lecture seule comme grep ouvrait un intervalle pendant lequel l'agent aurait pu écrire n'importe quoi ;
• tout dépendait du format du transcript, que Claude Code est libre de changer.

Un mod supprime la devinette. Notre mod agentsroom-changes s'accroche à tool.call pour les deux outils shell. Juste avant que la commande tourne, il prend une photo du dépôt (git status, plus la taille et la date de modification de chaque chemin modifié). Juste après, il en prend une seconde. Les chemins qui diffèrent sont ce que la commande a changé, suppressions comprises, et le mod les envoie à l'app desktop AgentsRoom par un point d'accès HTTP local. Un appel que Claude Code marque lui-même comme lecture seule ne revendique rien.

Voici le hook, raccourci. Le fichier complet fait 177 lignes, surtout la photo du dépôt et ses limites.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

L'app desktop copie le mod dans son propre dossier et démarre chaque agent Claude avec claude --plugin-dir <ce dossier>, seulement quand le Claude Code installé est en 2.1.287 ou plus récent. Nous l'avons livré dans AgentsRoom 1.201.0, le 5 octobre 2026.

Ce que nous avons appris en le livrant

Un mod ne doit jamais coûter un appel d'outil à l'utilisateur. Notre hook se place devant chaque commande shell que Claude lance. S'il plante, ou s'il attend le réseau, le travail de Claude s'arrête. Chaque étape est protégée, chaque envoi vers l'app desktop part sans attendre de réponse, et la seule attente que nous acceptons, ce sont deux photos git status, plafonnées à 15 secondes chacune. Un envoi perdu coûte une attribution, jamais la commande.

Ne rien faire quand on n'est pas attendu. Le mod lit une variable d'environnement qu'AgentsRoom pose pour ses agents. Quand elle manque, par exemple parce que quelqu'un a copié le dossier dans sa propre configuration, chaque hook passe directement à next(e).

Un dossier chargé avec --plugin-dir est surveillé. Claude Code recharge le mod quand un fichier de ce dossier change, et un rechargement relance register. Ça a décidé de notre façon de l'installer : l'app desktop n'écrit un fichier du mod que si son contenu a changé, parce qu'une réécriture aveugle à chaque lancement d'agent rechargerait le mod dans toutes les consoles Claude déjà ouvertes.

Prévoir que l'API bouge. Les événements et les méthodes peuvent changer d'une version à l'autre, et la documentation le dit elle-même. Quand un mod est chargé depuis --plugin-dir, Claude Code écrit les déclarations de types de la version qui tourne dans .claude-plugin/types/ ; c'est contre elles que nous vérifions les types, pas contre une page web. Et si une version ne charge plus notre mod, rien ne casse : le mod ne se déclare jamais prêt, et AgentsRoom revient à l'ancienne méthode par le transcript.

Écrire le tien

Tu as deux portes d'entrée.

Demander à Claude. Dans une session Claude Code interactive, décris le mod que tu veux (« affiche la branche git courante au-dessus du prompt »). Claude s'appuie sur une skill intégrée, plugin-authoring, écrit le mod dans un dossier propre à cette session, et Claude Code te demande une fois s'il doit activer les mods que Claude écrit. Réponds oui et le mod se charge à la fin du tour, puis se recharge après chaque tour qui le modifie.

Écrire les trois fichiers toi-même, puis :

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate affiche une ligne hooks: avec les événements que ton module gère et une ligne calls: avec chaque méthode de l'API des mods qu'il appelle. Si un événement que tu voulais gérer manque, Claude Code n'appellera pas ce hook non plus. L'analyse statique a ses règles : écris chaque appel en entier ($.ui.toast(...), jamais const ui = $.ui), passe les noms d'événements en chaînes littérales, et n'importe que tes propres fichiers, par chemin relatif.

Pour partager un mod, traite-le comme le plugin qu'il est : envoie le dossier, ou liste-le dans une marketplace (un dépôt avec un .claude-plugin/marketplace.json) pour qu'on l'installe avec /plugin install <name>@<marketplace>.

Des mods à lire dès aujourd'hui

• Intégrés à Claude Code : /plugin, onglet Installed, section Built-in. Parmi eux, le panneau /diff et le chargeur qui lit AGENTS.md comme consignes du projet, dont Anthropic publie le code dans le dossier mods du dépôt anthropics/claude-code, avec leurs tests. Intégré aussi, et coupé tant que tu ne l'actives pas : You should know, un agent annexe qui signale ce que toi ou Claude auriez pu manquer.
• Les exemples d'Anthropic, dans le dépôt claude-code-playground : une prévision de la fenêtre de contexte dessinée au-dessus du prompt, une garde qui retient une commande shell risquée et montre ce qu'elle changerait, et une commande /replay qui rejoue pas à pas les modifications du dernier tour.
• Le nôtre, décrit plus haut : un mod sans aucune interface, un seul hook tool.call, une bonne forme à copier si ce qu'il te faut est de la donnée plutôt qu'un panneau.

Avant d'installer le mod de quelqu'un d'autre

Un mod n'est pas isolé dans une sandbox. Il tourne avec tes droits : il peut lire et écrire tes fichiers, lire tes variables d'environnement et tes réglages (clés d'API comprises), lancer des programmes, faire des requêtes réseau, voir chaque prompt et chaque appel d'outil, et approuver un appel d'outil avant qu'on te le demande. Si tu as activé la sandbox de Claude Code, elle couvre les commandes Bash que Claude lance, pas les processus qu'un mod démarre.

Alors lis avant d'installer. Clone le mod et lance claude plugin validate sur le dossier : les lignes hooks: et calls: te disent ce qu'il écoute et ce qu'il atteint, sans rien exécuter. Un mod qui dessine seulement une bande au-dessus du prompt n'a aucune raison d'appeler $.http ou $.process. Pour arrêter tous les mods que tu as installés, démarre avec --safe-mode le temps d'une session, ou mets "disableAllHooks": true dans ~/.claude/settings.json.

Où tournent les mods

Un mod qui dessine devrait vérifier où il tourne et se replier sur du texte là où rien ne se dessine.

Dans AgentsRoom

Tu n'installes rien : à partir de Claude Code 2.1.287, chaque agent Claude démarre avec le mod, et l'onglet Changements montre les fichiers que chacune de ses commandes shell a créés, modifiés ou supprimés, à côté de l'agent qui l'a fait. Avec un Claude Code plus ancien, AgentsRoom continue de rattacher les écritures shell par le transcript, comme avant.

La même idée tourne dans d'autres CLI quand c'est possible : oh-my-pi reçoit une extension au même contrat, et les autres CLI gardent leur façon de rattacher les écritures shell. Pour aller plus loin dans ce que Claude Code expose à chaque étape, notre guide des hooks de Claude Code couvre les hooks de settings à côté desquels un mod se place.

Questions fréquentes

Qu'est-ce qu'un mod dans Claude Code ?

Un mod est un plugin Claude Code qui contient un hooks module : un fichier JavaScript ou TypeScript dont Claude Code appelle les fonctions depuis son propre processus quand quelque chose se passe, comme un appel d'outil, un prompt envoyé ou une partie de l'écran à dessiner. Chaque fonction peut laisser passer l'événement, le modifier ou y répondre elle-même. C'est ce qui permet à un mod de dessiner un panneau, d'ajouter une commande ou de retenir une commande shell risquée.

Quelle version de Claude Code faut-il pour les mods ?

Claude Code 2.1.287 ou plus récent dans le terminal, sorti le 1er octobre 2026, dont le changelog dit « Added Claude Mods ». L'onglet Code de l'app Claude Desktop les accepte depuis la 2.1.286. Dans l'extension VS Code, les hooks tournent, et ce qu'un mod dessine demande l'extension 2.1.299 ou plus récente. Lance claude --version pour vérifier.

Quelle différence entre un mod et un hook de Claude Code ?

Un hook écrit dans settings.json lance une commande shell, une requête HTTP ou un prompt quand un événement se produit, en dehors de Claude Code. Les hooks d'un mod sont des fonctions qui tournent dans Claude Code. Ils font ce qu'un hook de settings ne peut pas faire : dessiner dans l'interface, ajouter une commande slash qui s'exécute sans tour de Claude, réécrire un appel d'outil ou y répondre sans lancer l'outil, et partager un état entre hooks.

Les mods de Claude Code sont-ils sûrs à installer ?

Un mod n'est pas isolé dans une sandbox. Il tourne avec tes droits, peut lire tes fichiers et tes variables d'environnement, lancer des programmes, faire des requêtes réseau et approuver un appel d'outil. N'installe que les mods d'auteurs en qui tu as confiance, et lance d'abord claude plugin validate sur le dossier : il liste les événements que le mod écoute et les appels qu'il fait, sans l'exécuter.

Où trouver des exemples de mods Claude Code ?

Anthropic publie le code de certains mods intégrés, comme le panneau /diff et le chargeur d'AGENTS.md, dans le dossier mods du dépôt anthropics/claude-code, et des mods d'exemple dans le dépôt anthropics/claude-code-playground. Celui d'AgentsRoom décrit dans cet article est un quatrième type d'exemple : un mod sans interface, avec un seul hook tool.call.

Peut-on désactiver les mods ?

Oui. Désactive un mod dans l'onglet Installed de /plugin, démarre une seule session avec --safe-mode, ou mets disableAllHooks à true dans ~/.claude/settings.json pour arrêter tous les mods que tu as installés, avec tes hooks de settings. --safe-mode et disableAllHooks laissent tourner les mods intégrés : ceux-là se coupent un par un dans /plugin.