Saltar al contenido principal
Un mod puede dibujar su propia interfaz en Claude Code y cambiar partes de la interfaz que Claude Code ya dibuja. Cada lugar donde un mod puede dibujar se llama punto de renderizado, como un panel, la franja sobre el prompt o el spinner. Claude Code dispara el evento ui.render cada vez que está a punto de dibujar un punto de renderizado, y tu hook para ese evento devuelve lo que se debe dibujar allí. Este mapa muestra dónde puede dibujar un mod en una sesión de terminal: Mapa de una sesión de terminal de Claude Code con renderizado en pantalla completa. Un mod puede agregar un panel como barra lateral a la derecha, una notificación emergente en la parte superior derecha de la transcripción, una línea de registro en la transcripción, una franja sobre el prompt y una línea de estado debajo del prompt. Un mod puede redibujar mensajes, filas de llamadas a herramientas y el spinner. El prompt es propio de Claude Code. Mapa de una sesión de terminal de Claude Code con renderizado en pantalla completa. Un mod puede agregar un panel como barra lateral a la derecha, una notificación emergente en la parte superior derecha de la transcripción, una línea de registro en la transcripción, una franja sobre el prompt y una línea de estado debajo del prompt. Un mod puede redibujar mensajes, filas de llamadas a herramientas y el spinner. El prompt es propio de Claude Code. En una terminal más angosta, el panel se ubica sobre el prompt en lugar de junto a la transcripción. Crea tu primer mod antes de empezar aquí. Comienza con el ejemplo práctico, que crea un panel con dos pestañas y un contador, y luego lee la sección de cada parte que quieras cambiar.
Para consultar una prop o un límite específico, consulta la referencia.

Crea un panel con pestañas

En esta sección creas un mod que agrega un comando /hello-tabs, y el comando abre un panel. Un panel es una barra lateral junto a la transcripción en una terminal de pantalla completa ancha, o una región enmarcada sobre el prompt en otros casos. Este panel muestra dos pestañas, y la segunda pestaña tiene un botón que suma uno a un contador. El conteo sigue ahí después de reiniciar Claude Code. El mod terminado se ve así. La grabación abre el panel, cambia a la segunda pestaña, presiona el botón algunas veces y vuelve a la primera pestaña:
Las pestañas son dos botones en una fila. El mod registra cuál está activa y dibuja el contenido de esa pestaña debajo de la fila.
1

Crea el plugin

Un mod es un plugin con un manifiesto, un hooks.json que apunta a tu código y el archivo de código. Crear un mod explica cada uno. Crea un directorio llamado hello-tabs con los directorios .claude-plugin y hooks dentro, y luego guarda los dos primeros archivos.Guarda el manifiesto como hello-tabs/.claude-plugin/plugin.json:
hello-tabs/.claude-plugin/plugin.json
Indica tu punto de entrada en hello-tabs/hooks/hooks.json:
hello-tabs/hooks/hooks.json
2

Escribe el código

Esta lista indica qué hace cada hook, en el orden en que aparecen en el código:
  • Agrega el comando /hello-tabs y carga el conteo que guardó una sesión anterior
  • Abre el panel cuando ejecutas ese comando
  • Dibuja el contenido del panel: la fila de pestañas y el cuerpo de la pestaña abierta
Dos variables a nivel de módulo, tab y count, contienen el estado del panel.Guarda esto como hello-tabs/hooks/register.js:
hello-tabs/hooks/register.js
Cada hook también hace algo que el código no deja claro:
  • session.start también lee el conteo guardado desde $.store, un almacén de clave-valor que persiste entre sesiones.
  • command.run solo le indica a Claude Code que el panel existe. Abrir un panel no dibuja nada por sí solo: Claude Code luego dispara ui.render para preguntar qué va dentro.
  • ui.render devuelve el árbol de elementos, un Box que contiene otras cajas, texto y botones, y lo vuelve a construir a partir de tab y count cada vez que se ejecuta.
Presionar un botón ejecuta su callback onPress, que cambia una variable y llama a redraw. Claude Code luego vuelve a ejecutar el hook ui.render, y el hook construye un árbol nuevo a partir de los valores nuevos. Todo dibujo interactivo usa ese ciclo de renderizado: un callback cambia el estado y el hook vuelve a renderizar a partir del nuevo estado.
3

Abre el panel

En tu shell, inicia Claude Code con claude --plugin-dir ./hello-tabs. En el prompt de Claude Code, ejecuta /hello-tabs. Se abre un panel con 1: One y 2: Two en la parte superior. Presiona 2 y luego presiona a, la tecla de acceso rápido de Add one, algunas veces. El conteo sube.
4

Comprueba que el conteo se guardó

Presiona Esc para cerrar el panel y luego sal de la sesión. En tu shell, vuelve a iniciar Claude Code con el mismo comando claude --plugin-dir ./hello-tabs y, en el prompt de Claude Code, ejecuta /hello-tabs. El conteo está donde lo dejaste.Para borrar el conteo, haz que el mod llame a $.store.delete('count'). Conservar el estado explica cuánto dura cada tipo de valor.

Elige dónde dibujar

Para elegir el punto de renderizado en el que dibuja un hook ui.render, pasa un filtro, llamado matcher, como segundo argumento de on. { component: 'Pane' } ejecuta el hook solo para paneles. En el hook, e.component indica el punto, e.surface indica qué aplicación está dibujando y e.props contiene los datos propios del punto. Para un panel, e.requestId es el id con el que lo abriste. El panel y la franja están vacíos hasta que un mod los llena. Selecciona una pestaña para ver qué es cada uno y cómo dibujar en él:
Un panel es una barra lateral junto a la transcripción en una terminal de pantalla completa ancha o, en caso contrario, una región enmarcada encima del prompt. Con varios paneles abiertos, cada uno tiene una pestaña que muestra su título.Un panel aparece cuando tu mod llama a $.ui.open con un id que eliges, como en $.ui.open({ id: 'hello-tabs' }). Abre un panel en el momento adecuado describe los demás campos y cuándo un panel espera a que la terminal sea más ancha.Para dibujar en tu panel, filtra por { component: 'Pane' } y comprueba que e.requestId sea tu id.
Un mod también puede colocar una fila propia en la transcripción.

Cambia lo que Claude Code ya dibuja

Claude Code dibuja por sí mismo la mayor parte de su interfaz: mensajes, filas de llamadas a herramientas, el spinner y más. Cada una de esas partes también es un punto de renderizado, así que un mod puede cambiar su estilo o reemplazarla. Para cambiar una, filtra tu hook ui.render por su nombre de esta tabla: Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage y los puntos de llamadas a herramientas funcionan en la terminal, la aplicación Desktop y la extensión de VS Code. La tabla de puntos de renderizado indica dónde se genera cada uno de los demás. En un punto que Claude Code ya dibuja, tu hook puede cambiar un detalle, reemplazar el dibujo o dejarlo como está. Selecciona una pestaña para ver cada opción aplicada al spinner. Los ejemplos leen una variable calls que otro hook cuenta, como en el mod del tutorial.
Para conservar el dibujo de Claude Code y cambiar una parte, pasa a next una copia del evento con las props modificadas. Este hook cambia el texto que sigue a la palabra del spinner:
El spinner conserva su animación y su palabra, y tu texto va después de la palabra:
En estos puntos, next(e) devuelve una referencia al dibujo de Claude Code, { type: 'engine', ref }, a menos que un mod que se ejecuta después del tuyo haya devuelto un árbol propio. Para cambiar lo que hay en ese dibujo, pasa a next una copia del evento con props diferentes, como hace la pestaña Cambiar un detalle. Puedes devolver la referencia tal cual o colocarla en un Box junto a elementos propios:
Mientras Claude trabaja, el spinner se anima como antes y under the spinner aparece debajo. La solicitud de permiso no es un punto de renderizado, así que un mod no puede cambiar lo que muestra. El diálogo de preguntas, AskUserQuestion, sí lo es, así que un mod puede cambiar ese diálogo cuando Claude hace una pregunta. Un árbol para el diálogo debe contener la referencia exactamente una vez, con tus elementos encima. De lo contrario, Claude Code dibuja su propio diálogo.

Abre un panel en el momento adecuado

Un panel solo aparece cuando tu mod lo abre. Cómo y cuándo lo abres determina si toma el foco del teclado, cuánto espacio solicita y si llega a mostrarse en una terminal estrecha. Para abrir un panel, llama a $.ui.open con un id que elijas. El id es el nombre del panel: tu hook ui.render lo comprueba y lo vuelves a pasar para cerrar el panel. Si otro mod tiene abierto un panel con ese id, la llamada se rechaza.
Para cerrar el panel, llama a $.ui.close con el id con el que lo abriste:
Además de id, $.ui.open acepta estos campos opcionales: La extensión de VS Code ignora rows y columns y ajusta el tamaño del panel por sí misma. focus, closeOnEscape y holdToasts son opcionales y solo aceptan true. Para no usar uno, omítelo. Pasar false genera un error como ui.open: focus is true or left out. Para establecer uno de ellos de forma condicional, agrega el campo solo cuando se cumpla la condición. Esta llamada solicita el foco del teclado solo cuando items no está vacío:
Para permitir que un comando abra el panel mientras Claude está trabajando, agrega immediate: true cuando registres el comando. Sin eso, un comando escrito durante un turno espera a que el turno termine.

Retén los toasts detrás de un diálogo

Pasa holdToasts: true a $.ui.open cuando el panel sea un diálogo que el usuario responde y luego deja, para que no aparezcan toasts mientras decide. En la terminal, la retención dura mientras ese panel es el que se muestra, y un toast generado durante ese tiempo espera hasta que termine la retención. Claude Code retiene los toasts de otros mods y sus propias notificaciones de corta duración, además de los que tu mod genera con $.ui.toast. No uses el campo en un panel que permanece abierto, para que el usuario siga viéndolos.

Cuándo un panel espera a que la terminal sea más ancha

Un panel que tu mod abre sin que se lo pidan no aparece en una terminal estrecha, para que no pueda ocupar una pantalla pequeña. Que aparezca o no depende de qué lo abrió:
  • Si lo abrió algo que hizo el usuario, como un comando que ejecutó o un botón que presionó, el panel aparece con cualquier ancho
  • Si lo abrió tu mod por su cuenta, por ejemplo desde un temporizador o un hook turn.start, el panel solo aparece en una terminal de al menos 144 columnas de ancho. Después de que el usuario haya abierto ese panel por sí mismo una vez, bastan 110 columnas.
Cuando el panel aparece, $.ui.open se resuelve como { isPlaced: true }. Cuando el panel está en espera, isPlaced es false y reason es una cadena que explica el motivo. Un panel en espera aparece cuando el usuario lo abre o amplía la terminal. Para avisar que algo está disponible sin abrir un panel, llama a $.ui.toast('Your message'), que muestra una notificación toast.

Dibuja en la extensión de VS Code

En la extensión de VS Code, lo que dibuja un mod aparece en el panel de chat con la versión 2.1.299 o posterior de la extensión. Una sesión que no obtiene feature flags, como una en Amazon Bedrock, necesita la versión 2.1.304 o posterior. En un hook ui.render para el panel, e.surface es vscode. Para comprobar qué puntos y elementos dibuja el panel, y qué props ignora, consulta las tablas de puntos de renderizado y de elementos. Para que un mod funcione en el panel además de en la terminal, ten en cuenta estas diferencias:
  • Paneles: en un panel de 800 píxeles de ancho o más, los paneles se acoplan junto a la conversación, e.props.placement es 'dock' y e.viewport.isFullscreen es true. En un panel más estrecho, los paneles se dibujan encima del cuadro del prompt, placement es 'inline' y un panel muestra 12 filas antes de desplazarse.
  • Toasts y líneas de estado: se ubican en una sola pila directamente encima del cuadro del prompt, junto con los paneles cuando el panel es estrecho, con una línea de estado por mod. La pila se oculta mientras se muestra una solicitud de permiso o un diálogo.
  • Etiquetas: el panel enmarca lo que un mod dibuja o reescribe y lo etiqueta con el nombre del plugin, como en From the token-chart plugin o Edited by the token-chart plugin.
  • Teclado: los botones no tienen teclas de acceso rápido, así que el usuario hace clic en un botón o presiona Enter sobre él una vez que tiene el foco.
  • Foco del teclado: el panel concede la solicitud focus: true de un panel solo cuando el panel tiene el foco, Claude está inactivo sin ninguna pregunta pendiente y el cuadro del prompt está vacío.
  • El diálogo de preguntas: en AskUserQuestion, el panel conserva su propia tarjeta de pregunta y dibuja tus elementos encima de ella. Las props que pasas a next no cambian la tarjeta.
  • Sugerencias de prompt: $.prompt.suggest se resuelve con isShown: false y no muestra nada, porque el panel reserva el texto de sugerencia atenuado del cuadro del prompt para las sugerencias propias de Claude.
  • Límites de texto: el panel corta una línea de estado a los 200 caracteres o dos filas, y un toast a los 500 caracteres.

Coloca una fila en la transcripción

Una fila es una línea que tu mod agrega a la transcripción en la terminal, después del mensaje más reciente. Permanece en ese lugar a medida que avanza la conversación, y Claude no la ve. $.ui.place requiere Claude Code v2.1.314 o posterior.
1

Coloca la fila

Llama a $.ui.place con un id. El id es un nombre que inventas para la fila, como build-status. Puede tener de 1 a 64 letras, dígitos, _ o -, y cada fila que tu mod tenga en la transcripción necesita el suyo.
2

Dibuja la fila

Dibuja la fila en el punto de renderizado Placed.
Este ejemplo agrega un comando /build-status. Cuando el usuario ejecuta el comando, el mod agrega una fila que muestra Build: passing. El texto es fijo para que el ejemplo sea breve, así que un mod real dibujaría su propio resultado:
Para probar el ejemplo, coloca este código en un mod. En una sesión de terminal, ejecuta /build-status en el prompt de Claude Code. Build: passing aparece como una fila al final de la transcripción. La llamada no siempre muestra una fila, y una fila puede desaparecer más tarde, así que contempla estos casos en tu mod:
  • El resultado: { isPlaced: true, requestId } cuando la terminal dibuja la fila. De lo contrario, isPlaced es false y reason explica el motivo, como en no attached surface draws placed rows yet. Uno de los motivos es el límite de filas que un mod puede tener a la vez.
  • Una segunda llamada con el mismo id: mientras la primera fila siga en la transcripción, la llamada no agrega ninguna fila y se resuelve con el requestId de esa fila. Para cambiar lo que muestra la fila, vuelve a dibujar la fila.
  • Cuándo desaparece la fila: cuando termina la conversación, cuando el usuario retrocede a un punto anterior a la fila o, fuera del renderizado en pantalla completa, cuando se compacta la conversación. --resume no restaura la fila. Para volver a mostrar la fila, llama a $.ui.place de nuevo.

Pon un fondo detrás de la conversación

$.theme.set y $.theme.clear reemplazan a $.ui.backdrop, que Claude Code v2.1.319 eliminó. Cambia $.ui.backdrop({ id: 'your-backdrop' }) por una llamada a $.theme.set como la del ejemplo de esta sección, y $.ui.backdrop(undefined) por $.theme.clear(), que quita el fondo de cualquier mod.
Para poner un fondo detrás de la conversación en la aplicación Desktop o en la aplicación móvil, llama a $.theme.set con un backdrop y luego dibuja el fondo en el punto de renderizado Backdrop. Para quitar el fondo, llama a $.theme.clear(). La terminal no dibuja ningún fondo. $.theme.set y $.theme.clear requieren Claude Code v2.1.319 o posterior. Este ejemplo requiere Claude Code v2.1.323 o posterior, así que primero comprueba tu versión. El mod establece un fondo cuando se inicia la sesión, dibuja el fondo y agrega un comando /plain que quita el fondo:
Antes de v2.1.323, escribe id en lugar de scene en la llamada a $.theme.set y en e.props, y mueve overrideColorScheme dentro de backdrop como colorScheme.
Para probar el ejemplo, coloca este código en un mod e inicia una sesión en la aplicación Desktop o en la aplicación móvil. Para quitar el fondo, ejecuta /plain en el prompt de Claude Code. La transcripción muestra the theme is cleared después del nombre del mod, como en night-sky: the theme is cleared para un mod llamado night-sky. Comprueba qué acepta backdrop, qué te indica el resultado de la llamada y qué pueden cambiar otros mods:
  • Los campos de backdrop: scene es un nombre que eliges para un fondo que dibuja tu hook. Para los demás campos y overrideColorScheme, consulta los tipos para tu compilación.
  • Si se dibuja el fondo: $.theme.set se resuelve con isDrawn: true cuando una aplicación Desktop o móvil conectada a la sesión indica que dibuja fondos. De lo contrario, isDrawn es false y reason explica el motivo.
  • Un tema por sesión: un mod que llama a $.theme.set reemplaza el fondo y los colores de la sesión, y un mod que llama a $.theme.clear() los quita, sin importar qué mod los haya establecido. Llama a $.theme.clear() solo cuando el usuario lo pida.

Cambia los colores de la aplicación Desktop

Para cambiar los colores de la pestaña Code de la aplicación Desktop con un mod, pídele uno a Claude o escribe uno tú mismo. Ambas formas requieren Claude Code v2.1.324 o posterior en la pestaña Code, así que primero comprueba ahí la versión. Claude Code en la terminal conserva sus propios colores.

Pídele a Claude un mod de colores

1

Describe los colores

Inicia una sesión local en la pestaña Code y dile a Claude qué colores quieres. Por ejemplo, escribe make a mod that makes the app cream in light mode and dark brown in dark mode. Claude escribe los archivos del mod.
2

Aprueba el mod

Responde las preguntas que Claude Code hace sobre los archivos del mod y la recarga en caliente. Para saber qué hace cada respuesta, consulta Pídele a Claude un mod.
3

Comprueba los colores

La pestaña Code cambia de color cuando se carga el mod. Para ajustar un color, dile a Claude qué cambiar. Si no cambia nada, consulta Corrige los colores de mods que no aparecen.

Escribe un mod de colores tú mismo

makeColors es una función que crea un tema a partir de unos pocos colores hexadecimales. Estos pasos crean un mod llamado paper que la usa.
1

Haz que Claude copie makeColors

Inicia una sesión local en la pestaña Code y escribe copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/. Comprueba que ambos archivos estén en ese directorio.
2

Guarda el manifiesto y hooks.json

A partir de Escribe un mod tú mismo, guarda .claude-plugin/plugin.json y hooks/hooks.json en ~/.claude/skills/paper/, y cambia first-mod por paper en ambos archivos. Un mod dentro de ~/.claude/skills/ se carga cuando inicias una sesión.
3

Escribe el código

Guarda este archivo como ~/.claude/skills/paper/hooks/register.js. Cuando se inicia una sesión, el código llama a $.theme.set con los colores para el modo claro y el modo oscuro:
Para usar tus propios colores, reemplaza los valores hexadecimales por otros colores hexadecimales de seis dígitos.
4

Comprueba los colores

Inicia una nueva sesión local en la pestaña Code. Con los valores del ejemplo, el fondo es crema en el modo claro y marrón oscuro en el modo oscuro. Si no cambia nada, consulta Corrige los colores de mods que no aparecen.

Corrige los colores de mods que no aparecen en la aplicación Desktop

Si usas un proveedor externo en lugar de una cuenta de Claude en Claude Desktop v5.11492.5 o anterior, la pestaña Code conserva sus propios colores, así que omite estas comprobaciones. De lo contrario, si los colores de un mod no aparecen en la pestaña Code, o si desaparecen, comprueba estas causas:
  • Versión antigua: actualiza la aplicación Desktop, reiníciala e inicia una nueva sesión local en la pestaña Code. Si Claude escribió el mod, vuelve a pedírselo ahí.
  • Mod no cargado: si Claude escribió el mod, consulta cuándo se carga en Pídele a Claude un mod. Si lo escribiste tú, compara tus archivos y sus rutas con Escribe un mod de colores tú mismo.
  • Tema rechazado: pídele a Claude que ejecute la llamada a makeColors del mod. Si la llamada genera un error, o su lista problems tiene una entrada que empieza por Desktop won't paint this theme, haz que Claude corrija el tema. Si instalaste el mod, envía lo que Claude encuentre a su autor.
  • Otra llamada a $.theme: cuando cualquier mod de la sesión llama a $.theme.set o $.theme.clear(), los colores y el fondo de una llamada anterior desaparecen. En tu propio mod, pasa colors y backdrop en la misma llamada a $.theme.set. Usa a la vez un solo mod que establezca un tema.

Quita los colores de mods de la aplicación Desktop

Para quitar los colores de un mod de la pestaña Code, primero desactiva el mod. Un mod que sigue activado puede volver a establecer sus colores.
1

Desactiva el mod

2

Inicia una nueva sesión

Inicia una nueva sesión local en la pestaña Code.
3

Quita los colores que persisten

Si los colores siguen ahí, abre Settings desde la pestaña Code y busca ahí code appearance. Abre el resultado y selecciona Remove colors.

Construye un árbol a partir de elementos

Lo que devuelve un hook ui.render es un árbol de elementos: una descripción de lo que se debe dibujar, hecha de cajas, texto y controles anidados unos dentro de otros. Tú describes el dibujo, y Claude Code lo renderiza en la aplicación que el usuario tenga abierta: la terminal, la aplicación Desktop o la extensión de VS Code. Para obtener los elementos, llama a $.ui.resolve(e) en tu hook, como en const { Box, Text, Button } = $.ui.resolve(e). Cada elemento es una función. Le pasas props, y pones los elementos y cadenas que van dentro de él en children. Selecciona una pestaña para ver cada uno de los elementos más comunes y cómo los dibuja la terminal:
Text dibuja una cadena, con estilos opcionales como bold y color:
La galería de interfaces tiene ejemplos y capturas de pantalla de la mayoría de los elementos. Esta tabla enumera los elementos principales: Si tu módulo es un archivo .tsx o .jsx, puedes escribir el árbol como JSX. Primero desestructura los elementos de $.ui.resolve(e). Si tu dibujo no aparece, revisa si su árbol tiene una prop que un elemento no acepta o un hijo donde no va ninguno. Un hook que devuelve un árbol así falla, y una línea hook skipped indica el nombre de tu mod y la regla que el árbol incumplió. Para un Text en un panel con una prop llamada bogusProp, esa línea dice:
En la aplicación Desktop y la extensión de VS Code, un Link se dibuja como texto sin formato a menos que su href cumpla estos requisitos:
  • Esquema y host: una URL https:, o una URL http://localhost como http://localhost:3000
  • Sin @: escribe un @ en la ruta o la consulta como %40
  • Escritura: lo que devuelve new URL(href).href, salvo por una / faltante después del host. Eso excluye un host en mayúsculas, un espacio y :443 en una URL https:.
En la terminal, estos requisitos no se aplican.

Cuando un Client falla

En la terminal, cuando falla el archivo que ejecuta un Client, una línea atenuada como my-mod: Client client/spinner.js: boom ocupa el lugar del Client, y el resto de tu dibujo se sigue mostrando. Si tu mod maneja ui.fault, Claude Code entonces vuelve a dibujar el sitio.

Dibuja una cuadrícula de celdas de colores

Para un mapa de calor, un minigráfico o un tablero de juego en la terminal, dibuja un solo Raster y no un Box por cada celda. Un Raster recibe una key, su tamaño en columns y rows, y cells, una cadena base64 que empaqueta todas las celdas. Cada celda son tres números: el punto de código del carácter, su color y su color de fondo. Un color es un valor RGB de 24 bits en hexadecimal, como 0xc62828 para un rojo. El valor 0x01000000, uno por encima de ese rango, significa el predeterminado de la terminal. Las aplicaciones distintas de la terminal no tienen Raster, así que comprueba e.surface y dibuja texto allí. Este cuerpo de panel dibuja un mapa de calor de tres por dos:
En la terminal, el panel muestra la cuadrícula: Un panel en la terminal que contiene una pequeña cuadrícula de bloques de colores, dos filas de tres. La fila superior es verde, ámbar y roja. La fila inferior es verde, verde y ámbar. El arreglo rows es la parte que cambiarías, y cellsOf lo convierte en la cadena empaquetada. El hook dibuja solo en un panel cuyo id es heat, así que abre uno con $.ui.open({ id: 'heat' }) desde un comando, como el ejemplo hello-tabs abre su panel. Cada carácter tiene que ocupar una celda de ancho. Para animar un Raster que ya está en pantalla, llama a $.ui.blit con el id del panel como requestId, la key del Raster, el mismo tamaño y celdas nuevas. Para este ejemplo, eso es $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Vuelve a pintar ese único elemento sin ejecutar de nuevo tu hook ui.render.

Responder a pulsaciones y escritura

Cuando el usuario pulsa un botón, escribe en un campo o elige de una lista que tu mod dibujó, Claude Code llama al callback de ese control, que se ejecuta en tu módulo. Cada control acepta sus propios callbacks:
  • Button: acepta onPress(e), donde e.surface es la app de la que vino la pulsación
  • Input: acepta onSubmit(value) y onInput(value)
  • Select: acepta onSelect(value) con sus opciones en options, una lista de al menos una opción con valores únicos, como [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

Qué controles necesitan una key

Dale a cada Input y Select una prop key, como key: 'size'. Un Button puede prescindir de una key cuando tiene una prop label o un único hijo de tipo cadena. Su key es entonces el valor de label o esa cadena. Las pruebas y otros mods identifican un control por su key:
  • Pruebas: una prueba pulsa o escribe en un control por su key.
  • Otros mods: Claude Code dispara ui.press, ui.input o ui.select con la key del control en e.element antes de ejecutar el callback del control. El hook de otro mod también puede ejecutarse para ese evento. Ese hook ve lo que el usuario escribió en tu Input y puede cambiar ese texto o impedir que tu callback se ejecute. La API de mods no le da a ese mod ningún método para pulsar tus botones.
Si un mensaje dice needs a key o is drawn twice, encuentra la causa a partir de ese mensaje.

Foco del teclado y teclas de acceso rápido

Tu mod nunca lee el teclado por sí mismo. El usuario pulsa una tecla, Claude Code decide a cuál de tus controles va dirigida y se ejecuta el callback de ese control. Aparte de una tecla de acceso rápido numérica en la banda o un atajo de teclado de action, eso solo ocurre mientras tu panel o banda tiene el foco del teclado. El resto del tiempo, las teclas van al prompt. En la extensión de VS Code, los botones no tienen teclas de acceso rápido: el usuario hace clic en un botón o pulsa Enter sobre él, y escribe en los campos.

Cómo obtiene un panel el foco del teclado

Un panel obtiene el foco del teclado cuando:
  • Tu mod lo abre con focus: true desde un comando o una pulsación
  • El usuario pulsa Ctrl+X y luego Tab
  • El usuario hace clic en él, lo que en la terminal requiere el renderizado en pantalla completa
Claude Code concede focus: true solo mientras el prompt está vacío y nada más tiene el foco del teclado. Un panel que se abre mientras el usuario está escribiendo no se queda con sus pulsaciones de teclas.

Qué hace cada tecla

Esta tabla indica qué hace una tecla mientras tu panel o banda tiene el foco del teclado: Un mod no puede asignar Tab ni las flechas a ninguna otra cosa, así que un juego se controla con w, a, s y d.

Establecer una tecla de acceso rápido y el primer foco

  • hotkey: para que el usuario pueda pulsar un Button con una sola tecla, dale una hotkey de un dígito o una letra minúscula, como en hotkey: 'a'
  • autoFocus: para elegir qué control tiene el foco cuando se abre el panel, añádele autoFocus: true. En la extensión de VS Code, autoFocus no hace nada: el control se dibuja como si lo hubieras omitido, y no necesitas cambiar nada. La prop solo acepta true, así que omítela en los demás controles.
Cómo se muestra una tecla de acceso rápido depende del botón y de la app: En la terminal, nombra la tecla en la etiqueta de un botón con corchetes, o usa plain: true, para que el usuario vea qué pulsar. La referencia de elementos tiene las demás reglas de Button: action, las teclas de acceso rápido numéricas en la banda y dos botones con la misma tecla de acceso rápido.

Cuando el usuario contrae la banda

En la terminal, mientras un mod dibuja en la banda, el usuario puede contraer la banda a una fila para quitarla de en medio:
  • Hacer clic en [-]: mientras la banda está expandida, Claude Code dibuja esta marca en el extremo derecho de su primera fila. En el renderizado en pantalla completa, el usuario hace clic en ella para contraer la banda.
  • Pulsar Ctrl+X y luego Ctrl+A: esto funciona tanto si el prompt, la banda o un panel tiene el foco del teclado. El usuario puede asignarle otras teclas mediante la acción abovePrompt:toggle.
Una banda contraída oculta todo lo que los mods dibujan en ella y muestra en su lugar una fila atenuada, que nombra las teclas que la expanden según las tenga asignadas el usuario:
Las mismas teclas, o en el renderizado en pantalla completa un clic en la fila, vuelven a expandir la banda. Hasta entonces, nada pulsa un botón en ella: ni una tecla de acceso rápido, ni un dígito escrito en un prompt vacío, ni un atajo de teclado para la action de un botón. Si la banda tiene el foco del teclado cuando el usuario la contrae, el foco vuelve al prompt, y Ctrl+X y luego Tab omite la banda mientras está contraída. La banda permanece contraída hasta que el usuario la expande, incluso después de /clear, y vuelve a estar expandida la próxima vez que se inicia Claude Code. Tu mod no puede expandirla. No hagas de la banda el único lugar donde tu mod muestra algo que el usuario tiene que responder. Para mostrarlo en otro lugar solo mientras la banda está contraída, lee e.props.isCollapsed en tu hook ui.render, que sigue ejecutándose. isCollapsed requiere Claude Code v2.1.321 o posterior.

Recibir texto escrito y dibujar una fila por elemento

Muchos paneles son un campo de texto con una lista debajo. El ejemplo de esta sección es un panel de notas: escribes una nota y pulsas Enter para añadirla, y cada nota tiene un botón x que la elimina. Con dos notas añadidas, la terminal dibuja el panel así:
La ✕ del borde superior es la marca propia de Claude Code para cerrar el panel. El ejemplo usa estas técnicas:
  • Recibir texto escrito: un Input llama a onSubmit(value) con el texto del campo cuando el usuario pulsa Enter, y a onInput(value) en cada cambio
  • Dibujar una lista: asigna a cada dato una fila y dale al botón de cada fila su propia key
Este hook dibuja el contenido del panel:
Para probar el panel:
  • Añadir una nota: escribe una línea y pulsa Enter. La línea aparece como una fila nueva y el campo se vacía.
  • Eliminar una nota: pulsa Tab hasta que el botón x de la nota tenga el foco y luego pulsa Enter. La x es la etiqueta del botón y no una tecla de acceso rápido, así que escribir la letra no lo pulsa.
Cada cambio sigue el mismo ciclo de renderizado que hello-tabs: el callback cambia notes, llama a redraw y guarda la lista en $.store. Si tu hook vuelve a dibujar el panel mientras el usuario está escribiendo una nota, el campo conserva su texto siempre que el hook pase el mismo value cada vez. Para reemplazar su texto por el tuyo, pasa un value distinto. El ejemplo guarda las notas pero no las carga. Para recuperarlas en la siguiente sesión, léelas en un hook session.start, de la misma forma en que hello-tabs lee count. Estas props forman la línea del campo, Note: Type a note and press Enter ⏎ add: Enviar un Input no inicia un turno a menos que tu callback llame a $.prompt.submit.

Volver a dibujar un sitio

Un dibujo es una instantánea: muestra lo que devolvió tu hook ui.render la última vez que se ejecutó. Para mostrar algo nuevo, el hook tiene que ejecutarse de nuevo. Claude Code lo vuelve a ejecutar ante algunos cambios, y tu mod lo solicita para el resto.

Cuándo Claude Code vuelve a dibujar sin que se lo pidas

Claude Code vuelve a ejecutar tu hook ui.render cuando cambian las props del sitio o cuando cambia el ancho de la terminal. Cuando un Client del sitio falla y tu mod maneja ui.fault, Claude Code ejecuta el hook una vez más después de que tus hooks ui.fault retornan, para que tu hook ui.render pueda omitir el Client. No ejecuta el hook con un temporizador, y no puede saber cuándo cambia una variable de tu módulo.

Volver a dibujar cuando cambian tus datos

Para que tus sitios se vuelvan a dibujar después de que cambien tus propios datos, llama a $.ui.invalidate('ui.render'). Este panel cuenta pulsaciones. El callback del botón cambia count y luego solicita que se vuelva a dibujar:
Cada pulsación aumenta el número en el panel. El ejemplo hello-tabs envuelve la misma llamada en su función redraw. Un valor que guardas en $.state no necesita la llamada, porque al escribir el valor se vuelven a dibujar los sitios que lo leen.

Volver a dibujar con un temporizador

Para mantener actualizado un reloj, una cuenta regresiva o un valor externo a la sesión, vuelve a dibujar de forma programada. Inicia un temporizador en el hook session.start del módulo. Si el módulo ya tiene uno, como ocurre con hello-tabs, agrégale la línea de $.clock.every:
Claude Code ahora ejecuta tu hook ui.render una vez por segundo. El temporizador se detiene después de que el módulo se recarga, y la nueva instancia del módulo inicia el suyo propio.

Con qué frecuencia puede volver a dibujarse un sitio

Claude Code limita la frecuencia con la que se vuelve a dibujar un sitio, así que tu mod puede llamar a $.ui.invalidate tan seguido como cambien sus datos. Para saber con qué frecuencia puede volver a dibujarse cada sitio, consulta la tabla de límites. Las llamadas que llegan más rápido que el límite se agrupan en un solo redibujado. Ese redibujado ejecuta tu hook una vez, y el hook lee tus datos tal como están en ese momento, así que se muestra el valor más reciente y no los intermedios. Una animación no puede ejecutarse más rápido que el límite.

Conservar el estado

El lugar donde un mod guarda un valor decide cuánto dura ese valor: hasta que el módulo se recarga, hasta que termina la sesión o de una sesión a la siguiente. Elige según cuánto tiempo tiene que durar el valor: $.store.get(key) se resuelve con el valor o undefined, y $.store.set(key, value) acepta cualquier valor JSON.

Guardar un valor en $.state

$.state conserva valores durante una sesión y vuelve a dibujar por ti. Es estado reactivo: un hook ui.render que lee un valor se suscribe a él, así que Claude Code vuelve a dibujar ese sitio cada vez que escribes el valor, y no llamas a $.ui.invalidate. Un valor en $.state también sobrevive a una recarga del módulo, cosa que una variable no hace. Para configurarlo, declara tus valores, apunta tu manifiesto a la declaración y luego define y usa cada valor. Los ejemplos mueven el count de hello-tabs a $.state.

Declarar los valores

Declara los valores en un archivo de declaración de tipos. La clave exterior es el nombre de tu plugin, y cada entrada debajo de ella es un valor y su tipo. Guarda esto como hello-tabs/types/index.d.ts:
hello-tabs/types/index.d.ts

Apuntar el manifiesto a la declaración

Para que claude plugin validate compruebe tu código con ese archivo, agrega al manifiesto un campo types con su ruta:
hello-tabs/.claude-plugin/plugin.json

Definir, leer y escribir un valor

En tu módulo, define cada valor con un valor predeterminado, léelo mientras dibujas y escríbelo desde un callback. atom nombra un valor y su valor predeterminado, read lo devuelve y update lo escribe. Los tres helpers llaman a $.state.get y $.state.set por ti:
Como el hook ui.render leyó count, Claude Code vuelve a ejecutar el hook cada vez que el botón lo escribe. Estas reglas se aplican al código:
  • Escribe plugin y key como literales de cadena: claude plugin validate los lee de tu código fuente
  • Guarda el resultado de cada llamada a atom en una const: si declaras count con let, la validación falla con takes a source the scan can read
  • Declara cada valor en el archivo de declaración de tipos: de lo contrario, la validación falla con hello-tabs.count is not declared
  • Escribe desde un callback o desde el hook de otro evento: un hook ui.render puede leer el estado pero no puede escribirlo, así que escribe desde onPress, onSubmit o un hook para otro evento

Cambiar hello-tabs para usar $.state

Para mover count de hello-tabs a $.state, cambia cada línea que lo usa:
  • Al principio del módulo: agrega la línea import y reemplaza let count = 0 por la línea atom
  • En el hook ui.render: agrega la línea read antes de tabButton y dibuja 'Count: ' + n en el Text
  • En el botón Add one: reemplaza onPress por el de Guardar desde más de una sesión, que guarda el conteo además de escribirlo
  • En el hook session.start: reemplaza las dos líneas que leen saved por la llamada a loadCount de Volver a cargar un valor guardado después de /clear
Conserva redraw para los botones de pestaña, porque tab sigue siendo una variable.

Volver a cargar un valor guardado después de /clear

Si tu mod copia un valor guardado de $.store a $.state en session.start, tiene que volver a copiarlo después de /clear, /resume o /branch. Esos comandos restablecen cada valor de $.state a su valor predeterminado, y session.start no se vuelve a disparar. classic.SessionStart sí se dispara después de cada uno de ellos, con e.source establecido en clear, resume o fork, así que vuelve a copiar el valor en un hook sobre él. De lo contrario, tu dibujo muestra el valor predeterminado, y un callback que guarda el valor de $.state escribe el valor predeterminado encima de lo que almacenaste. Este código carga count desde ambos hooks. Se basa en la versión de hello-tabs con $.state, donde count es un atom y update está importado. Coloca loadCount encima de register y agrega la llamada a loadCount al hook session.start que ya tienes. classic.SessionStart también se dispara al inicio y después de la compactación, que no restablece $.state, así que el filtro sobre source limita el hook a los tres restablecimientos:
Con ambos hooks en su lugar, el panel muestra el conteo guardado después de /clear y no 0, y la siguiente pulsación de Add one suma al conteo guardado. loadCount escribe el valor almacenado encima del que está en $.state, y session.start se vuelve a disparar cada vez que el módulo se recarga. Para evitar que el almacén se quede atrás, guarda en cada cambio, como hace el botón Add one. Para comprobar la recarga sin una sesión, prueba el dibujo después de /clear.

Guardar desde más de una sesión

Todas las sesiones de tu máquina que ejecutan tu mod comparten un mismo $.store. Un get seguido de un set no es atómico. Cuando dos sesiones leen cada una un valor, lo cambian y lo vuelven a escribir, compiten entre sí, y la segunda escritura reemplaza a la primera. Para que eso sea menos probable:
  • Dale a cada elemento su propia clave: un set cambia solo su propia clave, así que las sesiones que escriben claves distintas no se sobrescriben entre sí
  • Vuelve a leer justo antes de escribir: para un valor que cambian varias sesiones, haz get de la clave en el callback y construye el nuevo valor a partir de eso, no de una copia que cargaste en session.start. La escritura de otra sesión igual se pierde si ocurre entre tu get y tu set.
Este botón suma uno a lo que el almacén contenga en ese momento y luego actualiza el dibujo:
Si una segunda sesión ha pulsado su propio botón tres veces desde que comenzó esta sesión, esta pulsación muestra y guarda un conteo que incluye esas tres.

Próximos pasos