SpyBara
Go Premium

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

This page contains 326 additions and 0 deletions.

2026
Fri 2 18: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 pueda manejar, cualquier método de la API de mods que pueda llamar o cualquier punto de renderizado en el que pueda dibujar, para la CLI de Claude Code y la app Desktop a partir de la v2.1.287. Cada entrada incluye 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 agregan 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 extensión .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 agrega un namespace a la API de mods Declara los valores de PluginState y cualquier namespace que agregue 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 completados.

La función de hook

Un mod registra cada uno de sus hooks, que son manejadores 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 manejador de errores del hook.

Argumento Qué es
$ La API de mods: cada método de Métodos de la API de mods. Escribe cada llamada completa, namespace y luego método, como en $.fs.read('notes.md').
e La entrada del evento, como datos planos congelados en profundidad. Para cambiarla, pasa una copia a next.
next(e) El siguiente manejador, 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. Claude Code en sí 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 ahora
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 manejador .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 escribes tú, como en { deny: 'Use the file tools.' }.

Herramientas

Los eventos de herramientas se disparan en torno a 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 de tool.call y PreToolUse. next(e) se resuelve con 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 a Claude por primera vez { description }

Prompts y lo que lee Claude

Los eventos de prompt cubren 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 ir al 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 renderiza 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 que se envía 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 ir 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 después de 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 app 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 a Claude un tipo de subagente y cuando uno está a punto de iniciarse:

Evento Se dispara cuando Un hook puede devolver
agent.offer Se ofrece a Claude un tipo de subagente { 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 app, 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 envía datos a su mod

Otros mods

Estos eventos permiten que un mod actúe sobre otros mods a medida que 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 lista 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 namespace u ocultar uno

Telemetría

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

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 función. 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, con el nombre de su namespace y 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 se agrupan en namespaces, como $.ui. Esta tabla lista los métodos de cada namespace por nombre, así 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.

Namespace 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 palabras del propio 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, así que otro proceso puede leer un archivo escrito a medias. Guarda en $.store los datos que modifican varias sesiones.
$.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 figura en el manifiesto de tu propio plugin.
$.audio play, speak
$.telemetry log, mark. Un registro se envía solo cuando la llamada la hace Claude Code o un mod integrado.

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 de 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 puede hacer un hook en un punto de renderizado, con un ejemplo de cada opción.

Punto 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 ahora. El campo rows de $.ui.open solicita un límite diferente.

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

Elementos

Los elementos son los componentes básicos del árbol que devuelve un hook de ui.render, y los obtienes de $.ui.resolve(e). Construir un árbol a partir de elementos muestra los más comunes junto con cómo los dibuja la terminal, y la galería de interfaz tiene capturas de pantalla de la mayoría. Una marca de verificación significa que la app puede dibujar el elemento.

Elemento Props principales Terminal Desktop
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 Dibujar 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 acciones de atajos de teclado propias de Claude Code, y el atajo del usuario para esa acción presiona el botón cuando ese atajo es una combinación de teclas o una tecla con modificador. Un hotkey numérico 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 indican el mismo hotkey, se lo queda el último. autoFocus solo acepta true en cualquier control, así que omite la prop para dejarlo desactivado.

Límites

Los hooks y las llamadas a la API de 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 dentro de una llamada a la API de mods distinta de $.clock.sleep 10 segundos
El tiempo de ejecución de un manejador .catch 1 segundo
Todos los hooks de 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 a 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 combinan.
$.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 terminal, 110 después de que el usuario 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 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 apps 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 de prependPlugins se ejecutan antes que cualquier mod que instale un usuario, y los de appendPlugins después, en el orden listado. Consulta El orden en que se ejecutan los mods.
allowManagedModsOnly Configuración administrada, como 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 opción de la protección integrada Permite que un mod instalado por un usuario apruebe una llamada a herramienta que rechaza una regla deny
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 iniciar
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 que cualquier mod que instale una persona 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 se carga solo 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 indican 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 es 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 hace. --strict trata las advertencias como errores y --json imprime un informe legible por máquina.
claude plugin test [directory] Ejecuta cada archivo del directorio, o del directorio actual si no indicas ninguno, cuyo nombre termina en .test.ts o .test.tsx. Sale con el estado 1 cuando falla una prueba.
claude --plugin-dir <directory> Carga un directorio de plugin durante una sesión y recarga su módulo de hooks cuando guardas. Repite el flag para cargar varios.
/reload-plugins Recarga los plugins cuando lo ejecutas