Los mods de Claude Code se lanzaron el 1 de octubre de 2026 y en menos de una semana la comunidad ya había publicado más de 1.700. Si sigues de cerca a Anthropic, probablemente viste cómo el anuncio superaba los 2,1 millones de visualizaciones. Lo que quizá no has hecho todavía es crear uno. Este tutorial te enseña a crear mods de Claude Code paso a paso, con patrones de la API verificados en la documentación oficial.
Entender cómo funcionan realmente los mods es el requisito previo para todo lo demás, así que la guía empieza por ahí.
Índice
- Qué son los mods de Claude Code (y en qué se diferencian de los hooks)
- Requisitos antes de empezar
- Cómo se estructura un mod
- Paso a paso: un mod que oculta secretos
- Tres mods oficiales que merece la pena estudiar
- Problemas habituales y cómo solucionarlos
- Seguridad: lo que no te puedes saltar
- Qué crear después
- Fuentes
Qué son los mods de Claude Code (y en qué se diferencian de los hooks)
Anthropic presentó los mods el 1 de octubre: pequeñas funciones en TypeScript que se enganchan a los eventos internos de Claude Code y cambian lo que hace el agente. Puede parecer lo mismo que los hooks de configuración que ya existían, pero la diferencia importa: aquellos hooks podían reaccionar a los eventos, pero no reescribirlos ni sustituir funciones. Los mods van más allá.
Un mod es un plugin formado por funciones en JavaScript o TypeScript a las que Claude Code llama cada vez que ocurre un evento interno: una llamada a una herramienta, un prompt enviado, un elemento de la interfaz que se dibuja. La función puede simplemente observar el evento, reescribirlo antes de que continúe o sustituir por completo el comportamiento esperado, por ejemplo bloqueando un comando. Es la misma lógica que un middleware de Express, aplicada al ciclo de vida del agente.
En la práctica, los mods pueden reescribir un prompt antes de que llegue al modelo, bloquear o reintentar una llamada a una herramienta, aprobar o denegar una solicitud de permiso, ocultar secretos en la salida de las herramientas y editar o sustituir elementos de la interfaz. Es una superficie mucho más amplia que todo lo que estaba disponible antes para los plugins de Claude Code.
La cadena de middleware
«Cuando varios mods se enganchan al mismo evento, se ejecutan en el orden en que se cargan»: el primer mod que se carga ve el evento el primero y el resultado el último. Esta ejecución en capas, como una cebolla, permite apilar mods de distintos autores y que cada uno envuelva al siguiente.
Requisitos antes de empezar
Antes de escribir una sola línea de TypeScript, comprueba que tu entorno cumple lo mínimo.
- Versión de Claude Code: necesitas Claude Code v2.1.287 o posterior, donde los mods están activados por defecto. Ejecuta
claude --versionpara comprobarlo y actualiza si tienes una versión anterior. - No hace falta activar nada: la variable de acceso anticipado
CLAUDE_CODE_ENABLE_FUNCTION_HOOKSse ignora en estas versiones, incluso si vale 0. - Funciona en ambas interfaces: los mods se distribuyen dentro de plugins y funcionan en la CLI de Claude Code y en la app de escritorio.
- Salvedad con VS Code: el panel de chat de VS Code y
claude -pejecutan los hooks pero no muestran los paneles de los mods, así que un mod basado en paneles no se verá ahí. - Conocimientos de TypeScript: basta con TypeScript básico. Con nociones de TypeScript y de JSX al estilo de React cubres toda la API.
Cómo se estructura un mod
Entender cómo se organizan los mods en disco te ahorrará mucho tiempo de depuración.
Un mod necesita tres archivos: un manifiesto, un hooks.json que apunta a tu código y un módulo de TypeScript que registra el hook. En concreto:
- La carpeta es un plugin normal con un manifiesto
.claude-plugin/plugin.json.hooks/hooks.jsonindica un módulo enmodules. El módulo exportaregister(on, options), y dentro de élon(event, matcher?, hook)añade un hook.
Todos los hooks siguen el mismo patrón de tres argumentos:
on("tool.call", { tool: "Bash" }, async ($, e, next) => {
// $ la API de mods: ui, session, state, store, fs, process, clock, http, tool, command, model
// e los datos de entrada de este evento
// next pasa e a los demás plugins y después al comportamiento propio de Claude Code
return next(e);
});Para registrar comportamiento, cada mod llama a on dentro de register. on recibe el nombre del evento, un filtro opcional sobre los campos del evento y la función del hook.
A qué eventos te puedes enganchar
Hay veinte eventos repartidos en varias áreas: ciclo de vida (session.start, turn.start, turn.step, turn.complete, engine.create), herramientas (PreToolUse, tool.call, tool.describe), interfaz (ui.render, ui.resolve, ui.press, ui.input, ui.select), prompts (prompt.submit, prompt.section, prompt.context, skill.prompt) y agentes (agent.offer, agent.spawn).
Paso a paso: un mod que oculta secretos
Es uno de los ejemplos prácticos más claros de cómo los mods gestionan datos sensibles. El objetivo es eliminar claves de API y claves privadas de la salida de las herramientas antes de que Claude las lea.
Paso 1: crea la carpeta del plugin
Crea una carpeta, por ejemplo ./redact-secrets, y añade los tres archivos necesarios:
.claude-plugin/plugin.json: el manifiesto con el nombre y la descripción del pluginhooks/hooks.json: apunta a tu módulo en la clavemoduleshooks/register.ts: el módulo de TypeScript que exportaregister
Paso 2: escribe el hook
Guarda el hook como hooks/register.ts. Claude Code llama a register una vez al cargar el mod, y el hook tool.call se ejecuta alrededor de cada llamada a Bash y Read. Al llamar a await next(e) se ejecutan la comprobación de permisos y la herramienta; después, el hook devuelve una copia del resultado con los secretos ocultos.
El patrón verificado es este:
export const register: Register = (on) => {
on("tool.call", async ($, e, next) => {
const result = await next(e);
// oculta los patrones de secretos conocidos antes de que Claude vea el resultado
return redact(result);
});
};Patrones habituales de secretos: /sk-[A-Za-z0-9_-]{20,}/g para claves de API al estilo de OpenAI y Anthropic, /AKIA[0-9A-Z]{16}/g para identificadores de claves de acceso de AWS y /gh[pousr]_[A-Za-z0-9]{36,}/g para tokens de GitHub.
Paso 3: consigue las definiciones de tipos
Cada vez que Claude Code carga o recarga un mod desde una carpeta que pasas con --plugin-dir, escribe archivos de declaración de TypeScript (.d.ts) en .claude-plugin/types/ dentro de la carpeta del mod. Describen los eventos, los métodos de la API de mods y los elementos exactos de tu versión de Claude Code, para que tu editor pueda autocompletar y comprobar los tipos de tus hooks.
Es buen momento para repasar los espacios de nombres disponibles. Los mods reciben el objeto $, que incluye, entre otros, $.plugin (name, root), $.ui (resolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, selection, blit), $.command (register, run, list) y $.tool (register, call, check, list).
Paso 4: carga el mod con recarga automática
Inicia una sesión de Claude Code con la opción --plugin-dir apuntando a tu carpeta:
claude --plugin-dir ./redact-secretsUna carpeta cargada con --plugin-dir admite recarga en caliente: cada vez que guardas register.ts, el mod se recarga sin reiniciar la sesión. Es la forma más rápida de iterar.
Paso 5: valida y prueba
Antes de compartirlo o instalarlo en serio, ejecuta el validador integrado:
claude plugin validateEjecuta claude plugin validate con cada plugin antes de instalarlo y lee el código del hook: es TypeScript legible, no código ofuscado.
También tienes el framework oficial de pruebas: importa expect y test desde claude-code/testing, responde a cada llamada a herramienta en lugar de Claude Code para que no se ejecute ninguna herramienta real, lanza eventos sintéticos y comprueba el resultado.
Paso 6: instálalo para el día a día
Cuando estés contento con el mod, instálalo como plugin en el ámbito que encaje con tu forma de trabajar. El ámbito de usuario lo activa en todos los proyectos del equipo; el de proyecto lo registra en el .claude/settings.json del repositorio para tus compañeros, que aún tendrán que instalarlo una vez; y el local lo activa solo para ti en ese repositorio.
Para instalar un mod ya publicado por la comunidad:
claude plugin marketplace add <autor/repo>
claude plugin install <nombre-del-mod>@<marketplace>Después de instalarlo, ejecuta /reload-plugins en una sesión abierta.
Tres mods oficiales que merece la pena estudiar
En el lanzamiento, Anthropic convirtió en mods tres de sus funciones integradas: el panel de diferencias, el cargador de AGENTS.md y la telemetría. Así sentó un precedente oficial y dejó claro que el sistema es una pieza central, no un experimento. Leer su código en el repositorio de Claude Code es la forma más rápida de ver cómo es un mod con calidad de producción.
El mod diff registra el comando /diff, vigila los cambios del espacio de trabajo de Git y muestra listas de archivos y fragmentos de código. Se suscribe a muchos eventos del ciclo de vida, como session.start, command.run, tool.call, turn.complete y prompt.submit, además de varios eventos de interfaz. Demuestra cómo una extensión puede combinar registro de comandos, inspección del repositorio e interfaz dinámica en un solo módulo de TypeScript.
El 3 de octubre de 2026, Anthropic añadió además un plugin integrado llamado You Should Know, que revisa la salida de Claude en busca de cosas que se te podrían pasar. Actívalo con /plugin enable cc-plugin-you-should-know@builtin.
Problemas habituales y cómo solucionarlos
El mod no se carga
Necesitas Claude Code 2.1.287 o posterior en la terminal; compruébalo con claude --version. Si la versión es correcta y el mod sigue sin aparecer, revisa que hooks/hooks.json apunte al nombre de archivo correcto del módulo y que register sea una exportación con nombre, no una exportación por defecto con otro nombre.
El panel no se ve
El panel de chat de VS Code y claude -p ejecutan los hooks pero no muestran los paneles de los mods. Usa la CLI o la pestaña Code de la app de escritorio. Las sesiones en la nube y en WSL tampoco muestran paneles.
Conflicto en el orden de los hooks
Los mods se ejecutan como una cadena de middleware por capas en orden de registro, de modo que el orden de carga y la confianza entre mods pueden aprovecharse si un mod malicioso entra en la cadena. Si dos mods no coinciden en una decisión de permisos, gana la capa exterior: el que se cargó primero. Cambia el orden de tus --plugin-dir o ajusta los ámbitos para resolver el conflicto.
Mod desactivado por la política de la organización
Las instalaciones gestionadas cargan primero un mod de protección (sec-default), y los administradores pueden limitar qué mods se ejecutan. Puedes desactivar los mods por plugin en /plugin, por sesión con --safe-mode o en todas partes con disableAllHooks.
Seguridad: lo que no te puedes saltar
Antes de instalar cualquier mod de terceros, es imprescindible entender cómo acceden a tu equipo.
Los mods se ejecutan con el mismo acceso a tu equipo que Claude Code. No están aislados. La documentación de Anthropic indica que un mod funciona con tus permisos, no está en un entorno aislado y puede aprobar llamadas a herramientas; revísalo antes con claude plugin validate.
Ese control adicional tiene un coste en seguridad: los mods heredan el acceso de Claude Code a tu equipo, aunque se mantienen las restricciones de marketplaces de la organización y las instalaciones gestionadas cargan primero el mod de protección.
Usa --safe-mode cuando trabajes en repositorios sensibles hasta que confíes en tu conjunto de plugins.
Qué crear después
La comunidad avanza rápido: un catálogo comunitario ya recogía 1.752 mods a 4 de octubre de 2026. Algunas ideas confirmadas para explorar:
- Salvaguardas para producción: un mod puede pedir confirmación antes de que cualquier comando toque la configuración de producción.
- Registro de auditoría: un mod que se carga el primero puede registrar todas las llamadas que hacen los demás mods.
- Visualización del uso de contexto: con unas pocas líneas de TypeScript puedes añadir un panel que muestre un gráfico del contexto consumido.
- Políticas en los prompts: añade una línea de política a cada prompt antes de que llegue al modelo, por ejemplo para que el agente nunca muestre secretos y prefiera preguntar antes que dar permisos.
Si ya usas Claude Code para automatizar, la guía de integración de Claude con n8n te muestra cómo llevar a Claude a tus flujos de negocio, y el tutorial de la API de Claude (en inglés) cubre la capa de API a la que los mods pueden llamar a través de $.http.
Entender cómo se encadenan los mods es lo que separa un experimento puntual de una herramienta de ingeniería fiable. Empieza con un solo hook tool.call, ejecuta claude plugin validate antes de cada instalación y lee el código de los mods oficiales de Anthropic antes de escribir algo más complejo. La funcionalidad es tan nueva que la documentación oficial y los archivos .d.ts que Claude genera para tu versión exacta son tus referencias más fiables: úsalos antes que cualquier tutorial de terceros, incluido este.