¿Qué son los mods de Claude Code?

¿Qué son los mods de Claude Code? Son plugins que ejecutan tu propio JavaScript o TypeScript dentro de Claude Code, de modo que pueden cambiar su aspecto y su comportamiento: dibujar una línea encima del prompt, mostrar cifras en la línea de estado, rechazar un comando de shell peligroso o añadir un comando de barra. Los mods llegaron con Claude Code 2.1.287 y están activados por defecto.

Esta guía explica de qué se compone un mod, qué puede tocar y qué no, en qué se diferencian los mods de los hooks de configuración, los servidores MCP y las skills, y cómo valorar si es seguro instalar uno. Termina con un mod funcional que puedes construir en dos minutos.

¿Qué es un mod de Claude Code?#

Un mod es un plugin normal de Claude Code con un archivo adicional: un módulo de hooks. El módulo exporta una función register(on, options). Cuando Claude Code carga el plugin, llama a register, y el mod usa on(...) para suscribirse a eventos como "una herramienta está a punto de ejecutarse", "ha terminado un turno" o "se está dibujando el spinner".

Cada manejador recibe tres argumentos:

• $, la API de mods. Todo efecto que tenga un mod pasa por ella: $.ui.status, $.ui.toast, $.process.run, $.fs.read, $.command.register, etc.
• e, el evento, por ejemplo el comando de Bash que está a punto de ejecutarse.
• next, que pasa el evento al comportamiento propio de Claude Code.

Un manejador puede observar (llamar a next(e) y examinar el resultado), reescribir (llamar a next con un evento modificado) o responder (devolver su propio resultado sin llamar nunca a next, que es como una protección deniega una llamada a una herramienta).

Lo que convierte un plugin en un mod es una sola clave. Si hooks/hooks.json contiene modules, el plugin es un mod:

{
  "modules": ["./register.js"]
}

Los mods se ejecutan en el proceso de Claude Code con tus permisos de usuario. No están aislados en un sandbox. La contrapartida útil es que todo efecto tiene que pasar por $, de modo que Claude Code puede leer el código fuente de un mod y enumerar exactamente qué eventos gestiona y qué llamadas a la API hace antes de que lo ejecutes.

¿Qué puede cambiar un mod?#

La lista de eventos es larga, pero la mayoría de los mods usan unas pocas áreas:

Los mods también pueden abrir paneles, registrar herramientas para que Claude las llame, ejecutar subagentes, leer y escribir archivos, hacer peticiones HTTP y guardar datos en un pequeño almacén clave-valor. Cada una de esas acciones es una llamada a $ que aparece en la validación.

La interfaz de los mods se dibuja en la terminal (incluido el plugin de JetBrains) y en la pestaña Code de la app de escritorio. En el panel de chat de la extensión de VS Code, en claude -p y en el Agent SDK, los hooks siguen ejecutándose, pero no se dibuja nada. Por eso una protección te sigue protegiendo en ejecuciones sin interfaz, mientras que un mod de línea de estado simplemente no tiene dónde mostrar su texto.

Mods frente a hooks, servidores MCP y skills#

Estos cuatro puntos de extensión solo se parecen en el nombre:

• Los hooks de configuración ejecutan un comando de shell en puntos fijos (antes de una herramienta, después de una herramienta, al detenerse). Son procesos separados que se comunican con Claude Code mediante JSON por stdin y stdout. No pueden dibujar interfaz ni mantener estado en vivo.
• Los mods se ejecutan dentro del proceso con una API tipada. Pueden hacer lo mismo que un hook y, además, dibujar en los puntos de renderizado, registrar comandos y herramientas, y reaccionar a eventos que los hooks nunca ven, como el dibujado del spinner o el inicio de una compactación.
• Los servidores MCP dan a Claude nuevas herramientas y fuentes de datos a través de un protocolo. Claude decide cuándo llamarlos. No cambian la interfaz de Claude Code ni interceptan sus herramientas integradas.
• Las skills son instrucciones y archivos que Claude carga cuando una tarea encaja con ellas. Cambian lo que Claude sabe, no lo que hace Claude Code.

Una regla aproximada: si quieres que Claude sepa algo nuevo o sea capaz de hacer algo nuevo, recurre a una skill o a un servidor MCP. Si quieres que el propio Claude Code se vea o se comporte de otra manera, escribe un mod.

¿Son seguros los mods de Claude Code?#

Un mod puede hacer todo lo que tú puedes hacer en una terminal, así que trata su instalación como la de cualquier herramienta de desarrollo. Tres hábitos mantienen el riesgo bajo:

1. Lee la salida de validate. claude plugin validate <dir> muestra una línea hooks: y una línea calls: para el módulo. Un mod de línea de estado que incluya $.http.fetch o $.fs.write merece una revisión más detenida.
2. Revisa las insignias de permisos. Cada página de mod en ClaudeMods convierte esas llamadas en etiquetas sencillas, como "Ejecuta comandos" o "Intercepta llamadas a herramientas", con una frase que explica por qué el mod necesita cada una.
3. Conoce los interruptores de apagado. /plugin disable <name> desactiva un mod. claude --safe-mode inicia una sesión con todos los mods desactivados. "disableAllHooks": true en la configuración los mantiene desactivados.

Las organizaciones pueden ir más allá. Los administradores pueden permitir solo mods gestionados, bloquear la carga lateral con --plugin-dir y colocar un mod de protección aprobado por delante de todo lo que instalen los usuarios. Los detalles están en la documentación de administración de mods.

¿Qué versión de Claude Code necesito?#

Ejecuta claude --version. La terminal necesita la 2.1.287 o posterior. La app de escritorio incluye su propia copia de Claude Code, y los mods funcionan en ella a partir de la 2.1.286. Cada mod de este sitio indica la versión con la que se probó por última vez; en el momento de escribir esto, es la 2.1.291.

Crea un mod mínimo para verlo funcionar#

Bastan tres archivos. Crea esta estructura:

hello-status/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

.claude-plugin/plugin.json:

{
  "name": "hello-status",
  "version": "0.1.0",
  "description": "Writes a fixed message to the Claude Code status line",
  "author": { "name": "Your Name" }
}

hooks/hooks.json contiene la clave modules mostrada antes, apuntando a ./register.js. Después, hooks/register.js:

export function register(on) {
  on('session.start', async ($, e, next) => {
    const started = await next(e)
    $.ui.status('hello from my first mod')
    return started
  })
}

Compruébalo antes de ejecutarlo:

claude plugin validate ./hello-status

En Claude Code 2.1.291 esto muestra:

  ❯ ./register.js hooks: session.start
  ❯ ./register.js calls: $.ui.status

✔ Validation passed

Ahora inicia una sesión con el mod cargado solo para esta ejecución:

claude --plugin-dir ./hello-status

La línea de estado muestra tu mensaje. Edita register.js y guarda; Claude Code recarga el módulo sin reiniciar. El mod se carga como hello-status@inline y desaparece al salir. El tutorial de mods explica cómo hacer pruebas y publicarlos.

Dónde encontrar mods#

Los mods se distribuyen a través de marketplaces de plugins, que son repositorios Git o URL con un archivo marketplace.json. ClaudeMods mantiene uno, y cada mod del directorio tiene una página con una grabación de demostración, el comando de instalación, sus opciones, el código que hace el trabajo y los permisos que usa. Cada uno se valida, se prueba y se graba en una compilación real de Claude Code antes de publicar su página.

¿Listo para añadir uno? Cómo instalar mods de Claude Code explica todos los métodos de instalación, además de cómo actualizarlos y eliminarlos.