SpyBara
Go Premium

plugins/mods/reference.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 105 additions and 97 deletions.

2026
Fri 2 22:59 Sat 3 23:57 Sun 4 23:58 Tue 6 23:59 Wed 7 23:59 Thu 8 22:58 Fri 9 23:02 Sat 10 23:01 Sun 11 23:57 Wed 14 22:58 Thu 15 23:58 Fri 16 22:59 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22: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. Les entrées couvrent la CLI Claude Code et l'application Desktop à partir de la v2.1.290, ainsi que l'extension VS Code à partir de la v2.1.299. 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.

[!NOTE]

La référence complète est constituée des déclarations TypeScript pour les mods de Claude Code, qui décrivent chaque événement, méthode et élément, avec des exemples. La copie sur GitHub peut être plus ancienne que la version de Claude Code que vous avez installée. En cas de divergence, fiez-vous à la copie que Claude Code écrit pour votre version.

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 Dans un gestionnaire .catch uniquement. kind vaut throw ou timeout lorsque le hook a échoué, et message est le texte de l'erreur. kind vaut re-entry lorsque le hook a été ignoré parce que l'événement provenait d'un appel à l'API des mods effectué par ce hook ou par le code de votre mod en dehors de ses hooks. re-entry nécessite Claude Code v2.1.292 ou une version ultérieure.
next.error.cause Défini uniquement lorsque kind vaut re-entry. rewritten si un hook tool.call ou PreToolUse a modifié l'appel à l'API des mods dont provenait l'événement, ou si un hook agent.spawn a modifié un agent démarré par cet appel. lent lorsqu'une méthode qu'un autre mod ajoute à l'API des mods a déclenché cet événement, sauf si rewritten s'applique également. lent nécessite Claude Code v2.1.292 ou une version ultérieure, et rewritten la v2.1.300 ou une version ultérieure.
next.called Dans un gestionnaire .catch uniquement. true lorsque le hook 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. next(e) ou { decision }, avec decision défini sur allow, ask ou deny et un reason facultatif
tool.describe Une fois pour chaque outil, lorsque sa description est envoyée à Claude pour la première fois. Une seconde fois pour un outil MCP lorsque Claude le charge via la recherche d'outils, avec e.description défini sur le texte que Claude lit pour l'outil chargé. { description }, avec éventuellement isDeferred défini sur true pour placer l'outil derrière la recherche d'outils ou sur false pour le charger dès le départ

Champs d'agent et d'organisation sur tool.check

Dans un hook tool.check, lisez ces champs pour distinguer l'appel d'un sous-agent de celui de la conversation principale, et pour savoir si votre organisation exige une approbation pour un outil de connecteur :

Sur tool.check, e.agentId et e.ceiling nécessitent Claude Code v2.1.290 ou une version ultérieure.

Le champ e.isReadOnly sur tool.check

Dans un hook tool.check, e.isReadOnly vaut true lorsque l'outil signale cet appel comme étant en lecture seule. Sinon, le champ est absent, et ne vaut pas false. La valeur correspond au propre signalement de l'outil : lisez donc Vérifier si un appel d'outil est en lecture seule avant d'approuver un appel sur la seule base de ce champ.

Sur tool.check, e.isReadOnly nécessite Claude Code v2.1.304 ou une version ultérieure.

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.autocomplete L'utilisateur saisit du texte dans la zone de prompt et un mot se termine au niveau du curseur. e.token est ce mot. Claude Code n'attend pas le hook : ses propres lignes d'autocomplétion s'affichent en premier. { suggestions }, une liste de lignes { text, label, description } affichées sous celles de Claude Code. Choisir une ligne remplace le mot par son text.
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
prompt.mention Claude Code est sur le point de lire un fichier qu'un prompt mentionne avec @. Nécessite Claude Code v2.1.290 ou une version ultérieure. next({ ...e, path }) pour lire un autre fichier, ou { deny: reason }
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 }

Champs de source et de frontmatter sur skill.prompt

Dans un hook skill.prompt, vous pouvez lire ces champs, en plus du nom du skill dans e.skill et du texte que Claude lit dans e.text :

Champ Type Contenu
e.source string Qui fournit le skill : policySettings, userSettings ou projectSettings pour un skill situé respectivement à l'emplacement entreprise, personnel ou projet. Les autres sources donnent un mot tel que plugin, mcp, syncedSkills ou built-in.
e.pluginName string Le nom du plugin, pour un skill dont e.source vaut plugin
e.path string Le chemin absolu du fichier SKILL.md du skill, ou de son fichier .md pour un skill écrit sous forme de fichier de commande. Absent lorsque le skill n'a aucun fichier sur cette machine, comme c'est le cas pour un skill intégré.
e.frontmatter object Le frontmatter du fichier du skill, sous forme de données simples
e.frontmatterProblem string La raison pour laquelle il manque à e.frontmatter le frontmatter du fichier ou l'une de ses clés, comme dans is a list or a single value, not a table. Absent lorsque e.frontmatter contient l'intégralité du frontmatter ou que le skill n'en a pas.

Un hook peut transmettre un text ou un frontmatter modifié à next : les hooks qui le suivent lisent les deux, et Claude lit le text final. Un hook qui modifie tout autre champ échoue.

Sur skill.prompt, e.source, e.pluginName, e.path, e.frontmatter et e.frontmatterProblem nécessitent Claude Code v2.1.299 ou une version ultérieure.

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 }) avec un message.content modifié, pour réécrire les blocs de texte de la ligne ou le content d'un bloc tool_result qu'elle contient
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 ou un coéquipier d'une équipe d'agents 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 ou un coéquipier d'une équipe d'agents est sur le point de démarrer. Pour un coéquipier, e.isTeammate vaut true. next({ ...e, model }) pour choisir son modèle, ou { deny: reason }

Lorsque Claude reprend un sous-agent avec l'outil SendMessage, votre hook agent.spawn ne s'exécute pas à nouveau. Pour refuser les appels SendMessage qui reprennent un sous-agent, ciblez cet outil dans un hook tool.call.

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
ui.fault Un élément Client dessiné par votre mod n'a pas pu se charger, se dessiner ou s'exécuter. e.phase vaut load, render ou run, et e.reason est le message d'erreur. Nécessite Claude Code v2.1.289 ou une version ultérieure.

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. Un mod en dehors du niveau user peut également en retenir un.

Lorsque le hook d'un autre mod appelle une méthode sur un namespace que vous avez ajouté dans engine.create, les appels $ de votre méthode s'exécutent dans le contexte de ce hook jusqu'à ce que chaque hook sur cet événement ait renvoyé son résultat. Par exemple, un chemin relatif est résolu par rapport au répertoire de travail de ce hook, et $.prompt.submit est rejeté tant que le tour attend ce hook. Les appels que votre méthode effectue ensuite s'exécutent dans le contexte propre de votre mod.

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, notify, status, log, notice, ask, copy, selection, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list. list() renvoie les sous-agents et coéquipiers de cette session, chacun avec un status parmi pending, running, waiting, idle, completed, failed ou killed, où idle et waiting nécessitent Claude Code v2.1.289 ou une version ultérieure.
$.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 indique l'application qui dessine, par exemple terminal, desktop ou vscode. 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.

Le rendu dans l'extension VS Code nécessite la version 2.1.299 ou ultérieure de l'extension. Une session qui ne récupère pas les feature flags nécessite la version 2.1.304 ou ultérieure. Dessiner dans l'extension VS Code liste ce que l'extension dessine différemment.

Point de rendu e.props e.requestId Affiché dans
Pane title, isFocused, bodyColumns, placement, scroll, view L'id du volet Terminal, Desktop, VS Code
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, VS Code
AssistantMessage Le texte de la réponse L'id du message Terminal, Desktop, VS Code
ToolUse, ToolResult, ToolGroup Le nom, l'entrée et le résultat de l'outil L'id de l'appel d'outil Terminal, Desktop, VS Code
CommandOutput command, text L'id du message Terminal, Desktop
AskUserQuestion La question et les options L'id de l'appel d'outil Terminal, Desktop, VS Code
ToolProgress kind L'id de l'appel d'outil Terminal
Spinner word, message, suffix, mode L'id de l'agent Terminal, Desktop, VS Code
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. Dans le terminal et l'application Desktop, il est absent tant que l'application n'a pas mesuré sa fenêtre. Dans ces applications, son rows correspond à la hauteur de la fenêtre entière, et non à celle de votre volet. Dans l'extension VS Code, il est toujours présent.

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 pour votre arbre
  • 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 correspond à cette limite. 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 VS Code
Box key, disposition flex, gap, padding, margin, width, height, minWidth, minHeight, borderStyle, borderColor, borderDimColor, backgroundColor, position, top, left, right, bottom, overflow, display, hover ✓ ✓ ✓
Text color, backgroundColor, bold, italic, underline, strikethrough, dimColor, inverse, wrap, size, weight, mono, tabular, hover ✓ ✓ ✓
Button key, label, onPress, hotkey, plain, dimColor, autoFocus, action, hover ✓ ✓ ✓
Link href, label. Consultez Limites. ✓ ✓ ✓
Code source, language, path, startLine, format, wrap ✓ ✓ ✓
Markdown text, key, dimColor, onLinkPress, pressableLinks ✓ ✓ ✓
Input key, label, placeholder, value, submitLabel, onSubmit, onInput, autoFocus ✓ ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓ ✓
Svg Une source de balisage SVG jusqu'à 131 072 caractères, un texte alt, width, height et isInteractive ✓ ✓
Client module, key, props, width, height, flexGrow ✓ ✓
Raster key, columns jusqu'à 512, rows jusqu'à 256, cells. Consultez Dessiner une grille de cellules colorées. ✓
Image key, une source telle que des octets PNG ou RGBA jusqu'à 2 Mio, ou un chemin de fichier, columns et rows jusqu'à 255, et un texte alt. Consultez les terminaux qui le dessinent. ✓

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
  • Hotkeys numériques dans le bandeau : 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
  • Un bandeau réduit : tant que le bandeau est réduit, ni un raccourci action ni un hotkey ne presse un bouton qu'il contient
  • Deux boutons sur un même hotkey : 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.

L'extension VS Code ignore certaines props d'éléments et dessine l'élément comme si vous les aviez omises :

  • Box : position avec ses top, left, right et bottom, alignSelf, borderDimColor et hover
  • Text : size, mono, tabular et hover
  • Button : hotkey, plain, autoFocus, action et hover ; l'utilisateur y presse donc un bouton d'un clic, ou avec Entrée une fois que le bouton a le focus
  • Code : language, path, startLine, format et wrap ; le code est donc dessiné sans couleurs ni numéros de ligne, et un bloc format: 'diff' affiche le texte brut du diff
  • Input et Select : autoFocus
  • Svg : isInteractive

Styles de bordure de Box

Pour dessiner une bordure autour d'une Box, définissez sa prop borderStyle sur l'un de ces noms, comme dans borderStyle: 'round'. Chaque ligne indique ce que le terminal dessine pour ce nom et montre le bord supérieur de la bordure.

borderStyle Ce que dessine le terminal Bord supérieur
'single' Traits fins avec des coins carrés ┌──┐
'double' Traits doubles ╔══╗
'round' Traits fins avec des coins arrondis ╭──╮
'bold' Traits épais ┏━━┓
'singleDouble' Traits fins en haut et en bas, traits doubles sur les côtés ╓──╖
'doubleSingle' Traits doubles en haut et en bas, traits fins sur les côtés ╒══╕
'classic' Les caractères ASCII +, - et | +--+
'arrow' Des flèches qui pointent vers l'intérieur de la Box ↘↓↓↙
'dashed' Traits en pointillés avec des coins vides ╌╌
'quote' Une barre, ▎, le long du côté gauche et des cellules vides sur les trois autres côtés Vide

Une Box dont la prop borderStyle désigne tout autre nom, comme 'rounded', est dessinée sans bordure.

Pas d'espacement de Box

Les props d'espacement de Box sont gap, columnGap, rowGap, padding, margin, ainsi que les formes de padding et margin portant sur un seul côté ou un seul axe, comme paddingX et marginTop. Chacune accepte un nombre de cellules du terminal, comme gap: 1, ou un nom de pas, comme gap: 'md'. Dans le terminal et l'extension VS Code, chaque pas correspond au nombre de cellules suivant :

Pas Cellules en largeur Cellules en hauteur
'xs' 1 0
'sm' 1 0
'md' 2 1
'lg' 3 1
'xl' 4 2

Si vous définissez gap, padding ou margin sur un pas, celui-ci s'applique à la fois en largeur et en hauteur. Par exemple, dans le terminal et l'extension VS Code, padding: 'md' correspond à deux cellules de chaque côté et à une ligne au-dessus et en dessous.

Les noms de pas nécessitent Claude Code v2.1.299 ou une version ultérieure. Sur une version antérieure, Claude Code dessine sa propre version du site à la place d'un arbre qui utilise un nom de pas.

Props typographiques de Text

Définissez size, weight, mono ou tabular sur un Text pour demander à l'application qui dessine votre arbre une taille de texte, une graisse, une police à chasse fixe ou des chiffres de largeur égale. Avant de vous appuyer sur une prop, vérifiez ce qu'en font le terminal et l'extension VS Code. Si une application ignore une prop que vous avez définie, votre arbre y est tout de même dessiné, avec le texte tel qu'il serait si vous aviez omis cette prop.

Prop Valeurs Dans le terminal Dans l'extension VS Code
size 'caption', 'footnote', 'body', 'heading' ou 'title' Ignorée : le terminal n'a qu'une seule taille de texte Ignorée
weight 'regular', 'medium', 'semibold' ou 'bold' semibold et bold sont dessinées en gras semibold et bold sont dessinées en gras
mono true pour demander la police à chasse fixe de l'application Ignorée : le terminal est toujours à chasse fixe Ignorée, le texte conserve donc la police propre à l'extension
tabular true pour demander des chiffres de largeur égale, afin qu'un nombre mis à jour sur place ou une colonne de nombres reste aligné Ignorée : les chiffres du terminal occupent déjà une cellule chacun Ignorée

Ces quatre props nécessitent Claude Code v2.1.299 ou une version ultérieure. Sur une version antérieure, Claude Code dessine sa propre version du site à la place d'un arbre qui définit size, weight, mono ou tabular.

Remplacer bold par weight

bold sur un Text est déprécié au profit de weight et fonctionne toujours. Pour le remplacer sur un Text sans weight, changez bold: true en weight: 'semibold' pour obtenir le même résultat sur Claude Code v2.1.299 ou une version ultérieure.

Sur une version antérieure à v2.1.299, un arbre qui définit weight n'est pas dessiné, et Claude Code dessine sa propre version du site à la place. Si vous définissez à la fois bold et weight sur un Text, bold n'a aucun effet.

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.

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, ou 50 millisecondes pour un hook prompt.edit
Le temps d'exécution d'un gestionnaire .catch 1 seconde
L'ensemble des hooks session.end Aussi longtemps que le budget du hook SessionEnd, soit 1,5 seconde sauf si vous le modifiez, compté à partir du moment où les hooks SessionEnd de vos paramètres se terminent
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
Le corps de la requête d'un $.http.fetch 4 Mio, comptés en caractères. Un appel avec un corps plus volumineux est rejeté.
Le corps de la réponse d'un $.http.fetch 4 Mio. text contient les 4 premiers Mio et le reste n'est pas lu. Lorsque l'en-tête Content-Length déclare davantage, l'appel est rejeté à la place, avec une raison qui se termine par is over the 4194304-byte limit, sauf lorsque la dernière requête après d'éventuelles redirections utilise la méthode HEAD. L'exemption HEAD nécessite Claude Code v2.1.296 ou une version ultérieure.
Un appel $.http.fetch, redirections et corps compris 30 secondes
Redirections suivies par un appel $.http.fetch 5
La raison drop d'un hook ou la raison deny de config.set 4 096 caractères. La fin d'une raison plus longue est tronquée, et le drop ou le deny s'applique quand même. La troncature nécessite Claude Code v2.1.292 ou une version ultérieure ; sur les versions antérieures, le hook échoue à la place.
Texte dans un arbre Les 100 000 premiers caractères sont dessinés
Le language ou le path d'un Code, la value d'une option Select, ou le module d'un Client 10 000 caractères. Si l'un d'eux est plus long, Claude Code dessine sa propre version du site.
Le href d'un Link 2 048 caractères. Un href plus long empêche le dessin de l'arbre entier.
$.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
Portées, telles que les fonctions, les blocs et les boucles, imbriquées les unes dans les autres dans un même fichier d'un module de hooks 2 000
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, dans une session dont les identifiants ne proviennent pas d'un /login 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 exécutent leurs hooks. 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 dans une session dont les identifiants proviennent d'un /login 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