SpyBara
Go Premium

plugins/mods/reference.md 2026-10-01 23:59 UTC to 2026-10-02 11:59 UTC

This page contains 326 additions and 0 deletions.

2026
Fri 2 11:59

Référence des mods

Référence complète des mods Claude Code : structure du module de hooks, événements, méthodes de l'API des mods, points de rendu, éléments par surface, limites et paramètres.

Consultez tout événement qu'un mod peut gérer, toute méthode de l'API des mods qu'il peut appeler, ou tout point de rendu dans lequel il peut dessiner, pour la CLI Claude Code et l'application Desktop à partir de la v2.1.287. Chaque entrée donne le nom et une description d'une ligne, avec un lien vers la section du guide qui l'explique lorsqu'elle existe.

Fichiers

Un mod est un répertoire de plugin contenant ces fichiers :

Fichier Requis Contenu
.claude-plugin/plugin.json Oui Le manifeste du plugin. Les mods n'ajoutent aucun champ requis.
hooks/hooks.json Oui modules : un tableau contenant un chemin, relatif à ce fichier, vers le module de hooks, comme dans "modules": ["./register.js"]. Peut aussi contenir des hooks de paramètres sous hooks.
Le module de hooks, tel que hooks/register.js Oui Le point d'entrée du mod. Exporte register(on, options). Nommé .js, .mjs, .cjs, .jsx, .ts, .mts, .cts ou .tsx. Un module ES.
types/index.d.ts, désigné par types dans le manifeste Lorsque le mod utilise $.state ou ajoute un namespace à l'API des mods Déclare les valeurs PluginState et tout namespace ajouté par le mod
Fichiers dont le nom se termine par .test.ts ou .test.tsx Non Tests exécutés par claude plugin test

register reçoit on et options. options contient les valeurs des champs userConfig déclarés par le manifeste, avec les valeurs par défaut renseignées.

La fonction de hook

Un mod enregistre chacun de ses hooks, qui sont des gestionnaires d'événements, en appelant on à l'intérieur de register. on prend le nom de l'événement, un matcher facultatif, qui est un filtre sur les champs de l'événement, et le hook, comme dans on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on renvoie un enregistrement doté d'une seule méthode, .catch(handler), qui définit le gestionnaire d'erreurs du hook.

Argument Ce que c'est
$ L'API des mods : chaque méthode de Méthodes de l'API des mods. Écrivez chaque appel en entier, namespace puis méthode, comme dans $.fs.read('notes.md').
e L'entrée de l'événement, sous forme de données simples profondément figées. Pour la modifier, passez une copie à next.
next(e) Le gestionnaire suivant, comme dans un middleware. Exécute les hooks qui suivent celui-ci, puis le comportement de Claude Code. Se résout avec le résultat de l'événement.
next.signal Un AbortSignal qui s'interrompt lorsque l'événement est abandonné
next.origin { plugin, tier } de l'émetteur de l'événement. Claude Code lui-même est { plugin: 'engine', tier: 'core' }. Le tier d'un mod est son groupe de priorité dans l'ordre d'exécution des mods : prepend, user, append ou builtin.
next.budget La limite de temps du hook en millisecondes : next.budget.ms est la limite totale, et next.budget.remainingMs est ce qui reste à cet instant
next.to(e, tier) Passe directement à un tier ultérieur, qui est append, builtin ou core. next.to(e, 'append') ignore les mods installés par un utilisateur. Seul un mod présent dans prependPlugins ou appendPlugins peut l'appeler.
next.error, next.called Dans un gestionnaire .catch uniquement. next.error.kind vaut throw ou timeout, next.error.message est le texte de l'erreur, et next.called vaut true lorsque le hook en échec avait appelé next.

Événements

Les événements sont regroupés selon ce qu'ils concernent, chacun avec le moment où il se déclenche et ce qu'un hook qui le gère peut renvoyer. Les hooks sur turn.step et process.spawn sont des générateurs asynchrones, et les autres hooks sont des fonctions asynchrones.

La dernière colonne de chaque tableau utilise une notation abrégée. next(e) transmet l'événement sans modification. next({ ...e, text }) transmet une copie dont le champ nommé est modifié, comme dans next({ ...e, text: e.text.trim() }). Un objet répond à l'événement sans appeler next, et un mot tel que reason désigne une chaîne que vous écrivez, comme dans { deny: 'Use the file tools.' }.

Outils

Les événements d'outils se déclenchent autour de chaque appel d'outil effectué par Claude, depuis la description que Claude lit jusqu'à la décision d'exécuter ou non l'appel :

Événement Se déclenche lorsque Un hook peut renvoyer
tool.call Un outil est sur le point de s'exécuter next(e), { deny: reason } ou { result }
tool.check Claude Code décide si un appel d'outil peut s'exécuter, après les hooks tool.call et PreToolUse. next(e) se résout avec la décision à laquelle ont abouti les règles, le mode de permission et ces hooks. { decision }, qui vaut allow, ask ou deny
tool.describe Une fois pour chaque outil, lorsque sa description est envoyée à Claude pour la première fois { description }

Prompts et ce que Claude lit

Les événements de prompt couvrent le texte que l'utilisateur saisit et le texte que Claude Code envoie de lui-même à Claude, comme le prompt système et les rappels :

Événement Se déclenche lorsque Un hook peut renvoyer
prompt.submit Un prompt est soumis next({ ...e, text }), next({ ...e, context }) ou { drop: reason }
prompt.fill, prompt.suggest Du texte est sur le point d'être placé dans la zone de prompt en tant que brouillon, ou en tant que suggestion estompée next(e) avec le texte modifié
prompt.edit L'utilisateur modifie la zone de prompt next(e)
prompt.compose Claude Code génère un prompt système { sections }, une liste de { id, text, scope } dans l'ordre d'envoi
prompt.section Une fois pour chaque section nommée du prompt système. e.name est l'id de la section dans prompt.compose. { text }, ou { text: null } pour omettre la section
prompt.context Une fois pour chaque conversation, pour le contexte envoyé avec le premier message { blocks }
prompt.attachment Claude Code ajoute un message de sa propre initiative pour Claude, tel qu'un rappel. e.type nomme le type, et pour les types que déclarent les déclarations de types, e.detail contient les informations à partir desquelles le texte a été rédigé. { text }, ou { text: null } pour l'omettre
skill.prompt Le texte d'un skill est développé pour Claude { text }
attribution.text Claude Code compose le texte d'attribution d'un commit ou d'une pull request { text }

Commandes et configuration

Les événements de commande et de configuration se déclenchent lorsqu'une commande s'exécute ou est listée, et lorsqu'une ligne de /config est affichée ou modifiée :

Événement Se déclenche lorsque Un hook peut renvoyer
command.run Une commande est sur le point de s'exécuter { text }, {} ou next(e)
command.describe Une fois pour chaque commande, pour la liste des commandes { description, argumentHint, isHidden }
config.set Une ligne de /config est sur le point de changer next({ ...e, value }) ou { deny: reason }
config.describe Une fois pour chaque ligne de /config { label, description, isHidden }

Tours

Les événements de tour suivent une réponse du début à la fin, y compris chaque requête envoyée au modèle pendant celle-ci :

Événement Se déclenche lorsque Un hook peut renvoyer
turn.start Un tour commence next(e)
turn.step Une requête est sur le point d'être envoyée au modèle yield* next(e), ou next({ ...e, model }), next({ ...e, effort })
turn.complete Un tour s'est terminé next(e), ou { text } pour afficher une ligne sous la réponse

Session

Les événements de session marquent le démarrage, la fin et la compaction de la session, ainsi que l'échange de messages avec d'autres sessions :

Événement Se déclenche lorsque Un hook peut renvoyer
session.start Une fois pour chaque mod chargé, avant le premier prompt, puis à nouveau après un rechargement de ce mod. Pas après /clear, /resume ou /branch. next(e)
session.end La session se termine, ou /clear, /resume ou /branch s'exécute. e.reason vaut clear, resume, logout, prompt_input_exit ou other. /branch signale resume. next(e)
session.compact La conversation est sur le point d'être compactée { skip: reason }
session.receive, session.send Un message arrive d'un autre agent ou d'une autre session, ou est sur le point d'y être envoyé. Consultez Envoyer et recevoir des messages entre sessions. { consumed: reason } pour receive, { isDelivered: false, reason } pour send
session.append Une fois pour chaque ligne conservée par la conversation, telle qu'un prompt, un bloc de réponse, un résultat d'outil ou une notification, avant son stockage next({ ...e, message }) pour réécrire le content de la ligne
session.attach, session.detach Une autre application se connecte à la session ou s'en déconnecte next(e)
session.measure Après chaque tour, et lorsque le pourcentage utilisé d'une limite de forfait change next(e)

Sous-agents

Les événements de sous-agent se déclenchent lorsqu'un type de sous-agent est proposé à Claude et lorsqu'un sous-agent est sur le point de démarrer :

Événement Se déclenche lorsque Un hook peut renvoyer
agent.offer Un type de sous-agent est proposé à Claude { isOffered: false } pour le retenir
agent.spawn Un sous-agent est sur le point de démarrer { model } ou { deny: reason }

Interface

Les événements d'interface se déclenchent lorsque Claude Code dessine un point de rendu et lorsque l'utilisateur utilise un contrôle dessiné par un mod. Dessiner dans l'interface montre ce que renvoie un hook ui.render :

Événement Se déclenche lorsque
ui.render Un point de rendu est sur le point d'être dessiné
ui.resolve Les mods se chargent, une fois pour chaque application, point de rendu et mod. Le résultat est la table d'éléments que lit $.ui.resolve(e).
ui.press, ui.input, ui.select Un Button, un Input ou un Select dessiné par un mod est utilisé
ui.focus, ui.scroll Le contrôle ayant le focus ou la position de défilement d'un volet ou du bandeau est sur le point de changer
ui.close Un volet est sur le point de se fermer. e.id est le volet et e.origin.kind vaut plugin, person ou unload.
ui.message Un élément Client envoie des données à son mod

Autres mods

Ces événements permettent à un mod d'agir sur d'autres mods au moment de leur chargement, pour en refuser un ou modifier l'API des mods qu'il reçoit :

Événement Se déclenche lorsque Un hook peut renvoyer
plugin.register Un module de hooks est sur le point de se charger. e.uses liste ses événements, ses appels à l'API des mods, ses variables d'environnement et son état, tels que claude plugin validate les affiche. Chaque appel est écrit sans le préfixe $., comme fs.read. { refuse: reason }
engine.create L'API des mods est en cours de construction pour ce mod Une API des mods modifiée, pour ajouter un namespace ou en retenir un

Télémétrie

Les événements de télémétrie se déclenchent pour les enregistrements d'utilisation que Claude Code journalise :

Événement Se déclenche lorsque Un hook peut renvoyer
telemetry.log, telemetry.mark Un enregistrement de télémétrie est sur le point d'être journalisé, ou une utilisation d'une fonctionnalité est marquée. Dans un mod que vous installez, donnez à un hook de télémétrie le filtre { to: 'collector' }, comme dans on('telemetry.log', { to: 'collector' }, hook). Sans ce filtre, le mod échoue à claude plugin validate. * ne correspond pas à ces événements. next(e), ou { deny: reason }

Événements des hooks de paramètres

Chaque événement de hook de paramètres est un événement nommé classic.<Event>, tel que classic.Stop ou classic.PostToolUse. e est le JSON stdin du hook.

Appels à l'API des mods

Chaque méthode de l'API des mods est également un événement, nommé d'après son namespace et sa méthode, comme fs.read, model.complete ou ui.open. Un hook sur l'un d'eux intercepte les appels des mods qui s'exécutent après lui, et peut renvoyer next(e), { deny: reason } ou { value }.

Méthodes de l'API des mods

L'API des mods est l'argument $ que reçoit chaque hook. Ses méthodes sont regroupées en namespaces, comme $.ui. Ce tableau liste les méthodes de chaque namespace par nom : ainsi, open dans la ligne $.ui correspond à l'appel $.ui.open(...). Les guides montrent les plus courantes en action, et les types pour votre build documentent chaque méthode avec un exemple.

Namespace Méthodes
$.plugin name, root : le nom et le répertoire de ce plugin
$.ui resolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list
$.model complete, fork, classify
$.prompt submit, read, fill, suggest, compose. Claude lit le texte de submit({ text }) après une phrase qui désigne votre mod comme expéditeur. submit({ text, asUser: true }) envoie le texte comme s'il s'agissait des propres mots de l'utilisateur, sans cette phrase.
$.turn abort
$.session messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() renvoie { startedAt, context, rateLimits, cost } : context contient tokens, window et percent, et rateLimits est une liste de { kind, percentUsed, resetsAt }.
$.config list, set
$.settings read
$.env get, set
$.fs read, write, list, exists, stat, ancestors. write n'est pas atomique : il remplace le contenu du fichier sur place, de sorte qu'un autre processus peut lire un fichier partiellement écrit. Conservez dans $.store les données que plusieurs sessions modifient.
$.store get, set, delete, keys. Un magasin clé-valeur partagé par toutes les sessions de la machine. Consultez Enregistrer depuis plusieurs sessions.
$.state État réactif : get, set, avec les helpers atom, read, update, derive et memberOf importés depuis claude-code
$.clock now, sleep, after, every
$.http fetch
$.process run, spawn
$.mcp call, connect. connect(server) connecte un serveur MCP listé par le manifeste de votre propre plugin.
$.audio play, speak
$.telemetry log, mark. Un enregistrement n'est envoyé que lorsque l'appel est effectué par Claude Code ou par un mod intégré.

Points de rendu

Un point de rendu est un point d'extension de l'interface de Claude Code. Chaque ligne est une valeur de e.component dans un hook ui.render, avec les champs de e.props et les applications qui l'affichent. e.surface vaut terminal ou desktop. Modifier ce que Claude Code dessine déjà montre ce qu'un hook peut faire à un point de rendu, avec un exemple pour chaque option.

Point de rendu e.props e.requestId Affiché dans
Pane title, isFocused, bodyColumns, placement, scroll, view L'id du volet Terminal, Desktop
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Une seule instance Terminal, Desktop
UserMessage text, origin, isExpanded, et task ou from selon l'origine L'id du message Terminal, Desktop
AssistantMessage Le texte de la réponse L'id du message Terminal, Desktop
ToolUse, ToolResult, ToolGroup Le nom, l'entrée et le résultat de l'outil L'id de l'appel d'outil Terminal, Desktop
CommandOutput command, text L'id du message Terminal, Desktop
AskUserQuestion La question et les options L'id de l'appel d'outil Terminal, Desktop
ToolProgress kind L'id de l'appel d'outil Terminal
Spinner word, message, suffix, mode L'id de l'agent Terminal, Desktop
TurnDuration word, durationMs L'id du message Terminal
InfoNotice text, command L'id du message Terminal
SessionMode modes Une seule instance Terminal, Desktop
PromptHint isDraft, isWorking, hint Une seule instance Terminal, Desktop

e.viewport contient columns, rows et isFullscreen. Il est absent tant que l'application n'a pas mesuré sa fenêtre. Son rows correspond à la hauteur de la fenêtre entière, et non à celle de votre volet.

Pour adapter un arbre à son point de rendu, lisez ces props dans le hook :

  • Largeur d'un Pane ou du bandeau : dessinez selon e.props.bodyColumns
  • Hauteur d'un Pane à côté de la transcription : lorsque e.props.placement vaut 'dock', e.props.scroll.bodyRows est le nombre de lignes dont dispose le volet
  • Hauteur d'un Pane au-dessus du prompt : lorsque e.props.placement vaut 'inline', le volet s'agrandit avec votre arbre jusqu'à une limite, et bodyRows ne compte que les lignes actuellement affichées. Le champ rows de $.ui.open permet de demander une limite différente.

Un arbre plus haut que le volet défile d'un seul bloc.

Éléments

Les éléments sont les briques de l'arbre que renvoie un hook ui.render, et vous les obtenez à partir de $.ui.resolve(e). Construire un arbre à partir d'éléments présente les plus courants avec leur rendu dans le terminal, et la galerie d'interface contient des captures d'écran de la plupart d'entre eux. Une coche signifie que l'application peut dessiner l'élément.

Élément Props principales Terminal Desktop
Box key, disposition flex, gap, padding, margin, width, height, borderStyle, backgroundColor, position, hover ✓ ✓
Text color, backgroundColor, bold, italic, underline, dimColor, inverse, wrap ✓ ✓
Button key, label, onPress, hotkey, plain, dimColor, autoFocus, action ✓ ✓
Link href, label ✓ ✓
Code Le code, jusqu'à 10 000 caractères ✓ ✓
Markdown text, jusqu'à 10 000 caractères, key, dimColor, onLinkPress, pressableLinks ✓ ✓
Input key, label, placeholder, value, submitLabel, onSubmit, onInput, autoFocus ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓
Svg Un document SVG, jusqu'à 131 072 caractères ✓
Client module, key ✓ ✓
Raster key, columns jusqu'à 512, rows jusqu'à 256, cells. Consultez Dessiner une grille de cellules colorées. ✓
Image Octets PNG ou RGBA jusqu'à 2 Mio, ou un chemin de fichier ✓

Autres règles pour Button : action nomme l'une des propres actions de raccourci clavier de Claude Code, et le raccourci de l'utilisateur pour cette action presse le bouton lorsque ce raccourci est une combinaison de touches ou une touche avec modificateur. Un hotkey numérique sur un bouton du bandeau se déclenche aussi lorsque l'utilisateur tape ce seul chiffre dans un prompt vide puis marque une pause. Lorsque deux boutons d'un même dessin désignent le même hotkey, c'est le dernier qui l'obtient. autoFocus n'accepte que true sur tout contrôle : omettez donc la prop pour le désactiver.

Limites

Les hooks et les appels à l'API des mods s'exécutent sous des limites de temps et de taille. Claude Code ignore un hook qui dépasse une limite de temps et rejette un appel qui dépasse une limite de taille.

Limite Valeur
Le temps d'exécution propre d'un hook pour un événement, sans compter le temps passé dans next ou dans un appel à l'API des mods autre que $.clock.sleep 10 secondes
Le temps d'exécution d'un gestionnaire .catch 1 seconde
L'ensemble des hooks session.end 1,5 seconde
Délai d'expiration de $.process.run 30 secondes par défaut, 10 minutes au maximum
maxTokens de $.model.complete 1024 par défaut, jusqu'à 64 000 ou la limite de sortie du modèle
$.fs.read et $.fs.write 4 Mio pour un fichier
Un enfant chaîne d'un Text 10 000 caractères
$.store 4 Mio de JSON au total
$.session.messages() Les 4 096 entrées les plus récentes
Redessins $.ui.invalidate('ui.render') Limités à 10 par seconde, ou 30 dans le terminal pour le volet visible, le bandeau déployé et la ligne d'indication sous le prompt. Les appels plus rapprochés sont regroupés.
$.ui.toast Affiché pendant 4 secondes sauf si vous passez { timeoutMs }
Un volet ouvert sans que l'utilisateur l'ait demandé Placé à partir de 144 colonnes de terminal, 110 une fois que l'utilisateur l'a ouvert une fois
Noms de commandes, d'outils, de types de sous-agents et de volets Lettres, chiffres, _ et -, jusqu'à 64 caractères
Un test claude plugin test 5 secondes sauf si le test définit timeoutMs

Paramètres et variables d'environnement

Voici les paramètres et variables d'environnement qui affectent les mods. La colonne Emplacement indique le fichier de paramètres ou l'environnement à partir duquel chacun est lu :

Nom Emplacement Effet
CLAUDE_CODE_PLUGIN_DIRS Environnement, ou env dans ~/.claude/settings.json Répertoires de plugins à charger comme le fait --plugin-dir, pour les applications auxquelles vous ne pouvez pas passer de flag. Chemins absolus séparés par :, ou ; sous Windows.
CLAUDE_CODE_PLUGIN_DIR_WATCH Environnement 1 fait recharger les mods --plugin-dir à l'enregistrement dans une session non interactive de longue durée
prependPlugins, appendPlugins Paramètres gérés. Paramètres utilisateur uniquement sur une machine sans paramètres gérés, pour un utilisateur qui n'est pas connecté avec un forfait Team ou Enterprise. Listes d'identifiants de plugins, comme acme-guard@acme-tools. Les mods de prependPlugins s'exécutent avant tout mod installé par un utilisateur, et ceux de appendPlugins après, dans l'ordre indiqué. Consultez L'ordre d'exécution des mods.
allowManagedModsOnly Paramètres gérés, en tant qu'option du garde-fou intégré Seuls les mods qui relèvent de votre organisation et les mods intégrés à Claude Code se chargent. Les hooks de paramètres des utilisateurs continuent de s'exécuter.
allowModsToOverrideDenyRules Paramètres gérés, en tant qu'option du garde-fou intégré Permet à un mod installé par un utilisateur d'approuver un appel d'outil refusé par une règle deny
allowManagedHooksOnly Paramètres gérés Bloque les hooks et les mods installés qui n'appartiennent pas à votre organisation. Consultez ce qui continue de s'exécuter.
disableAllHooks Tout fichier de paramètres Dans les paramètres gérés, aucun mod ni hook provenant d'un plugin installé ne s'exécute. Dans vos propres paramètres, ce que gère votre organisation continue de s'exécuter. Consultez disableAllHooks.
disableSideloadFlags Paramètres gérés Rejette --plugin-dir et --plugin-url au démarrage
pluginConfigs Paramètres utilisateur ou gérés Contient les valeurs userConfig d'un mod, indexées par l'identifiant du plugin, comme acme-guard@acme-tools, ou par son nom suivi de @inline, comme first-mod@inline, pour un mod chargé avec --plugin-dir

sec-default@builtin est un garde-fou intégré à Claude Code, listé sous le nom cc-plugin-sec-default dans /plugin et dans le log de débogage. Il se charge avant tout mod installé par une personne sur une machine dotée de paramètres gérés, ou pour un utilisateur connecté avec un forfait Team ou Enterprise. Si prependPlugins est défini dans les paramètres gérés, le garde-fou ne se charge que lorsque cette liste le nomme, à la position indiquée. Son code source se trouve dans le répertoire mods/sec-default du dépôt Claude Code.

Commandes

Ces commandes et flags permettent de charger, d'inspecter et de tester un mod. Les commandes claude s'exécutent dans votre shell et les commandes / dans le prompt de Claude Code. Dans le tableau, <directory> désigne un chemin que vous saisissez, comme dans claude plugin validate ./first-mod. Les crochets indiquent un argument facultatif.

Commande Effet
/plugin Affiche une ligne telle que 1 mod active · first-mod sous ses onglets lorsqu'un mod non intégré a été chargé
claude plugin validate <directory> Lit le manifeste et le module de hooks d'un plugin et signale les erreurs, les événements qu'il gère et les appels à l'API des mods qu'il effectue. --strict traite les avertissements comme des erreurs et --json affiche un rapport lisible par une machine.
claude plugin test [directory] Exécute chaque fichier du répertoire, ou du répertoire courant si vous n'en indiquez aucun, dont le nom se termine par .test.ts ou .test.tsx. Se termine avec le statut 1 lorsqu'un test échoue.
claude --plugin-dir <directory> Charge un répertoire de plugin pour une session et recharge son module de hooks lorsque vous enregistrez. Répétez le flag pour en charger plusieurs.
/reload-plugins Recharge les plugins lorsque vous l'exécutez