SpyBara
Go Premium

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

This page contains 326 additions and 0 deletions.

2026
Fri 2 22:59

Referencia de mods

Referencia completa de los mods de Claude Code: estructura del módulo de hooks, eventos, métodos de la API de mods, puntos de renderizado, elementos por superficie, límites y configuración.

Consulta cualquier evento que un mod puede manejar, cualquier método de la API de mods que puede llamar o cualquier punto de renderizado en el que puede dibujar, para la CLI de Claude Code y la app de escritorio a partir de la v2.1.287. Cada entrada indica el nombre y una descripción de una línea, y enlaza a la sección de la guía que lo explica cuando existe.

Archivos

Un mod es un directorio de plugin con estos archivos:

Archivo Obligatorio Contenido
.claude-plugin/plugin.json Sí El manifiesto del plugin. Los mods no añaden campos obligatorios.
hooks/hooks.json Sí modules: un array con una ruta, relativa a este archivo, al módulo de hooks, como en "modules": ["./register.js"]. También puede contener hooks de configuración en hooks.
El módulo de hooks, como hooks/register.js Sí El punto de entrada del mod. Exporta register(on, options). Con nombre .js, .mjs, .cjs, .jsx, .ts, .mts, .cts o .tsx. Un módulo ES.
types/index.d.ts, indicado por types en el manifiesto Cuando el mod usa $.state o añade un namespace a la API de mods Declara los valores de PluginState y cualquier namespace que añada el mod
Archivos cuyos nombres terminan en .test.ts o .test.tsx No Pruebas que ejecuta claude plugin test

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 a on 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.

Argumento Qué es
$ La API de mods: todos los métodos de métodos de la API de mods. Escribe cada llamada completa, primero el espacio de nombres y luego el método, como en $.fs.read('notes.md').
e La entrada del evento, como datos simples congelados en profundidad. Para cambiarla, pasa una copia a next.
next(e) El siguiente controlador, como en un middleware. Ejecuta los hooks posteriores a este y luego el comportamiento de Claude Code. Se resuelve con el resultado del evento.
next.signal Un AbortSignal que se aborta cuando el evento se abandona
next.origin { plugin, tier } de quien disparó el evento. El propio Claude Code es { plugin: 'engine', tier: 'core' }. El tier de un mod es su grupo de prioridad en el orden en que se ejecutan los mods: prepend, user, append o builtin.
next.budget El límite de tiempo del hook en milisegundos: next.budget.ms es el límite completo y next.budget.remainingMs es lo que queda en este momento
next.to(e, tier) Salta a un tier posterior, que es append, builtin o core. next.to(e, 'append') omite los mods que instaló un usuario. Solo un mod en prependPlugins o appendPlugins puede llamarlo.
next.error, next.called Solo en un controlador .catch. next.error.kind es throw o timeout, next.error.message es el texto del error y next.called es true cuando el hook que falló había llamado a next.

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 de turn.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:

Evento Se dispara cuando Un hook puede devolver
tool.call Una herramienta está a punto de ejecutarse next(e), { deny: reason } o { result }
tool.check Claude Code decide si una llamada a herramienta puede ejecutarse, después de los hooks tool.call y PreToolUse. next(e) se resuelve en la decisión a la que llegaron las reglas, el modo de permisos y esos hooks. { decision }, que es allow, ask o deny
tool.describe Una vez por cada herramienta, cuando su descripción se envía por primera vez a Claude { description }

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:

Evento Se dispara cuando Un hook puede devolver
prompt.submit Se envía un prompt next({ ...e, text }), next({ ...e, context }) o { drop: reason }
prompt.fill, prompt.suggest Un texto está a punto de entrar en el cuadro del prompt como borrador o como sugerencia atenuada next(e) con el texto cambiado
prompt.edit El usuario edita el cuadro del prompt next(e)
prompt.compose Claude Code genera un prompt del sistema { sections }, una lista de { id, text, scope } en el orden en que se envían
prompt.section Una vez por cada sección con nombre del prompt del sistema. e.name es el id de la sección en prompt.compose. { text }, o { text: null } para omitir la sección
prompt.context Una vez por cada conversación, para el contexto enviado con el primer mensaje { blocks }
prompt.attachment Claude Code agrega un mensaje propio para Claude, como un recordatorio. e.type indica el tipo y, para los tipos que declaran las definiciones de tipos, e.detail contiene los datos a partir de los cuales se escribió el texto. { text }, o { text: null } para omitirlo
skill.prompt El texto de un skill se expande para Claude { text }
attribution.text Claude Code compone el texto de atribución de un commit o pull request { text }

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:

Evento Se dispara cuando Un hook puede devolver
command.run Un comando está a punto de ejecutarse { text }, {} o next(e)
command.describe Una vez por cada comando, para la lista de comandos { description, argumentHint, isHidden }
config.set Una fila de /config está a punto de cambiar next({ ...e, value }) o { deny: reason }
config.describe Una vez por cada fila de /config { label, description, isHidden }

Turnos

Los eventos de turno siguen una respuesta de principio a fin, incluida cada solicitud al modelo dentro de ella:

Evento Se dispara cuando Un hook puede devolver
turn.start Comienza un turno next(e)
turn.step Una solicitud está a punto de enviarse al modelo yield* next(e), o next({ ...e, model }), next({ ...e, effort })
turn.complete Terminó un turno next(e), o { text } para mostrar una línea debajo de la respuesta

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:

Evento Se dispara cuando Un hook puede devolver
session.start Una vez por cada mod cargado, antes del primer prompt, y de nuevo tras recargar ese mod. No después de /clear, /resume o /branch. next(e)
session.end La sesión termina, o se ejecuta /clear, /resume o /branch. e.reason es clear, resume, logout, prompt_input_exit u other. /branch informa resume. next(e)
session.compact La conversación está a punto de compactarse { skip: reason }
session.receive, session.send Llega un mensaje de otro agente o sesión, o está a punto de enviarse a uno. Consulta Enviar y recibir mensajes entre sesiones. { consumed: reason } para receive, { isDelivered: false, reason } para send
session.append Una vez por cada fila que conserva la conversación, como un prompt, un bloque de respuesta, un resultado de herramienta o un aviso, antes de almacenarla next({ ...e, message }) para reescribir el content de la fila
session.attach, session.detach Otra aplicación se conecta a la sesión o se desconecta de ella next(e)
session.measure Después de cada turno, y cuando cambia el porcentaje usado de un límite del plan next(e)

Subagentes

Los eventos de subagentes se disparan cuando se ofrece un tipo de subagente a Claude y cuando uno está a punto de iniciarse:

Evento Se dispara cuando Un hook puede devolver
agent.offer Se ofrece un tipo de subagente a Claude { isOffered: false } para ocultarlo
agent.spawn Un subagente está a punto de iniciarse { model } o { deny: reason }

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 de ui.render:

Evento Se dispara cuando
ui.render Un punto de renderizado está a punto de dibujarse
ui.resolve Se cargan los mods, una vez por cada aplicación, punto de renderizado y mod. El resultado es la tabla de elementos que lee $.ui.resolve(e).
ui.press, ui.input, ui.select Se usa un Button, Input o Select que dibujó un mod
ui.focus, ui.scroll El control enfocado o la posición de desplazamiento de un panel o de la banda está a punto de cambiar
ui.close Un panel está a punto de cerrarse. e.id es el panel y e.origin.kind es plugin, person o unload.
ui.message Un elemento Client publica datos en su mod

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:

Evento Se dispara cuando Un hook puede devolver
plugin.register Un módulo de hooks está a punto de cargarse. e.uses enumera sus eventos, llamadas a la API de mods, variables de entorno y estado, tal como los imprime claude plugin validate. Cada llamada se escribe sin el prefijo $., como fs.read. { refuse: reason }
engine.create Se está construyendo la API de mods para este mod Una API de mods modificada, para agregar un espacio de nombres u ocultar uno

Telemetría

Los eventos de telemetría se disparan para los registros de uso que Claude Code registra:

Evento Se dispara cuando Un hook puede devolver
telemetry.log, telemetry.mark Un registro de telemetría está a punto de registrarse, o se marca un uso de una funcionalidad. En un mod que instales, dale a un hook de telemetría el filtro { to: 'collector' }, como en on('telemetry.log', { to: 'collector' }, hook). Sin el filtro, el mod no pasa claude plugin validate. * no coincide con estos eventos. next(e) o { deny: reason }

Eventos de hooks de configuración

Cada evento de hook de configuración es un evento llamado classic.<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, como fs.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.

Espacio de nombres Métodos
$.plugin name, root: el nombre y el directorio de este plugin
$.ui resolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list
$.model complete, fork, classify
$.prompt submit, read, fill, suggest, compose. Claude lee el texto de submit({ text }) después de una oración que nombra a tu mod como remitente. submit({ text, asUser: true }) envía el texto como las propias palabras del usuario, sin esa oración.
$.turn abort
$.session messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() devuelve { startedAt, context, rateLimits, cost }: context tiene tokens, window y percent, y rateLimits es una lista de { kind, percentUsed, resetsAt }.
$.config list, set
$.settings read
$.env get, set
$.fs read, write, list, exists, stat, ancestors. write no es atómico: reemplaza el contenido del archivo en el lugar, por lo que otro proceso puede leer un archivo escrito parcialmente. Guarda en $.store los datos que varias sesiones modifican.
$.store get, set, delete, keys. Un almacén de clave-valor que comparten todas las sesiones de la máquina. Consulta Guardar desde más de una sesión.
$.state Estado reactivo: get, set, con los helpers atom, read, update, derive y memberOf importados de claude-code
$.clock now, sleep, after, every
$.http fetch
$.process run, spawn
$.mcp call, connect. connect(server) conecta un servidor MCP que el manifiesto de tu propio plugin enumera.
$.audio play, speak
$.telemetry log, mark. Un registro se envía solo cuando Claude Code o un mod integrado hace la llamada.

Puntos de renderizado

Un punto de renderizado es un punto de extensión en la interfaz de Claude Code. Cada fila es un valor de e.component en un hook ui.render, con los campos de e.props y las apps que lo renderizan. e.surface es terminal o desktop. 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.

Punto de renderizado e.props e.requestId Se renderiza en
Pane title, isFocused, bodyColumns, placement, scroll, view El id del panel Terminal, Desktop
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Una instancia Terminal, Desktop
UserMessage text, origin, isExpanded, y task o from según el origen El id del mensaje Terminal, Desktop
AssistantMessage El texto de la respuesta El id del mensaje Terminal, Desktop
ToolUse, ToolResult, ToolGroup El nombre, la entrada y el resultado de la herramienta El id de la llamada a herramienta Terminal, Desktop
CommandOutput command, text El id del mensaje Terminal, Desktop
AskUserQuestion La pregunta y las opciones El id de la llamada a herramienta Terminal, Desktop
ToolProgress kind El id de la llamada a herramienta Terminal
Spinner word, message, suffix, mode El id del agente Terminal, Desktop
TurnDuration word, durationMs El id del mensaje Terminal
InfoNotice text, command El id del mensaje Terminal
SessionMode modes Una instancia Terminal, Desktop
PromptHint isDraft, isWorking, hint Una instancia Terminal, Desktop

e.viewport contiene columns, rows e isFullscreen. No está presente hasta que la app ha medido su ventana. Su rows es la altura de toda la ventana, no la de tu panel.

Para ajustar un árbol a su punto de renderizado, lee estas props en el hook:

  • Ancho de un Pane o de la banda: dibuja según e.props.bodyColumns
  • Altura de un Pane junto a la transcripción: cuando e.props.placement es 'dock', e.props.scroll.bodyRows es el número de filas que tiene el panel
  • Altura de un Pane encima del prompt: cuando e.props.placement es 'inline', el panel crece con tu árbol hasta un límite, y bodyRows cuenta solo las filas que se muestran en ese momento. El campo rows de $.ui.open solicita un límite distinto.

Un árbol más alto que el panel se desplaza como un todo.

Elementos

Los elementos son los bloques de construcción de un árbol que devuelve un hook ui.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.

Elemento Props principales Terminal Escritorio
Box key, diseño flex, gap, padding, margin, width, height, borderStyle, backgroundColor, position, hover ✓ ✓
Text color, backgroundColor, bold, italic, underline, dimColor, inverse, wrap ✓ ✓
Button key, label, onPress, hotkey, plain, dimColor, autoFocus, action ✓ ✓
Link href, label ✓ ✓
Code El código, hasta 10,000 caracteres ✓ ✓
Markdown text, hasta 10,000 caracteres, key, dimColor, onLinkPress, pressableLinks ✓ ✓
Input key, label, placeholder, value, submitLabel, onSubmit, onInput, autoFocus ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓
Svg Un documento SVG, hasta 131,072 caracteres ✓
Client module, key ✓ ✓
Raster key, columns hasta 512, rows hasta 256, cells. Consulta Dibuja una cuadrícula de celdas de colores. ✓
Image Bytes PNG o RGBA de hasta 2 MiB, o una ruta de archivo ✓

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.

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 y rechaza una llamada que supera un límite de tamaño.

Límite Valor
El tiempo de ejecución propio de un hook para un evento, sin contar el tiempo dentro de next ni de una llamada a la API de mods distinta de $.clock.sleep 10 segundos
El tiempo de ejecución de un controlador .catch 1 segundo
Todos los hooks session.end en conjunto 1.5 segundos
Tiempo de espera de $.process.run 30 segundos de forma predeterminada, 10 minutos como máximo
maxTokens de $.model.complete 1024 de forma predeterminada, hasta 64,000 o el límite de salida del modelo
$.fs.read y $.fs.write 4 MiB por archivo
Un hijo de tipo cadena de un Text 10,000 caracteres
$.store 4 MiB de JSON en total
$.session.messages() Las 4,096 entradas más recientes
Redibujados de $.ui.invalidate('ui.render') Limitados a 10 por segundo, o 30 en la terminal para el panel visible, la banda expandida y la línea de sugerencia debajo del prompt. Las llamadas que llegan antes se agrupan.
$.ui.toast Se muestra durante 4 segundos a menos que pases { timeoutMs }
Un panel abierto sin que el usuario lo pida Se coloca a partir de 144 columnas de la terminal, 110 después de que lo haya abierto una vez
Nombres de comandos, herramientas, tipos de subagente y paneles Letras, dígitos, _ y -, hasta 64 caracteres
Una prueba de claude plugin test 5 segundos a menos que la prueba establezca timeoutMs

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:

Nombre Dónde Qué hace
CLAUDE_CODE_PLUGIN_DIRS Entorno, o env en ~/.claude/settings.json Directorios de plugins que se cargan como lo hace --plugin-dir, para aplicaciones a las que no puedes pasar un flag. Rutas absolutas separadas por :, o por ; en Windows.
CLAUDE_CODE_PLUGIN_DIR_WATCH Entorno 1 hace que una sesión no interactiva de larga duración recargue los mods de --plugin-dir al guardar
prependPlugins, appendPlugins Configuración administrada. Configuración de usuario solo en una máquina sin configuración administrada, para un usuario que no haya iniciado sesión con un plan Team o Enterprise. Listas de ids de plugins, como acme-guard@acme-tools. Los mods en prependPlugins se ejecutan antes de cada mod que instala un usuario, y los mods en appendPlugins se ejecutan después, en el orden indicado. Consulta El orden en que se ejecutan los mods.
allowManagedModsOnly Configuración administrada, como una opción de la protección integrada Solo se cargan los mods que cuentan como de tu organización y los mods integrados en Claude Code. Los hooks de configuración de los usuarios siguen ejecutándose.
allowModsToOverrideDenyRules Configuración administrada, como una opción de la protección integrada Permite que un mod instalado por un usuario apruebe una llamada a herramienta que una regla deny rechaza
allowManagedHooksOnly Configuración administrada Bloquea los hooks y los mods instalados que no son de tu organización. Consulta qué sigue ejecutándose.
disableAllHooks Cualquier archivo de configuración En la configuración administrada, no se ejecuta ningún mod ni hook de un plugin instalado. En tu propia configuración, lo que administra tu organización sigue ejecutándose. Consulta disableAllHooks.
disableSideloadFlags Configuración administrada Rechaza --plugin-dir y --plugin-url al inicio
pluginConfigs Configuración de usuario o administrada Contiene los valores de userConfig de un mod, indexados por el id del plugin, como acme-guard@acme-tools, o por su nombre y @inline, como first-mod@inline, para uno cargado con --plugin-dir

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 comandos claude 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.

Comando Qué hace
/plugin Muestra una línea como 1 mod active · first-mod debajo de sus pestañas cuando se ha cargado un mod que no viene integrado
claude plugin validate <directory> Lee el manifiesto y el módulo de hooks de un plugin e informa los errores, los eventos que maneja y las llamadas a la API de mods que realiza. --strict trata las advertencias como errores y --json imprime un informe legible por máquina.
claude plugin test [directory] Ejecuta cada archivo dentro del directorio, o del directorio actual cuando no indicas ninguno, cuyo nombre termina en .test.ts o .test.tsx. Sale con estado 1 cuando una prueba falla.
claude --plugin-dir <directory> Carga un directorio de plugin durante una sesión y vuelve a cargar su módulo de hooks cuando guardas. Repite el flag para cargar varios.
/reload-plugins Vuelve a cargar los plugins cuando lo ejecutas