La referencia completa son las declaraciones de TypeScript para mods de Claude Code, que describen cada evento, método y elemento, con ejemplos. La copia en GitHub puede ser más antigua que la versión de Claude Code que tienes instalada. Cuando ambas no coincidan, confía en la copia que Claude Code escribe para tu versión.
Archivos
Un mod es un directorio de plugin con estos archivos:register recibe on y options. options contiene los valores de los campos de userConfig que declara el manifiesto, con los valores predeterminados ya completados.
La función del hook
Un mod registra cada uno de sus hooks, que son controladores de eventos, llamando aon dentro de register. on recibe el nombre del evento, un matcher opcional, que es un filtro sobre los campos del evento, y el hook, como en on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on devuelve un registro con un método, .catch(handler), que establece el controlador de errores del hook.
Eventos
Los eventos se agrupan según lo que conciernen, cada uno con cuándo se dispara y qué puede devolver un hook sobre él. Los hooks deturn.step y process.spawn son generadores asíncronos, y los demás hooks son funciones asíncronas.
La última columna de cada tabla usa una notación abreviada. next(e) pasa el evento sin cambios. next({ ...e, text }) pasa una copia con el campo indicado cambiado, como en next({ ...e, text: e.text.trim() }). Un objeto responde al evento sin llamar a next, y una palabra como reason representa una cadena que tú escribes, como en { deny: 'Use the file tools.' }.
Herramientas
Los eventos de herramientas se disparan alrededor de cada llamada a herramienta que hace Claude, desde la descripción que lee Claude hasta la decisión sobre si la llamada se ejecuta:Campos de agente y organización en tool.check
En un hook de tool.check, lee estos campos para distinguir la llamada de un subagente de la de la conversación principal, y para ver si tu organización requiere aprobación para una herramienta de conector:
e.agentId: se establece cuando un subagente o un compañero en proceso hace la llamada, y está ausente cuando la hace la conversación principale.ceiling:askpara una herramienta de conector que tu organización estableció enask, en sesiones en las que ese ajuste llega a Claude Code
tool.check, e.agentId y e.ceiling requieren Claude Code v2.1.290 o posterior.
Prompts y lo que lee Claude
Los eventos de prompt abarcan el texto que escribe el usuario y el texto que Claude Code envía a Claude por su cuenta, como el prompt del sistema y los recordatorios:Campos de origen y frontmatter en skill.prompt
En un hook de skill.prompt, puedes leer estos campos junto con el nombre del skill en e.skill y el texto que lee Claude en e.text:
Un hook puede pasar un
text o frontmatter cambiado a next: los hooks posteriores leen ambos, y Claude lee el text final. Un hook que cambia cualquier otro campo falla.
En skill.prompt, e.source, e.pluginName, e.path, e.frontmatter y e.frontmatterProblem requieren Claude Code v2.1.299 o posterior.
Comandos y configuración
Los eventos de comandos y configuración se disparan cuando un comando se ejecuta o se lista, y cuando una fila de/config se muestra o cambia:
Turnos
Los eventos de turno siguen una respuesta de principio a fin, incluida cada solicitud al modelo dentro de ella:Sesión
Los eventos de sesión marcan el inicio, el fin y la compactación de la sesión, y el intercambio de mensajes con otras sesiones:Subagentes
Los eventos de subagentes se disparan cuando se ofrece un tipo de subagente a Claude y cuando un subagente o un compañero de un equipo de agentes está a punto de iniciarse:
Cuando Claude reanuda un subagente con la herramienta
SendMessage, tu hook de agent.spawn no vuelve a ejecutarse. Para rechazar las llamadas a SendMessage que reanudan un subagente, haz coincidir esa herramienta en un hook de tool.call.
Interfaz
Los eventos de interfaz se disparan cuando Claude Code dibuja un punto de renderizado y cuando el usuario usa un control que dibujó un mod. Dibujar en la interfaz muestra lo que devuelve un hook deui.render:
Otros mods
Estos eventos permiten que un mod actúe sobre otros mods mientras se cargan, para rechazar uno o cambiar la API de mods que recibe:
Cuando el hook de otro mod llama a un método de un espacio de nombres que agregaste en
engine.create, las llamadas a $ de tu método se ejecutan en el contexto de ese hook hasta que todos los hooks de ese evento devuelven. Por ejemplo, una ruta relativa se resuelve respecto al directorio de trabajo de ese hook, y $.prompt.submit se rechaza mientras el turno está esperando a ese hook. Las llamadas que tu método hace después de eso se ejecutan en el contexto propio de tu mod.
Telemetría
Los eventos de telemetría se disparan para los registros de uso que Claude Code registra:Eventos de hooks de configuración
Cada evento de hook de configuración es un evento llamadoclassic.<Event>, como classic.Stop o classic.PostToolUse. e es el JSON de stdin del hook.
Llamadas a la API de mods
Cada método de la API de mods también es un evento, nombrado según su espacio de nombres y su método, comofs.read, model.complete o ui.open. Un hook sobre uno intercepta las llamadas de los mods que se ejecutan después de él, y puede devolver next(e), { deny: reason } o { value }.
Métodos de la API de mods
La API de mods es el argumento$ que recibe cada hook. Sus métodos están agrupados en espacios de nombres, como $.ui. Esta tabla enumera los métodos de cada espacio de nombres por su nombre, de modo que open en la fila de $.ui es la llamada $.ui.open(...). Las guías muestran los más comunes en uso, y los tipos para tu compilación documentan cada método con un ejemplo.
Puntos de renderizado
Un punto de renderizado es un punto de extensión en la interfaz de Claude Code. Cada fila es un valor dee.component en un hook ui.render, con los campos de e.props y las apps que lo renderizan. e.surface indica la app que está dibujando, como terminal, desktop o vscode. Cambiar lo que Claude Code ya dibuja muestra lo que un hook puede hacer en un punto de renderizado, con un ejemplo de cada opción.
Renderizar en la extensión de VS Code requiere la versión 2.1.299 o posterior de la extensión y una sesión que obtenga los feature flags. Dibujar en la extensión de VS Code enumera lo que la extensión dibuja de forma diferente.
e.viewport contiene columns, rows e isFullscreen. En la terminal y en la app Desktop, no está presente hasta que la app ha medido su ventana. Ahí, su rows es la altura de toda la ventana, no la de tu panel. En la extensión de VS Code, siempre está presente.
Para ajustar un árbol a su punto de renderizado, lee estas props en el hook:
- Ancho de un
Paneo de la banda: dibuja segúne.props.bodyColumns - Altura de un
Panejunto a la transcripción: cuandoe.props.placementes'dock',e.props.scroll.bodyRowses el número de filas que tiene el panel para tu árbol - Altura de un
Paneencima del prompt: cuandoe.props.placementes'inline', el panel crece con tu árbol hasta un límite, ybodyRowses ese límite. Para solicitar un límite distinto, consulta el camporowsde$.ui.open.
Elementos
Los elementos son los bloques de construcción de un árbol que devuelve un hookui.render, y los obtienes de $.ui.resolve(e). Crea un árbol a partir de elementos muestra los más comunes junto con cómo los dibuja la terminal, y la galería de interfaces tiene capturas de pantalla de la mayoría. Una marca de verificación significa que la aplicación puede dibujar el elemento.
Más reglas de
Button: action nombra una de las propias acciones de atajos de teclado de Claude Code, y el atajo del usuario para ella presiona el botón cuando ese atajo es un acorde o una tecla con modificador. Un hotkey de dígito en un botón de la banda también se activa cuando el usuario escribe solo ese dígito en un prompt vacío y hace una pausa. Cuando dos botones de un mismo dibujo nombran el mismo hotkey, el último se queda con él. autoFocus solo acepta true en cualquier control, así que omite la prop para dejarla desactivada.
La extensión de VS Code ignora algunas props de los elementos y dibuja el elemento como si las hubieras omitido:
Box:positionyhoverText:size,monoytabularButton:hotkey,plain,autoFocusyaction, así que allí el usuario presiona un botón con un clic, o con Enter una vez que tiene el focoCode:language,path,startLine,formatywrap, así que el código se dibuja sin colores ni números de línea, y un bloqueformat: 'diff'muestra el texto sin procesar del diffInputySelect:autoFocus
Estilos de borde de Box
Para dibujar un borde alrededor de un Box, establece su borderStyle en uno de estos nombres, como en borderStyle: 'round'. Cada fila indica lo que dibuja la terminal para ese nombre y muestra el borde superior.
Un
Box cuyo borderStyle nombra cualquier otra cosa, como 'rounded', se dibuja sin borde.
Pasos de espaciado de Box
Las props de espaciado de Box son gap, columnGap, rowGap, padding, margin y las formas de un solo lado y de un solo eje de padding y margin, como paddingX y marginTop. Cada una acepta un número de celdas de la terminal, como gap: 1, o un nombre de paso, como gap: 'md'. En la terminal y en la extensión de VS Code, cada paso equivale a esta cantidad de celdas:
Si estableces
gap, padding o margin en un paso, el paso se aplica en horizontal y en vertical a la vez. Por ejemplo, en la terminal y en la extensión de VS Code, padding: 'md' equivale a dos celdas a cada lado y una fila arriba y abajo.
Los nombres de paso requieren Claude Code v2.1.299 o posterior. En una versión anterior, Claude Code dibuja su propia versión del sitio en lugar de un árbol que usa un nombre de paso.
Props tipográficas de Text
Establece size, weight, mono o tabular en un Text para pedirle a la aplicación que dibuja tu árbol un tamaño de texto, un grosor, una tipografía monoespaciada o dígitos de ancho uniforme. Antes de depender de una prop, comprueba qué hacen con ella la terminal y la extensión de VS Code. Si una aplicación ignora una prop que estableciste, tu árbol se sigue dibujando allí, con el texto como si hubieras omitido esa prop.
Estas cuatro props requieren Claude Code v2.1.299 o posterior. En una versión anterior, Claude Code dibuja su propia versión del sitio en lugar de un árbol que establece
size, weight, mono o tabular.
Reemplaza bold por weight
bold en un Text está obsoleto en favor de weight y sigue funcionando. Para reemplazarlo en un Text sin weight, cambia bold: true por weight: 'semibold' para obtener el mismo resultado en Claude Code v2.1.299 o posterior.
En una versión anterior a v2.1.299, un árbol que establece weight no se dibuja, y Claude Code dibuja su propia versión del sitio en su lugar. Si estableces tanto bold como weight en un Text, bold no tiene efecto.
Límites
Las llamadas a la API de hooks y mods se ejecutan con límites de tiempo y de tamaño. Claude Code omite un hook que supera un límite de tiempo.Configuración y variables de entorno
Estos son los ajustes y las variables de entorno que afectan a los mods. La columna Dónde indica desde qué archivo de configuración o entorno se lee cada uno:sec-default@builtin es una protección integrada en Claude Code, que aparece como cc-plugin-sec-default en /plugin y en el registro de depuración. Se carga antes de cada mod que una persona instala en una máquina con configuración administrada, o para un usuario que haya iniciado sesión con un plan Team o Enterprise. Si se establece prependPlugins en la configuración administrada, la protección solo se carga cuando esa lista la nombra, en la posición indicada. Su código fuente está en el directorio mods/sec-default del repositorio de Claude Code.
Comandos
Estos comandos y flags cargan, inspeccionan y prueban un mod. Los comandosclaude se ejecutan en tu shell y los comandos / en el prompt de Claude Code. En la tabla, <directory> representa una ruta que escribes, como en claude plugin validate ./first-mod. Los corchetes marcan un argumento opcional.