Passer au contenu principal
Un mod peut dessiner sa propre interface dans Claude Code et modifier des parties de l’interface que Claude Code dessine déjà. Chaque endroit où un mod peut dessiner s’appelle un site de rendu, comme un volet, la bande au-dessus de l’invite, ou le spinner. Claude Code déclenche l’événement ui.render chaque fois qu’il s’apprête à dessiner un site de rendu, et votre hook pour cet événement retourne ce qu’il faut dessiner là. Cette carte montre où un mod peut dessiner dans une session de terminal : Carte d'une session de terminal Claude Code en rendu plein écran. Un mod peut ajouter un volet comme barre latérale à droite, un toast en haut à droite de la transcription, une ligne de journal dans la transcription, une bande au-dessus de l'invite, et une barre de statut sous l'invite. Un mod peut redessiner les messages, les lignes d'appels d'outils, et le spinner. L'invite est celle de Claude Code. Carte d'une session de terminal Claude Code en rendu plein écran. Un mod peut ajouter un volet comme barre latérale à droite, un toast en haut à droite de la transcription, une ligne de journal dans la transcription, une bande au-dessus de l'invite, et une barre de statut sous l'invite. Un mod peut redessiner les messages, les lignes d'appels d'outils, et le spinner. L'invite est celle de Claude Code. Dans un terminal plus étroit, le volet se trouve au-dessus de l’invite au lieu d’être à côté de la transcription. Créez votre premier mod avant de commencer ici. Commencez par l’exemple travaillé, qui crée un volet avec deux onglets et un compteur, puis lisez la section pour chaque élément que vous voulez modifier.
Pour rechercher une prop ou une limite, consultez la référence.

Construire un volet avec des onglets

Dans cette section, vous construisez un mod qui ajoute une commande /hello-tabs, et la commande ouvre un volet. Un volet est une barre latérale à côté de la transcription dans un terminal plein écran large, ou une région encadrée au-dessus de l’invite sinon. Ce volet affiche deux onglets, et le deuxième onglet a un bouton qui ajoute un au compteur. Le compte est toujours là après que vous redémarriez Claude Code. Le mod fini ressemble à ceci. L’enregistrement ouvre le volet, bascule vers le deuxième onglet, appuie sur le bouton quelques fois, et revient au premier onglet :
Les onglets sont deux boutons dans une ligne. Le mod garde la trace de celui qui est actif et dessine le contenu de cet onglet sous la ligne.
1

Créer le plugin

Un mod est un plugin avec un manifeste, un hooks.json qui pointe vers votre code, et le fichier de code. Créer un mod explique chacun. Créez un répertoire nommé hello-tabs avec des répertoires .claude-plugin et hooks à l’intérieur, puis enregistrez les deux premiers fichiers.Enregistrez le manifeste sous hello-tabs/.claude-plugin/plugin.json :
hello-tabs/.claude-plugin/plugin.json
Nommez votre point d’entrée dans hello-tabs/hooks/hooks.json :
hello-tabs/hooks/hooks.json
2

Écrire le code

Cette liste indique ce que fait chaque hook, dans l’ordre où ils apparaissent dans le code :
  • Ajoute la commande /hello-tabs et charge le compte qu’une session précédente a sauvegardé
  • Ouvre le volet quand vous exécutez cette commande
  • Dessine le contenu du volet : la ligne d’onglets et le corps de l’onglet ouvert
Deux variables au niveau du module, tab et count, conservent l’état du volet.Enregistrez ceci sous hello-tabs/hooks/register.js :
hello-tabs/hooks/register.js
Chaque hook fait aussi quelque chose que le code ne rend pas évident :
  • session.start lit aussi le compte sauvegardé depuis $.store, un magasin clé-valeur qui persiste entre les sessions.
  • command.run dit seulement à Claude Code que le volet existe. Ouvrir un volet ne dessine rien par lui-même : Claude Code déclenche ensuite ui.render pour demander ce qu’il faut y mettre.
  • ui.render retourne l’arbre d’éléments, une Box qui contient d’autres boîtes, du texte et des boutons, et le construit à nouveau à partir de tab et count chaque fois qu’il s’exécute.
Appuyer sur un bouton exécute son callback onPress, qui change une variable et appelle redraw. Claude Code exécute ensuite le hook ui.render à nouveau, et le hook construit un nouvel arbre à partir des nouvelles valeurs. Chaque dessin interactif utilise ce cycle de rendu : un callback change l’état, et le hook dessine à nouveau à partir du nouvel état.
3

Ouvrir le volet

Dans votre shell, démarrez Claude Code avec claude --plugin-dir ./hello-tabs. À l’invite Claude Code, exécutez /hello-tabs. Un volet s’ouvre avec 1: One et 2: Two en haut. Appuyez sur 2, puis appuyez sur a, la touche de raccourci pour Add one, quelques fois. Le compte augmente.
4

Vérifier que le compte a été sauvegardé

Appuyez sur Esc pour fermer le volet, puis quittez la session. Dans votre shell, démarrez Claude Code à nouveau avec la même commande claude --plugin-dir ./hello-tabs, et à l’invite Claude Code exécutez /hello-tabs. Le compte est où vous l’avez laissé.Pour effacer le compte, faites appeler au mod $.store.delete('count'). Conserver l’état couvre combien de temps chaque type de valeur dure.

Choisir où dessiner

Pour choisir le point de rendu dans lequel un hook ui.render dessine, passez un filtre, appelé matcher, comme second argument de on. { component: 'Pane' } n’exécute le hook que pour les panneaux. Dans le hook, e.component nomme le point de rendu, e.surface indique quelle application dessine, et e.props contient les données propres au point de rendu. Pour un panneau, e.requestId est l’id avec lequel vous l’avez ouvert. Le panneau et la bande restent vides tant qu’un mod ne les remplit pas. Sélectionnez un onglet pour découvrir ce qu’est chacun d’eux et comment y dessiner :
Un panneau est une barre latérale à côté de la transcription dans un terminal large en plein écran, ou sinon une zone encadrée au-dessus du prompt. Lorsque plusieurs panneaux sont ouverts, chacun dispose d’un onglet qui affiche son titre.Un panneau apparaît lorsque votre mod appelle $.ui.open avec un id de votre choix, comme dans $.ui.open({ id: 'hello-tabs' }). Ouvrir un panneau au bon moment présente les autres champs et explique quand un panneau attend un terminal plus large.Pour dessiner dans votre panneau, filtrez sur { component: 'Pane' } et vérifiez que e.requestId correspond à votre id.
Un mod peut aussi placer sa propre ligne dans la transcription.

Modifier ce que Claude Code dessine déjà

Claude Code dessine lui-même la plupart de son interface : les messages, les lignes d’appels d’outils, le spinner, et plus encore. Chacune de ces parties est aussi un point de rendu, qu’un mod peut donc restyler ou remplacer. Pour en modifier une, filtrez votre hook ui.render sur son nom tiré de ce tableau : Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage et les points de rendu des appels d’outils fonctionnent dans le terminal, l’application Desktop et l’extension VS Code. Le tableau des points de rendu indique où chacun des autres est déclenché. Sur un point de rendu que Claude Code dessine déjà, votre hook peut modifier un détail, remplacer le dessin ou le laisser tel quel. Sélectionnez un onglet pour voir chaque cas appliqué au spinner. Les exemples lisent une variable calls qu’un autre hook incrémente, comme dans le mod du tutoriel.
Pour conserver le dessin de Claude Code et en modifier une partie, passez à next une copie de l’événement avec des props modifiées. Ce hook modifie le texte qui suit le mot du spinner :
Le spinner conserve son animation et son mot, et votre texte suit le mot :
Sur ces points de rendu, next(e) renvoie une référence au dessin de Claude Code, { type: 'engine', ref }, sauf si un mod exécuté après le vôtre a renvoyé son propre arbre. Pour modifier le contenu de ce dessin, passez à next une copie de l’événement avec des props différentes, comme le fait l’onglet Modifier un détail. Vous pouvez renvoyer la référence telle quelle, ou la placer dans une Box à côté de vos propres éléments :
Pendant que Claude travaille, le spinner s’anime comme avant, et under the spinner apparaît en dessous. La demande de permission n’est pas un point de rendu, un mod ne peut donc pas modifier ce qu’elle affiche. La boîte de dialogue de question, AskUserQuestion, en est un, un mod peut donc modifier cette boîte de dialogue lorsque Claude pose une question. Un arbre pour cette boîte de dialogue doit contenir la référence exactement une fois, avec vos éléments au-dessus. Sinon, Claude Code dessine sa propre boîte de dialogue.

Ouvrir un panneau au bon moment

Un panneau n’apparaît que lorsque votre mod l’ouvre. La manière et le moment où vous l’ouvrez déterminent s’il prend le focus clavier, l’espace qu’il demande, et s’il s’affiche ou non dans un terminal étroit. Pour ouvrir un panneau, appelez $.ui.open avec un id de votre choix. L’id est le nom du panneau : votre hook ui.render le vérifie, et vous le repassez pour fermer le panneau. Si un autre mod a un panneau ouvert avec cet id, l’appel est rejeté.
Pour fermer le panneau, appelez $.ui.close avec l’id avec lequel vous l’avez ouvert :
Outre id, $.ui.open accepte ces champs facultatifs : L’extension VS Code ignore rows et columns et dimensionne elle-même le panneau. focus, closeOnEscape et holdToasts sont facultatifs et n’acceptent que true. Pour ne pas en utiliser un, omettez-le. Passer false lève une erreur telle que ui.open: focus is true or left out. Pour en définir un de manière conditionnelle, n’ajoutez le champ que lorsque la condition est remplie. Cet appel ne demande le focus clavier que lorsque items n’est pas vide :
Pour permettre à une commande d’ouvrir le panneau pendant que Claude travaille, ajoutez immediate: true lorsque vous enregistrez la commande. Sans cela, une commande saisie pendant un tour attend la fin du tour.

Retenir les toasts derrière une boîte de dialogue

Passez holdToasts: true à $.ui.open lorsque le panneau est une boîte de dialogue à laquelle l’utilisateur répond avant de la quitter, afin que les toasts n’apparaissent pas pendant qu’il décide. Dans le terminal, la retenue dure tant que ce panneau est celui qui est affiché, et un toast déclenché pendant ce temps attend la fin de la retenue. Claude Code retient les toasts des autres mods et ses propres notifications éphémères, ainsi que ceux que votre mod déclenche avec $.ui.toast. N’utilisez pas ce champ pour un panneau qui reste ouvert, afin que l’utilisateur continue de les voir.

Quand un panneau attend un terminal plus large

Un panneau que votre mod ouvre sans qu’on le lui demande n’apparaît pas dans un terminal étroit, afin qu’il ne puisse pas accaparer un petit écran. Son affichage dépend de ce qui l’a ouvert :
  • Ouvert par une action de l’utilisateur, comme une commande qu’il a exécutée ou un bouton sur lequel il a appuyé, le panneau apparaît quelle que soit la largeur
  • Ouvert par votre mod de sa propre initiative, par exemple depuis un minuteur ou un hook turn.start, le panneau n’apparaît que dans un terminal d’au moins 144 colonnes de large. Une fois que l’utilisateur a lui-même ouvert ce panneau, 110 colonnes suffisent.
Lorsque le panneau apparaît, $.ui.open se résout en { isPlaced: true }. Lorsque le panneau est en attente, isPlaced vaut false et reason est une chaîne qui en indique la raison. Un panneau en attente apparaît lorsque l’utilisateur l’ouvre ou élargit le terminal. Pour signaler qu’un élément est disponible sans ouvrir de panneau, appelez $.ui.toast('Your message'), qui affiche une notification toast.

Dessiner dans l’extension VS Code

Dans l’extension VS Code, ce qu’un mod dessine apparaît dans le panneau de chat à partir de la version 2.1.299 de l’extension. Une session qui ne récupère pas les feature flags, comme une session sur Amazon Bedrock, nécessite la version 2.1.304 ou ultérieure. Dans un hook ui.render pour le panneau, e.surface vaut vscode. Pour vérifier quels points de rendu et éléments le panneau dessine, et quelles props il ignore, consultez les tableaux des points de rendu et des éléments. Pour qu’un mod fonctionne dans le panneau aussi bien que dans le terminal, tenez compte de ces différences :
  • Panneaux : dans un panneau de 800 pixels de large ou plus, les panneaux s’ancrent à côté de la conversation, e.props.placement vaut 'dock' et e.viewport.isFullscreen vaut true. Dans un panneau plus étroit, les panneaux se dessinent au-dessus de la zone de prompt, placement vaut 'inline', et un panneau affiche 12 lignes avant de défiler.
  • Toasts et barres de statut : ils se trouvent dans une seule pile juste au-dessus de la zone de prompt, avec les panneaux lorsque le panneau est étroit, avec une barre de statut par mod. La pile est masquée pendant l’affichage d’une demande de permission ou d’une boîte de dialogue.
  • Libellés : le panneau encadre ce qu’un mod dessine ou réécrit et l’étiquette avec le nom du plugin, comme dans From the token-chart plugin ou Edited by the token-chart plugin.
  • Clavier : les boutons n’ont pas de raccourcis clavier, l’utilisateur clique donc sur un bouton ou appuie sur Enter une fois que celui-ci a le focus.
  • Focus clavier : le panneau n’accorde la demande focus: true d’un panneau que lorsque le panneau a le focus, que Claude est inactif sans question en attente, et que la zone de prompt est vide.
  • La boîte de dialogue de question : sur AskUserQuestion, le panneau conserve sa propre carte de question et dessine vos éléments au-dessus. Les props que vous passez à next ne modifient pas la carte.
  • Suggestions de prompt : $.prompt.suggest se résout avec isShown: false et n’affiche rien, car le panneau réserve le texte de suggestion estompé de la zone de prompt aux propres suggestions de Claude.
  • Limites de texte : le panneau coupe une barre de statut à 200 caractères ou deux lignes, et un toast à 500 caractères.

Placer une ligne dans la transcription

Une ligne est un élément que votre mod ajoute à la transcription dans le terminal, après le dernier message. Elle reste à cet endroit au fil de la conversation, et Claude ne la voit pas. $.ui.place nécessite Claude Code v2.1.314 ou ultérieur.
1

Placer la ligne

Appelez $.ui.place avec un id. L’id est un nom que vous inventez pour la ligne, comme build-status. Il peut comporter de 1 à 64 lettres, chiffres, _ ou -, et chaque ligne que votre mod a dans la transcription a besoin du sien.
2

Dessiner la ligne

Dessinez la ligne sur le point de rendu Placed.
Cet exemple ajoute une commande /build-status. Lorsque l’utilisateur exécute la commande, le mod ajoute une ligne qui affiche Build: passing. Le texte est fixe pour que l’exemple reste court ; un vrai mod dessinerait son propre résultat :
Pour essayer l’exemple, placez ce code dans un mod. Dans une session de terminal, exécutez /build-status dans le prompt de Claude Code. Build: passing apparaît sous forme de ligne à la fin de la transcription. L’appel n’affiche pas toujours de ligne, et une ligne peut disparaître plus tard ; gérez donc ces cas dans votre mod :
  • Le résultat : { isPlaced: true, requestId } lorsque le terminal dessine la ligne. Sinon, isPlaced vaut false et reason en indique la raison, comme dans no attached surface draws placed rows yet. L’une des raisons possibles est la limite du nombre de lignes qu’un mod peut avoir en même temps.
  • Un second appel avec le même id : tant que la première ligne est encore dans la transcription, l’appel n’ajoute aucune ligne et se résout avec le requestId de cette ligne. Pour modifier ce qu’affiche la ligne, redessinez la ligne.
  • Quand la ligne disparaît : lorsque la conversation se termine, lorsque l’utilisateur revient en arrière au-delà de la ligne, ou, en dehors du rendu plein écran, lorsque la conversation est compactée. --resume ne rétablit pas la ligne. Pour afficher à nouveau la ligne, appelez de nouveau $.ui.place.

Placer un arrière-plan derrière la conversation

$.theme.set et $.theme.clear remplacent $.ui.backdrop, que Claude Code v2.1.319 a supprimé. Remplacez $.ui.backdrop({ id: 'your-backdrop' }) par un appel à $.theme.set semblable à celui de l’exemple de cette section, et $.ui.backdrop(undefined) par $.theme.clear(), qui supprime l’arrière-plan de n’importe quel mod.
Pour placer un arrière-plan derrière la conversation dans l’application Desktop ou l’application mobile, appelez $.theme.set avec un backdrop, puis dessinez l’arrière-plan sur le point de rendu Backdrop. Pour retirer l’arrière-plan, appelez $.theme.clear(). Le terminal ne dessine aucun arrière-plan. $.theme.set et $.theme.clear nécessitent Claude Code v2.1.319 ou ultérieur. Cet exemple nécessite Claude Code v2.1.323 ou ultérieur ; vérifiez donc votre version au préalable. Le mod définit un arrière-plan au démarrage de la session, dessine l’arrière-plan et ajoute une commande /plain qui retire l’arrière-plan :
Avant la v2.1.323, écrivez id à la place de scene dans l’appel à $.theme.set et dans e.props, et déplacez overrideColorScheme dans backdrop sous le nom colorScheme.
Pour essayer l’exemple, placez ce code dans un mod et démarrez une session dans l’application Desktop ou l’application mobile. Pour retirer l’arrière-plan, exécutez /plain dans le prompt de Claude Code. La transcription affiche the theme is cleared après le nom du mod, comme dans night-sky: the theme is cleared pour un mod nommé night-sky. Vérifiez ce qu’accepte backdrop, ce que vous indique le résultat de l’appel, et ce que les autres mods peuvent modifier :
  • Les champs de backdrop : scene est un nom que vous choisissez pour un arrière-plan que votre hook dessine. Pour les autres champs et overrideColorScheme, consultez les types de votre build.
  • Si l’arrière-plan est dessiné : $.theme.set se résout avec isDrawn: true lorsqu’une application Desktop ou mobile connectée à la session indique qu’elle dessine les arrière-plans. Sinon, isDrawn vaut false et reason en indique la raison.
  • Un seul thème par session : un mod qui appelle $.theme.set remplace l’arrière-plan et les couleurs de la session, et un mod qui appelle $.theme.clear() les supprime, quel que soit le mod qui les a définis. N’appelez $.theme.clear() que lorsque l’utilisateur le demande.

Modifier les couleurs de l’application Desktop

Pour modifier les couleurs de l’onglet Code de l’application Desktop avec un mod, demandez-en un à Claude ou écrivez-le vous-même. Les deux méthodes nécessitent Claude Code v2.1.324 ou ultérieur dans l’onglet Code ; vérifiez donc la version à cet endroit au préalable. Claude Code dans le terminal conserve ses propres couleurs.

Demander un mod de couleurs à Claude

1

Décrire les couleurs

Démarrez une session locale dans l’onglet Code et indiquez à Claude les couleurs que vous souhaitez. Par exemple, saisissez make a mod that makes the app cream in light mode and dark brown in dark mode. Claude écrit les fichiers du mod.
2

Approuver le mod

Répondez aux questions que Claude Code pose sur les fichiers du mod et le rechargement à chaud. Pour connaître l’effet de chaque réponse, consultez Demander un mod à Claude.
3

Vérifier les couleurs

L’onglet Code change de couleur lorsque le mod se charge. Pour ajuster une couleur, indiquez à Claude ce qu’il faut modifier. Si rien ne change, consultez Corriger les couleurs de mod manquantes.

Écrire un mod de couleurs vous-même

makeColors est une fonction qui construit un thème à partir de quelques couleurs hexadécimales. Ces étapes créent un mod nommé paper qui l’utilise.
1

Faire copier makeColors par Claude

Démarrez une session locale dans l’onglet Code, et saisissez copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/. Vérifiez que les deux fichiers se trouvent dans ce répertoire.
2

Enregistrer le manifeste et hooks.json

À partir de Écrire un mod vous-même, enregistrez .claude-plugin/plugin.json et hooks/hooks.json dans ~/.claude/skills/paper/, et remplacez first-mod par paper dans les deux fichiers. Un mod placé sous ~/.claude/skills/ se charge lorsque vous démarrez une session.
3

Écrire le code

Enregistrez ce fichier sous ~/.claude/skills/paper/hooks/register.js. Au démarrage d’une session, le code appelle $.theme.set avec les couleurs pour le mode clair et le mode sombre :
Pour utiliser vos propres couleurs, remplacez les valeurs hexadécimales par d’autres couleurs hexadécimales à six chiffres.
4

Vérifier les couleurs

Démarrez une nouvelle session locale dans l’onglet Code. Avec les valeurs de l’exemple, l’arrière-plan est crème en mode clair et brun foncé en mode sombre. Si rien ne change, consultez Corriger les couleurs de mod manquantes.

Corriger les couleurs de mod manquantes dans l’application Desktop

Si vous utilisez un fournisseur tiers au lieu d’un compte Claude dans Claude Desktop v5.11492.5 ou antérieur, l’onglet Code conserve ses propres couleurs ; ignorez donc ces vérifications. Sinon, si les couleurs d’un mod n’apparaissent pas dans l’onglet Code, ou si elles disparaissent, recherchez ces causes :
  • Version obsolète : mettez à jour l’application Desktop, redémarrez-la, et démarrez une nouvelle session locale dans l’onglet Code. Si Claude a écrit le mod, redemandez-le-lui dans cette session.
  • Mod non chargé : si Claude a écrit le mod, consultez à quel moment il se charge dans Demander un mod à Claude. Si vous l’avez écrit, comparez vos fichiers et leurs chemins avec Écrire un mod de couleurs vous-même.
  • Thème refusé : demandez à Claude d’exécuter l’appel makeColors du mod. Si l’appel lève une erreur, ou si sa liste problems contient une entrée commençant par Desktop won't paint this theme, faites corriger le thème par Claude. Si vous avez installé le mod, envoyez ce que Claude trouve à son auteur.
  • Un autre appel $.theme : lorsqu’un mod de la session appelle $.theme.set ou $.theme.clear(), les couleurs et l’arrière-plan d’un appel antérieur disparaissent. Dans votre propre mod, passez colors et backdrop dans le même appel à $.theme.set. N’utilisez qu’un seul mod à la fois qui définit un thème.

Supprimer les couleurs de mod de l’application Desktop

Pour retirer les couleurs d’un mod de l’onglet Code, désactivez d’abord le mod. Un mod encore activé peut redéfinir ses couleurs.
1

Désactiver le mod

2

Démarrer une nouvelle session

Démarrez une nouvelle session locale dans l’onglet Code.
3

Supprimer les couleurs qui persistent

Si les couleurs sont toujours présentes, ouvrez Settings depuis l’onglet Code, et recherchez-y code appearance. Ouvrez le résultat, et sélectionnez Remove colors.

Créer un arbre à partir d’éléments

Ce que renvoie un hook ui.render est un arbre d’éléments : une description de ce qu’il faut dessiner, composée de boîtes, de texte et de contrôles imbriqués les uns dans les autres. Vous décrivez le dessin, et Claude Code l’affiche dans l’application que l’utilisateur a ouverte : le terminal, l’application Desktop ou l’extension VS Code. Pour obtenir les éléments, appelez $.ui.resolve(e) dans votre hook, comme dans const { Box, Text, Button } = $.ui.resolve(e). Chaque élément est une fonction. Vous lui passez des props, et vous placez les éléments et les chaînes qui vont à l’intérieur dans children. Sélectionnez un onglet pour voir chacun des éléments les plus courants et la façon dont le terminal le dessine :
Text dessine une chaîne, avec un style facultatif tel que bold et color :
La galerie d’interface propose des exemples et des captures d’écran de la plupart des éléments. Ce tableau répertorie les principaux éléments : Si votre module est un fichier .tsx ou .jsx, vous pouvez écrire l’arbre en JSX. Déstructurez d’abord les éléments à partir de $.ui.resolve(e). Si votre dessin ne s’affiche pas, vérifiez que son arbre ne contient pas une prop qu’un élément n’accepte pas ou un enfant là où aucun n’est permis. Un hook qui renvoie un tel arbre échoue, et une ligne hook skipped nomme votre mod et la règle que l’arbre a enfreinte. Pour un Text dans un panneau avec une prop nommée bogusProp, cette ligne indique :
Dans l’application Desktop et l’extension VS Code, un Link s’affiche comme du texte brut, sauf si son href remplit ces conditions :
  • Schéma et hôte : une URL https:, ou une URL http://localhost telle que http://localhost:3000
  • Pas de @ : écrivez un @ dans le chemin ou la requête sous la forme %40
  • Orthographe : ce que renvoie new URL(href).href, à l’exception d’un / manquant après l’hôte. Cela exclut un hôte en majuscules, un espace et :443 sur une URL https:.
Dans le terminal, ces conditions ne s’appliquent pas.

Lorsqu’un Client échoue

Dans le terminal, lorsque le fichier exécuté par un Client échoue, une ligne grisée telle que my-mod: Client client/spinner.js: boom prend la place du Client, et le reste de votre dessin reste affiché. Si votre mod gère ui.fault, Claude Code redessine alors l’emplacement.

Dessiner une grille de cellules colorées

Pour une carte de chaleur, une sparkline ou un plateau de jeu dans le terminal, dessinez un seul Raster plutôt qu’un Box par cellule. Un Raster accepte une key, sa taille en columns et rows, et cells, une chaîne base64 qui regroupe toutes les cellules. Chaque cellule est composée de trois nombres : le point de code du caractère, sa couleur et sa couleur d’arrière-plan. Une couleur est une valeur RVB 24 bits en hexadécimal, par exemple 0xc62828 pour un rouge. La valeur 0x01000000, juste au-dessus de cette plage, désigne la couleur par défaut du terminal. Les applications autres que le terminal n’ont pas de Raster : vérifiez donc e.surface et dessinez du texte à la place. Ce corps de panneau dessine une carte de chaleur de trois sur deux :
Dans le terminal, le panneau affiche la grille : Un panneau dans le terminal contenant une petite grille de blocs colorés, deux rangées de trois. La rangée du haut est verte, ambre et rouge. La rangée du bas est verte, verte et ambre. Le tableau rows est la partie que vous modifieriez, et cellsOf le transforme en chaîne compactée. Le hook ne dessine que dans un panneau dont l’id est heat : ouvrez-en donc un avec $.ui.open({ id: 'heat' }) depuis une commande, comme l’exemple hello-tabs ouvre son panneau. Chaque caractère doit occuper une seule cellule de largeur. Pour animer un Raster déjà affiché à l’écran, appelez $.ui.blit avec l’id du panneau comme requestId, la key du Raster, la même taille et de nouvelles cellules. Pour cet exemple, cela donne $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Cet appel redessine cet unique élément sans exécuter à nouveau votre hook ui.render.

Réagir aux appuis et à la saisie

Lorsque l’utilisateur appuie sur un bouton, saisit du texte dans un champ ou choisit un élément dans une liste dessinée par votre mod, Claude Code appelle le callback de ce contrôle, qui s’exécute dans votre module. Chaque contrôle accepte ses propres callbacks :
  • Button : accepte onPress(e), où e.surface est l’application d’où provient l’appui
  • Input : accepte onSubmit(value) et onInput(value)
  • Select : accepte onSelect(value) avec ses choix dans options, une liste d’au moins un choix aux valeurs uniques, comme [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

Quels contrôles ont besoin d’une key

Donnez à chaque Input et Select une prop key, comme key: 'size'. Un Button peut se passer de key lorsqu’il possède une prop label ou un unique enfant de type chaîne. Sa clé est alors la valeur de label ou cette chaîne. Les tests et les autres mods identifient un contrôle par sa clé :
  • Tests : un test appuie sur un contrôle ou y saisit du texte via sa clé.
  • Autres mods : Claude Code déclenche ui.press, ui.input ou ui.select avec la clé du contrôle dans e.element avant d’exécuter le callback du contrôle. Le hook d’un autre mod peut aussi s’exécuter pour cet événement. Ce hook voit ce que l’utilisateur a saisi dans votre Input et peut modifier ce texte ou empêcher votre callback de s’exécuter. L’API des mods ne donne à ce mod aucune méthode pour appuyer sur vos boutons.
Si un message indique needs a key ou is drawn twice, trouvez la cause à partir de ce message.

Focus clavier et raccourcis

Votre mod ne lit jamais le clavier lui-même. L’utilisateur appuie sur une touche, Claude Code détermine à quel contrôle elle est destinée, et le callback de ce contrôle s’exécute. Hormis un raccourci numérique sur le bandeau ou une liaison action, cela ne se produit que lorsque votre panneau ou votre bandeau a le focus clavier. Le reste du temps, les touches vont au prompt. Dans l’extension VS Code, les boutons n’ont pas de raccourcis : l’utilisateur clique sur un bouton ou appuie sur Enter dessus, et saisit du texte dans les champs.

Comment un panneau obtient le focus clavier

Un panneau obtient le focus clavier lorsque :
  • Votre mod l’ouvre avec focus: true depuis une commande ou un appui
  • L’utilisateur appuie sur Ctrl+X puis Tab
  • L’utilisateur clique dessus, ce qui, dans le terminal, nécessite le rendu plein écran
Claude Code n’accorde focus: true que lorsque le prompt est vide et qu’aucun autre élément n’a le focus clavier. Un panneau qui s’ouvre pendant que l’utilisateur tape ne capture pas ses frappes.

Ce que fait chaque touche

Ce tableau indique ce que fait une touche lorsque votre panneau ou votre bandeau a le focus clavier : Un mod ne peut pas associer Tab ou les touches fléchées à autre chose ; un jeu se dirige donc avec w, a, s et d.

Définir un raccourci et le focus initial

  • hotkey : pour permettre à l’utilisateur d’appuyer sur un Button avec une seule touche, donnez-lui un hotkey d’un chiffre ou d’une lettre minuscule, comme dans hotkey: 'a'
  • autoFocus : pour choisir le contrôle qui a le focus à l’ouverture du panneau, ajoutez-lui autoFocus: true. Dans l’extension VS Code, autoFocus n’a aucun effet : le contrôle est dessiné comme si vous l’aviez omis, et vous n’avez rien à modifier. La prop n’accepte que true ; omettez-la donc sur les autres contrôles.
L’affichage d’un raccourci dépend du bouton et de l’application : Dans le terminal, nommez la touche dans le libellé d’un bouton entre crochets, ou utilisez plain: true, afin que l’utilisateur voie sur quoi appuyer. La référence des éléments présente les autres règles de Button : action, les raccourcis numériques sur le bandeau et deux boutons sur un même raccourci.

Lorsque l’utilisateur réduit le bandeau

Dans le terminal, lorsqu’un mod dessine dans le bandeau, l’utilisateur peut réduire le bandeau à une ligne pour le mettre de côté :
  • Cliquer sur [-] : lorsque le bandeau est développé, Claude Code dessine cette marque à l’extrémité droite de sa première ligne. En rendu plein écran, l’utilisateur clique dessus pour réduire le bandeau.
  • Appuyer sur Ctrl+X puis Ctrl+A : cela fonctionne que ce soit le prompt, le bandeau ou un panneau qui ait le focus clavier. L’utilisateur peut y associer d’autres touches via l’action abovePrompt:toggle.
Un bandeau réduit masque tout ce que les mods y dessinent et affiche à la place une ligne atténuée, qui nomme les touches permettant de le développer selon la configuration de l’utilisateur :
Les mêmes touches, ou en rendu plein écran un clic sur la ligne, développent à nouveau le bandeau. D’ici là, rien n’appuie sur un bouton qu’il contient : ni raccourci, ni chiffre saisi dans un prompt vide, ni raccourci clavier associé à l’action d’un bouton. Si le bandeau a le focus clavier lorsque l’utilisateur le réduit, le focus revient au prompt, et Ctrl+X puis Tab ignore le bandeau tant qu’il est réduit. Le bandeau reste réduit jusqu’à ce que l’utilisateur le développe, même après /clear, et il est de nouveau développé au prochain démarrage de Claude Code. Votre mod ne peut pas le développer. Ne faites pas du bandeau le seul endroit où votre mod affiche quelque chose auquel l’utilisateur doit répondre. Pour afficher cela ailleurs uniquement lorsque le bandeau est réduit, lisez e.props.isCollapsed dans votre hook ui.render, qui continue de s’exécuter. isCollapsed nécessite Claude Code v2.1.321 ou une version ultérieure.

Recevoir une saisie et dessiner une ligne par élément

De nombreux panneaux se composent d’un champ de texte avec une liste en dessous. L’exemple de cette section est un panneau de notes : vous tapez une note et appuyez sur Enter pour l’ajouter, et chaque note possède un bouton x qui la supprime. Avec deux notes ajoutées, le terminal dessine le panneau ainsi :
Le ✕ sur la bordure supérieure est la marque propre à Claude Code pour fermer le panneau. L’exemple utilise ces techniques :
  • Recevoir une saisie : un Input appelle onSubmit(value) avec le texte du champ lorsque l’utilisateur appuie sur Enter, et onInput(value) à chaque modification
  • Dessiner une liste : associez chaque donnée à une ligne, et donnez au bouton de chaque ligne sa propre key
Ce hook dessine le contenu du panneau :
Pour essayer le panneau :
  • Ajouter une note : tapez une ligne et appuyez sur Enter. La ligne apparaît comme une nouvelle ligne de la liste, et le champ se vide.
  • Supprimer une note : appuyez sur Tab jusqu’à ce que le bouton x de la note ait le focus, puis appuyez sur Enter. Le x est le libellé du bouton et non un raccourci ; taper la lettre n’appuie donc pas dessus.
Chaque modification suit le même cycle de rendu que hello-tabs : le callback modifie notes, appelle redraw et enregistre la liste dans $.store. Si votre hook redessine le panneau pendant que l’utilisateur tape une note, le champ conserve son texte tant que le hook transmet la même value à chaque fois. Pour remplacer son texte par le vôtre, transmettez une value différente. L’exemple enregistre les notes mais ne les charge pas. Pour les retrouver lors de la session suivante, lisez-les dans un hook session.start, comme hello-tabs lit count. Ces props composent la ligne du champ, Note: Type a note and press Enter ⏎ add : Soumettre un Input ne démarre pas de tour, sauf si votre callback appelle $.prompt.submit.

Redessiner un site

Un dessin est un instantané : il affiche ce que votre hook ui.render a retourné la dernière fois que le hook s’est exécuté. Pour afficher quelque chose de nouveau, le hook doit s’exécuter à nouveau. Claude Code l’exécute à nouveau pour certains changements, et votre mod demande le reste.

Quand Claude Code redessine sans être demandé

Claude Code exécute votre hook ui.render à nouveau quand les props du site changent ou la largeur du terminal change. Quand un Client du site échoue et que votre mod gère ui.fault, Claude Code exécute le hook une fois de plus après le retour de vos hooks ui.fault, afin que votre hook ui.render puisse omettre le Client. Il n’exécute pas le hook sur une minuterie, et il ne peut pas dire quand une variable dans votre module change.

Redessiner quand vos données changent

Pour avoir vos sites dessinés à nouveau après que vos propres données changent, appelez $.ui.invalidate('ui.render'). Ce volet compte les appuis. Le callback du bouton change count, puis demande un redessin :
Chaque appui augmente le nombre dans le volet. L’exemple hello-tabs enveloppe le même appel dans sa fonction redraw. Une valeur que vous gardez dans $.state n’a pas besoin de l’appel, car écrire la valeur redessine les sites qui la lisent.

Redessiner sur une minuterie

Pour garder une horloge, un compte à rebours, ou une valeur de l’extérieur de la session actuelle, redessinez selon un calendrier. Démarrez une minuterie dans le hook session.start du module. Si le module en a déjà une, comme hello-tabs le fait, ajoutez la ligne $.clock.every à celle-ci :
Claude Code exécute maintenant votre hook ui.render une fois par seconde. La minuterie s’arrête après le rechargement du module, et la nouvelle instance du module démarre la sienne.

À quelle fréquence un site peut redessiner

Claude Code limite la fréquence à laquelle il redessine un site, donc votre mod peut appeler $.ui.invalidate aussi souvent que ses données changent. Pour connaître la fréquence à laquelle chaque site peut redessiner, consultez le tableau des limites. Les appels qui viennent plus vite que la limite sont combinés en un redessin. Ce redessin exécute votre hook une fois, et le hook lit vos données telles qu’elles sont à ce moment, donc la valeur la plus récente s’affiche et les valeurs entre les deux ne s’affichent pas. Une animation ne peut pas s’exécuter plus vite que la limite.

Conserver l’état

L’endroit où un mod garde une valeur détermine combien de temps elle dure : jusqu’à ce que le module se recharge, jusqu’à ce que la session se termine, ou d’une session à l’autre. Choisissez selon la durée pendant laquelle la valeur doit durer : $.store.get(key) se résout en la valeur ou undefined, et $.store.set(key, value) prend n’importe quelle valeur JSON.

Garder une valeur dans $.state

$.state contient des valeurs pour la durée d’une session, et il redessine pour vous. C’est un état réactif : un hook ui.render qui lit une valeur s’y abonne, donc Claude Code redessine ce site chaque fois que vous écrivez la valeur, et vous n’appelez pas $.ui.invalidate. Une valeur dans $.state survit aussi à un rechargement du module, ce qu’une variable ne fait pas. Pour le configurer, déclarez vos valeurs, pointez votre manifeste vers la déclaration, puis définissez et utilisez chaque valeur. Les exemples déplacent le count de hello-tabs dans $.state.

Déclarer les valeurs

Déclarez les valeurs dans un fichier de déclaration de types. La clé externe est le nom de votre plugin, et chaque entrée en dessous est une valeur et son type. Enregistrez ceci sous hello-tabs/types/index.d.ts :
hello-tabs/types/index.d.ts

Pointer le manifeste vers la déclaration

Pour laisser claude plugin validate vérifier votre code par rapport à ce fichier, ajoutez un champ types au manifeste avec son chemin :
hello-tabs/.claude-plugin/plugin.json

Définir, lire et écrire une valeur

Dans votre module, définissez chaque valeur avec une valeur par défaut, lisez-la pendant le dessin, et écrivez-la à partir d’un callback. atom nomme une valeur et sa valeur par défaut, read la retourne, et update l’écrit. Les trois aides appellent $.state.get et $.state.set pour vous :
Parce que le hook ui.render a lu count, Claude Code exécute le hook à nouveau chaque fois que le bouton l’écrit. Ces règles s’appliquent au code :
  • Écrivez plugin et key comme des chaînes littérales : claude plugin validate les lit de votre source
  • Conservez le résultat de chaque appel atom dans une const : si vous déclarez count avec let, la validation échoue avec takes a source the scan can read
  • Déclarez chaque valeur dans le fichier de déclaration de types : sinon la validation échoue avec hello-tabs.count is not declared
  • Écrivez à partir d’un callback ou du hook d’un autre événement : un hook ui.render peut lire l’état et ne peut pas l’écrire, donc écrivez à partir de onPress, onSubmit, ou un hook pour un autre événement

Modifier hello-tabs pour utiliser $.state

Pour déplacer count dans hello-tabs dans $.state, modifiez chaque ligne qui l’utilise : Gardez redraw pour les boutons d’onglets, car tab est toujours une variable.

Charger une valeur sauvegardée à nouveau après /clear

Si votre mod copie une valeur sauvegardée de $.store dans $.state à session.start, il doit la copier à nouveau après /clear, /resume, ou /branch. Ces commandes remettent chaque valeur $.state à sa valeur par défaut, et session.start ne se déclenche pas à nouveau. classic.SessionStart se déclenche en revanche après chacune d’elles, avec e.source défini sur clear, resume, ou fork, donc copiez la valeur à nouveau dans un hook dessus. Sinon votre dessin affiche la valeur par défaut, et un callback qui enregistre la valeur $.state écrit la valeur par défaut sur ce que vous avez stocké. Ce code charge count à partir des deux hooks. Il s’appuie sur la version $.state de hello-tabs, où count est un atome et update est importé. Mettez loadCount au-dessus de register, et ajoutez l’appel loadCount au hook session.start que vous avez déjà. classic.SessionStart se déclenche aussi au démarrage et après compaction, ce qui ne réinitialise pas $.state, donc le filtre sur source garde le hook aux trois réinitialisations :
Avec les deux hooks en place, le volet affiche le compte sauvegardé après /clear et non 0, et le prochain appui sur Add one ajoute au compte sauvegardé. loadCount écrit la valeur stockée sur celle dans $.state, et session.start se déclenche à nouveau chaque fois que le module se recharge. Pour éviter que le magasin ne prenne du retard, enregistrez à chaque changement, comme le fait le bouton Add one. Pour vérifier le rechargement sans une session, testez le dessin après /clear.

Enregistrer à partir de plus d’une session

Chaque session sur votre machine qui exécute votre mod partage un $.store. Un get suivi d’un set n’est pas atomique. Quand deux sessions lisent chacune une valeur, la modifient et l’écrivent, elles font la course, et la deuxième écriture remplace la première. Pour rendre cela moins probable :
  • Donnez à chaque élément sa propre clé : un set change seulement sa propre clé, donc les sessions qui écrivent des clés différentes ne s’écrasent pas mutuellement
  • Lisez à nouveau juste avant d’écrire : pour une valeur que plusieurs sessions changent, get la clé dans le callback et construisez la nouvelle valeur à partir de cela, pas à partir d’une copie que vous avez chargée à session.start. L’écriture d’une autre session est toujours perdue si elle atterrit entre votre get et votre set.
Ce bouton ajoute un à ce que le magasin contient maintenant, puis met à jour le dessin :
Si une deuxième session a appuyé sur son propre bouton trois fois depuis le démarrage de cette session, cet appui affiche et enregistre un compte qui inclut ces trois.

Prochaines étapes