Mods de Claude Code: qué son, cómo funcionan y ejemplos reales

Los mods de Claude Code son pequeñas funciones en TypeScript o JavaScript que se ejecutan dentro de Claude Code y cambian cómo se comporta y cómo se ve: pueden reescribir un prompt, bloquear un comando peligroso, aprobar o denegar permisos, añadir paneles y botones a la interfaz o crear comandos propios. Anthropic los lanzó el 1 de octubre de 2026 con la versión 2.1.287, vienen activados por defecto y se instalan y comparten como cualquier plugin.

En esta guía tienes todo lo que necesitas saber: qué es un mod, para qué sirve, cómo funciona por dentro, cómo instalarlo, cómo crearlo sin escribir código, ejemplos reales con código, comunicación entre sesiones, permisos, seguridad y cómo controlarlos en un equipo o empresa.

Ficha rápida de los mods de Claude Code

¿Qué es un mod de Claude Code?

Definición sencilla

Cada vez que Claude Code hace algo, lanza un evento: llamar a una herramienta, pedirte permiso, enviar una petición al modelo o dibujar una parte de la pantalla. Un mod es una función que se engancha a uno de esos eventos y puede actuar antes, después o en lugar de lo que iba a pasar. También puede envolverlo, ejecutando código antes y después.

Una buena forma de entenderlo: hasta ahora usabas Claude Code tal y como salía de fábrica. Con los mods puedes «tunearlo» como harías con un coche: añadirle un medidor, un sistema de frenado extra o un panel nuevo en el salpicadero.

Qué puede hacer un mod

Según el anuncio oficial de Anthropic y la documentación de mods, con un mod puedes:

• Reescribir un prompt antes de que llegue al modelo.
• Bloquear, reescribir o reintentar una llamada a una herramienta.
• Aprobar o denegar una petición de permiso.
• Ocultar secretos (API keys, tokens) de la salida de una herramienta antes de que Claude la lea.
• Dibujar una interfaz propia: un panel junto a la conversación o una banda sobre el prompt, con pestañas, botones y campos de texto.
• Redibujar la interfaz de Claude Code: la fila de una llamada a herramienta, el spinner o el diálogo en el que Claude te hace preguntas.
• Crear comandos /propios que se ejecutan al instante, sin turno del modelo, incluso mientras Claude está trabajando.
• Registrar herramientas nuevas que Claude puede usar.
• Enviar una petición a otro modelo, por ejemplo mandar lo fácil a Haiku.
• Enviar mensajes a otras sesiones de Claude Code o a subagentes.
• Compartir datos entre hooks: lo que un hook cuenta, otro lo puede mostrar.

Por qué Anthropic creó los mods

Los desarrolladores llevaban tiempo pidiendo más control sobre Claude Code sin tener que esperar a que Anthropic lanzara cada función. Los hooks de configuración daban parte de ese control, pero tenían un límite claro: no podían reescribir eventos, dibujar interfaz nueva ni sustituir funciones. Los mods sí pueden. Anthropic incluso publicó el diseño en GitHub antes del lanzamiento para recoger opiniones.

La dirección es clara: Claude Code deja de ser solo un asistente que ejecutas y pasa a ser una plataforma que puedes reprogramar, algo parecido a lo que ocurrió con las extensiones de VS Code. Anthropic ha dicho que irá moviendo más funciones integradas a mods para que cada persona pueda quedarse con un núcleo pequeño y añadir solo lo que necesite.

Mods vs hooks vs skills vs MCP: diferencias

La diferencia clave está en dónde se ejecuta el código. Los hooks de configuración, las skills, las status lines y los servidores MCP funcionan desde fuera: lanzan un script o le dan a Claude texto y herramientas. Un mod corre dentro del proceso de Claude Code.

Cómo funciona un mod por dentro

Estructura de archivos de un mod

Un mod pequeño ocupa solo tres archivos:

mi-mod/
├── .claude-plugin/
│   └── plugin.json     ← nombre, versión y descripción
└── hooks/
    ├── hooks.json      ← apunta a tu código
    └── register.js     ← tu código (el "hooks module")

El archivo hooks.json solo indica qué módulo cargar:

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

Y plugin.json es el manifiesto del plugin:

{
  "name": "mi-mod",
  "version": "1.0.0",
  "description": "Mi primer mod de Claude Code"
}

La función register y sus tres argumentos

El módulo exporta una función register(on). Cada llamada a on(evento, filtro, hook) añade un hook, y todos los hooks reciben los mismos tres argumentos:

El módulo no tiene acceso a Node.js ni al DOM, ni a setTimeout. Ese límite es intencionado: como todo pasa por $, Claude Code puede listar lo que hace un mod antes de ejecutarlo.

Observar, reescribir o responder

Un hook se ejecuta antes de que Claude Code actúe, así que decide qué pasa después. Tiene tres opciones:

El evento es inmutable: si intentas asignar un campo directamente, lanza un error. Siempre se trabaja con copias.

Tu primer mod: contador de herramientas junto al spinner

Este mod cuenta cuántas herramientas usa Claude y muestra el número junto al spinner mientras trabaja (algo como Thinking · herramientas: 3):

// Variable compartida por los dos hooks
let llamadas = 0

export function register(on) {
  // Se ejecuta cada vez que Claude va a usar una herramienta
  on('tool.call', async ($, e, next) => {
    llamadas += 1
    $.ui.invalidate('ui.render')   // pide redibujar la interfaz
    return next(e)                 // la herramienta se ejecuta como siempre
  })

  // Se ejecuta cada vez que Claude Code dibuja el spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · herramientas: ' + llamadas } })
  })
}

Fíjate en que los dos hooks comparten la variable llamadas. Esa es una de las ventajas de los mods: un hook recoge datos y otro los muestra.

Filtrar qué eventos maneja un hook

El segundo argumento de on es un filtro (matcher). Puede ser un valor, una lista o una expresión regular:

on('tool.call', { tool: 'Bash' }, hook)               // solo Bash
on('tool.call', { tool: ['Edit', 'Write'] }, hook)    // Edit o Write
on('tool.call', { tool: /^mcp__github__/ }, hook)     // todas las herramientas de un MCP

El orden en que se ejecutan los mods

Cuando varios mods se enganchan al mismo evento forman una cadena tipo «cebolla»: el primero que carga ve el evento primero y el resultado el último, y decide si los demás llegan a ejecutarse. Eso permite apilar mods de autores distintos. El orden es:

Dentro de un mismo módulo, los hooks se ejecutan en el orden en que register llamó a on.

Eventos principales de los mods

Estos son los eventos que más vas a usar. La lista completa está en la página de eventos de la documentación.

La API de mods ($): qué puede tocar un mod

Todo lo que un mod hace fuera de su propio código pasa por la API $, agrupada en espacios de nombres. Estos son los principales (detalle en la página de la API):

Requisitos y dónde funcionan los mods

Necesitas Claude Code 2.1.287 o superior en la terminal (compruébalo con claude --version). La app de escritorio trae su propia copia de Claude Code y ahí los mods funcionan desde la 2.1.286; en la pestaña Code puedes ver tu versión con /status.

Un detalle importante: los hooks se ejecutan casi en todas partes, pero la interfaz solo se dibuja en la terminal y en la app de escritorio.

En la práctica: un mod guardián te sigue protegiendo en VS Code y en claude -p, pero un medidor visual no tiene dónde dibujarse. Un buen mod comprueba e.surface y, si no puede dibujar, escribe una línea en el transcript o devuelve texto.

Cómo instalar un mod en Claude Code

Instalar un mod desde un marketplace

Un mod se instala como cualquier plugin: nombre del plugin, @ y nombre del marketplace.

• Dentro de una sesión: /plugin install nombre@marketplace
• Desde tu shell: claude plugin install nombre@marketplace
• Desde la app de escritorio: botón +, luego Plugins y Add plugin

Si instalas desde la shell con una sesión abierta, ejecuta /reload-plugins en esa sesión para cargarlo sin reiniciar. Para añadir un marketplace de la comunidad:

claude plugin marketplace add usuario/repositorio
claude plugin install nombre-del-mod@nombre-del-marketplace

También puedes encontrar plugins con mods en el directorio de Claude.

Cargar un mod solo para una sesión

Para probar una carpeta sin instalarla:

claude --plugin-dir ./mi-mod

La app de escritorio no acepta opciones de línea de comandos. Ahí se usa la variable CLAUDE_CODE_PLUGIN_DIRS en el bloque env de ~/.claude/settings.json.

Ver qué mods están activos

Escribe /plugin. Bajo las pestañas aparece una línea gris como 1 mod active · nombre-del-mod. Los mods integrados aparecen en la pestaña Installed bajo Built-in.

Desactivar mods

Cómo crear un mod sin programar: pídeselo a Claude

No necesitas escribir ni una línea. Describe lo que quieres en una sesión interactiva de Claude Code y Claude lo escribe. Así funciona el proceso:

Prompts listos para copiar y pegar

Mostrar la rama de git sobre el prompt

Hazme un mod que muestre la rama de git actual en una línea encima del prompt.

Vigilar cuánto contexto llevas usado

Muy útil si trabajas con documentos largos (newsletters, guiones, briefs), porque el contexto se llena sin que te des cuenta y la calidad baja:

Hazme un mod que muestre encima del prompt qué porcentaje de contexto llevo usado
y los límites de mi plan. Que se actualice al terminar cada turno y que resalte la
cifra si pasa del 80%.

Pedir confirmación antes de borrar o sobrescribir

Hazme un mod que, antes de ejecutar cualquier comando que borre o sobrescriba archivos
de esta carpeta, me enseñe qué cambiaría y me deje elegir entre continuar o cancelar.

Medir cada turno

Crea un mod que muestre cuánto tardó el último turno, cuántas herramientas usó Claude
y cuántos tokens consumió, con un botón para ocultarlo.

Proponer el siguiente paso

Crea un mod que, al terminar cada turno, me proponga hasta tres prompts siguientes
y me deje elegir uno pulsando 1, 2 o 3 para dejarlo preparado en la caja de texto.

Consejo: termina siempre tu petición con «al terminar ejecuta claude plugin validate y dime qué hooks y qué calls lista». Así sabes exactamente qué hace el mod que te ha escrito Claude.

Cómo crear un mod a mano: ejemplos reales con código

Si prefieres entender el código, estos ejemplos cubren los casos más comunes. Todos van en hooks/register.js.

Ejemplo 1: guardián que bloquea comandos peligrosos

Si usas Claude en modo automático o con permisos de bypass, nada lo frena antes de un git reset --hard. Este mod rechaza comandos destructivos y explica a Claude por qué:

const PELIGROSOS = [
  { patron: /\bgit\s+reset\s+--hard\b/, motivo: 'git reset --hard borra trabajo sin guardar' },
  { patron: /\bgit\s+push\b.*--force/,  motivo: 'push forzado' },
  { patron: /\brm\s+-rf\s+(\/|~)/,      motivo: 'borrado recursivo de la raíz o del home' },
]

async function guardian($, e, next) {
  const regla = PELIGROSOS.find(r => r.patron.test(e.command))
  if (!regla) return next(e)                 // el resto de comandos pasa
  $.ui.toast('Bloqueado: ' + regla.motivo)
  return { deny: 'Comando bloqueado (' + regla.motivo + '). Pide al usuario que lo ejecute él.' }
}

export function register(on) {
  // .catch hace que falle "en cerrado": si el guardián se rompe, no deja pasar el comando
  on('tool.call', { tool: 'Bash' }, guardian).catch(async ($, e, next) =>
    next.called ? next(e) : { deny: 'El guardián falló, así que el comando no se ejecutó.' }
  )
}

Dos detalles importan más que las expresiones regulares:

• El guardián decide antes de llamar a next. En cuanto next se ejecuta, el comando ya ha corrido. Un deny devuelto después no deshace nada.
• El .catch hace que falle en cerrado. Claude Code salta un hook que lanza un error o supera su límite de 10 segundos, y un guardián saltado deja pasar el comando. Con el .catch ocurre lo contrario.

Ejemplo 2: preguntar antes de tocar producción

En lugar de bloquear, un hook puede pausar la llamada y preguntarte con $.ui.ask:

const PRODUCCION = /config\/production|\.env\.production/

export function register(on) {
  on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
    if (!PRODUCCION.test(e.file_path)) return next(e)
    let respuesta = 'Cancelar'                     // respuesta segura por defecto
    try {
      respuesta = await $.ui.ask('¿Modificar ' + e.file_path + '?', ['Sí, modificar', 'Cancelar'])
    } catch {
      // el usuario cerró la pregunta o no hay nadie (claude -p)
    }
    if (respuesta !== 'Sí, modificar') {
      return { deny: 'El usuario no autorizó cambiar la configuración de producción.' }
    }
    return next(e)                                 // después sigue el control de permisos normal
  })
}

La espera dentro de $.ui.ask no cuenta para el límite de 10 segundos del hook, así que puedes tardar lo que quieras en contestar.

Ejemplo 3: un comando instantáneo /rama

Un comando de un mod ejecuta tu función al momento, sin turno del modelo:

export function register(on) {
  on('session.start', async ($, e, next) => {
    try {
      await $.command.register({ name: 'rama', description: 'Muestra la rama de git actual', immediate: true })
    } catch {}                                   // un nombre ya usado lanza error
    return next(e)
  })

  on('command.run', { command: 'rama' }, async ($) => {
    try {
      const r = await $.process.run(['git', 'branch', '--show-current'])
      return { text: r.exitCode === 0 ? 'Rama actual: ' + r.stdout.trim() : 'Esto no es un repositorio git' }
    } catch {
      return { text: 'No se pudo ejecutar git' }
    }
  })
}

Con immediate: true el comando funciona incluso mientras Claude está trabajando. El text que devuelves aparece en el transcript y Claude también lo lee. Si además devuelves context, es una nota que solo lee el modelo.

Ejemplo 4: añadir contexto automático a tus prompts

Este hook añade la rama actual para Claude cada vez que hablas de un pull request, sin que cambie lo que ves en pantalla:

export function register(on) {
  on('prompt.submit', async ($, e, next) => {
    if (!/\bPR\b|pull request/i.test(e.text)) return next(e)
    const git = await $.process.run(['git', 'branch', '--show-current'])
    if (git.exitCode !== 0) return next(e)
    return next({ ...e, context: [...(e.context ?? []), 'Rama actual: ' + git.stdout.trim()] })
  })
}

Ejemplo 5: tareas en segundo plano con un temporizador

Un hook dura un evento. Para trabajo continuo se usa $.clock.every desde session.start. Este ejemplo revisa los checks de un pull request cada minuto y muestra el resultado bajo el prompt:

export function register(on) {
  on('session.start', async ($, e, next) => {
    $.clock.every(60_000, async () => {
      const r = await $.process.run(['gh', 'pr', 'checks'])
      $.ui.status('checks: ' + (r.exitCode === 0 ? 'todo en verde' : 'hay fallos'))
    })
    return next(e)   // no esperes al temporizador: la sesión arranca al momento
  })
}

Para mostrar algo sin arrancar un turno tienes tres opciones:

Probar un mod sin abrir una sesión

claude plugin test ejecuta los archivos *.test.ts del mod sin sesión, sin autenticación y sin red. Como no hay nada «debajo» de tu mod, cada prueba registra sustitutos para lo que el mod deja pasar:

import { expect, test } from 'claude-code/testing'

test('bloquea git reset --hard', async ($, on) => {
  on('tool.call', { tool: 'Bash' }, () => ({ result: { stdout: 'ok', stderr: '', interrupted: false } }))
  const r = await $.tool.call({ tool: 'Bash', command: 'git reset --hard' })
  expect(r.deny).toContain('git reset')
})

Registra los sustitutos al principio de cada prueba, antes de la primera llamada a $. Y para depurar en vivo, arranca con claude --debug: el log nombra cada hook saltado y cada dibujo rechazado.

Mods integrados en Claude Code

Algunas funciones de Claude Code ya son mods. Los ves en /plugin → Installed → Built-in. No se pueden actualizar ni desinstalar, y --safe-mode o disableAllHooks no los apagan.

El código de diff, agents-md, sec-default y telemetry es público en el directorio mods del repositorio de Claude Code. Es la mejor referencia para aprender a escribir mods bien hechos.

Ejemplos reales de mods: oficiales y de la comunidad

Mods de ejemplo de Anthropic

Anthropic publica tres mods de muestra en el repositorio claude-code-playground, y puedes verlos funcionando en claude.dev/mods:

Para probarlos: clona el repositorio y abre la carpeta del mod con --plugin-dir. Se comparten tal cual, sin soporte.

Mods de la comunidad destacados

En los primeros días la comunidad publicó cientos de mods. La mayoría son experimentos, pero algunos son muy útiles:

Para descubrir más, revisa los catálogos awesome-claude-code-mods (karanb192) y awesome-claude-code-mods (whyashthakker), este último con 70 mods organizados por categorías (sesión, git, repositorio, workspace, utilidades, flujo de trabajo y escritorio).

Qué construye la gente con los mods

Según el escaneo del catálogo de la comunidad del 6 de octubre de 2026, cinco días después del lanzamiento ya había 2.690 mods públicos en 1.265 repositorios. Lo más habitual:

Ideas de mods para marketing y contenido

No hace falta ser desarrollador para sacarles partido. Si trabajas con contenido, el valor está en describir cómo quieres que se comporte tu entorno:

• Medidor de contexto al trabajar con newsletters o guiones largos, para saber cuándo abrir una sesión limpia.
• Freno de seguridad sobre la carpeta de borradores, imágenes y exportaciones.
• Siguiente paso para flujos repetitivos: de vídeo a post, de post a notas, de notas a LinkedIn.
• Segundo cerebro en un panel con proyectos, tareas y notas guardadas en $.store.
• Router de modelos para que lo sencillo (resumir, traducir, formatear) no se coma tus límites.

Comunicación entre sesiones con mods

Una de las funciones más potentes: un mod puede enviar mensajes a otra de tus sesiones de Claude Code o a un subagente de la sesión actual, y observar los mensajes que entran y salen.

Enviar un mensaje con $.session.send

$.session.send({ to, text }) hace la misma entrega que la herramienta SendMessage. El destino puede ser { sessionId } para otra sesión o { agentId } para un subagente (lo obtienes con $.agent.list()). La llamada nunca falla en silencio: devuelve { isDelivered: true } o { isDelivered: false, reason }.

on('command.run', { command: 'ping' }, async ($, e) => {
  const r = await $.session.send({ to: { sessionId: e.args }, text: '¿En qué estás? Una línea.' })
  if (!r.isDelivered) $.ui.toast('No entregado: ' + r.reason)
  return {}
})

Recibir y filtrar mensajes

Ejemplo práctico: una sesión planea y otra construye

Con estas piezas puedes montar dos sesiones que trabajan en equipo:

• /duo planner y /duo builder guardan el id de cada sesión ($.session.id()) en $.store, que comparten todas las sesiones de la máquina.
• /plan <texto> en la sesión planner lee el id del builder y le envía el plan con $.session.send.
• En el builder, session.receive muestra «PLAN RECIBIDO» en la banda sobre el prompt y deja pasar el mensaje con next(e) para que Claude empiece a construir.
• En turn.complete, el builder manda un resumen de una línea al planner.
• En el planner, session.receive devuelve { consumed }: el resumen se ve, pero Claude no responde solo. Así se evitan bucles infinitos.

Seguridad en los mensajes: el nombre del remitente es lo que el remitente haya escrito, así que nunca bases una decisión en él. Si una sesión está configurada para rechazar mensajes entrantes (crossSessionInbound), el mensaje se rechaza antes de que el hook lo vea. Más detalles en la documentación de mensajes entre sesiones.

Llamar a otro modelo desde un mod

$.model.complete hace una pregunta suelta a un modelo, sin historial, ideal para clasificar o resumir:

const r = await $.model.complete({
  model: 'haiku',
  system: 'Responde una palabra: FACIL o DIFICIL',
  prompt: e.text,
  maxTokens: 5,
  timeoutMs: 8000,
})
const nivel = r.isAnswered ? r.text.trim() : 'DIFICIL'

Y en turn.step puedes enviar una petición completa a otro modelo. Este hook es un generador asíncrono porque la respuesta llega en streaming:

on('turn.step', async function* ($, e, next) {
  if (turnoFacil && e.agentId === undefined) {
    return yield* next({ ...e, model: 'haiku' })
  }
  return yield* next(e)
})

Permisos y seguridad de los mods de Claude Code

Esta es la parte que más importa. Un mod no es un prompt: es código que se ejecuta con tus permisos.

Qué puede alcanzar un mod

Una vez cargado, un mod puede:

• Actuar en tu máquina como tú: leer y escribir archivos donde tu usuario tenga acceso, lanzar programas y hacer peticiones de red.
• Leer tus secretos: variables de entorno y archivos de configuración, incluidas las API keys.
• Ver tu sesión: cada prompt que envías y cada llamada que hace Claude.
• Cambiar tu sesión: reescribir prompts o llamadas, enviar un prompt como si lo hubieras escrito tú o mandar mensajes a otra sesión.
• Actuar sin preguntarte: aprobar una llamada a herramienta antes de que te pregunten.
• Gastar tu uso: llamar a un modelo con tu plan o tu API key.

Mods y reglas de permisos: quién gana

Ojo con un matiz: las reglas deny se aplican a las herramientas de Claude, no a las llamadas propias del mod. Con Read(.env) denegado, un mod puede seguir leyendo ese archivo con $.fs.read.

Cómo revisar un mod antes de instalarlo

Descarga el plugin (por ejemplo, clonando su repositorio) y ejecuta:

claude plugin validate ./nombre-del-mod

La salida incluye dos líneas clave, sin ejecutar el mod:

❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

La línea hooks: lista los eventos que maneja el mod y la línea calls: lo que pide hacer. Claude Code se niega a cargar un mod que usa la API de una forma que este comando no puede leer. Estas son las llamadas que debes vigilar:

Y en la línea hooks:, presta atención a tool.call y prompt.submit (ve y puede cambiar cada llamada y cada prompt), tool.check (puede aprobar o denegar antes del aviso de permiso) y session.append (puede reescribir el historial antes de guardarlo).

Validar no es lo mismo que confiar. Que un mod pase validate significa que el motor puede cargarlo, no que sea seguro. Lee el código allí donde aparezcan $.process, $.http, $.fs.write, $.env.get o $.model, y vuelve a validarlo después de cada actualización.

Una lección real: los secretos enmascarados

Un autor de la comunidad creó un mod que sustituía las API keys en la salida de las herramientas antes de que Claude las viera. Aun así, Claude imprimió los valores reales mientras depuraba una edición fallida, y una escritura del archivo completo guardó los marcadores encima de las claves reales. Lo único que aguantó fue una regla deny sobre el archivo. Conclusión: un mod que cambia lo que ves no le oculta nada al modelo. Para proteger secretos, usa reglas de permisos.

Checklist de seguridad antes de instalar un mod

• ¿Conozco al autor o al marketplace?
• ¿He ejecutado claude plugin validate y revisado las líneas hooks: y calls:?
• ¿He leído el código de las partes que acceden a archivos, procesos, red o variables de entorno?
• ¿Lo he probado primero en un repositorio de pruebas, nunca directamente en producción?
• ¿Los guardianes tienen .catch para fallar en cerrado?
• ¿Lo crítico está protegido también con reglas deny?
• ¿Sé cómo apagarlo rápido (/plugin o --safe-mode)?

Mods en equipos y empresas

Como los mods viajan dentro de plugins, se aplican los controles de plugins que ya tengas. Los administradores pueden permitir o bloquear marketplaces: en los planes Team y Enterprise desde la consola de administración, y en planes de API o de terceros mediante managed settings. La guía completa está en gestionar mods en tu organización.

El guardián sec-default

En planes Team y Enterprise, y en cualquier máquina con managed settings, se carga primero un mod integrado llamado sec-default («security default»). Los usuarios no pueden desactivarlo. Impide que los mods que instala cada persona:

• Cambien lo que reciben o deciden los hooks gestionados por la organización.
• Modifiquen el system prompt, el CLAUDE.md gestionado u otras instrucciones gestionadas.
• Alteren lo que cualquier mod lee como configuración.
• Toquen las herramientas de los servidores MCP gestionados.
• Aprueben una llamada que una regla deny rechaza.

Fuera de eso, el guardián no añade más restricciones. Y falla en cerrado: si no puede leer la configuración gestionada, rechaza todos los mods de usuario.

Bloquear todos los mods de usuario

Para que solo carguen los mods de la organización, se activa allowManagedModsOnly en managed settings:

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

Con esta opción no carga ningún mod que traiga el usuario (instalado, cargado con --plugin-dir o escrito por Claude en una sesión). Los usuarios no pueden deshacerlo desde sus propios archivos de configuración, y sus hooks de configuración y status lines siguen funcionando.

Niveles de política para mods

Existe además allowModsToOverrideDenyRules: si lo activas, un mod de usuario podría aprobar llamadas que una regla deny rechaza. Úsalo solo si sabes exactamente por qué.

Desplegar mods propios de la organización

Para que Claude Code trate un mod como de tu organización, debe cumplir tres condiciones: estar activado en enabledPlugins gestionado, venir de un marketplace que es un directorio local con ruta absoluta, y estar listado por ruta relativa. Un ejemplo de configuración:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}

Si defines prependPlugins, incluye sec-default@builtin en la lista o perderás el guardián. Y protege el directorio para que solo un administrador pueda escribir en él: quien pueda escribir ahí puede reescribir tu mod.

Mods de política: revisar a los demás mods

Con el evento plugin.register, un mod de la organización recibe la misma lista que imprime validate cada vez que otro mod va a cargar, y puede rechazarlo. Por ejemplo, para impedir mods de usuario que lancen procesos:

const PROHIBIDAS = ['process.run', 'process.spawn']

export function register(on) {
  on('plugin.register', async ($, e, next) => {
    const usadas = e.uses.calls.filter(c => PROHIBIDAS.includes(c))
    if (e.tier === 'user' && usadas.length > 0) {
      return { refuse: 'Política de la empresa: los mods no pueden usar ' + usadas.join(', ') }
    }
    return next(e)
  })
}

Ideas de mods para equipos

• Estado de CI/CD: un panel junto a la conversación que se actualiza cuando los builds pasan o fallan.
• Protección de producción: confirmación obligatoria antes de tocar configuración de producción.
• Registro de auditoría: un mod que carga primero y registra cada llamada que hacen los demás mods.
• Convenciones del equipo: inyectar en los prompts las reglas de nombres o de commits sin repetirlas cada vez.

Buenas prácticas para escribir mods

• Los guardianes deciden antes de next y fallan en cerrado con .catch. Los mods que solo observan deben fallar en abierto (.catch(($, e, next) => next(e))) para que un fallo en un medidor nunca bloquee tu trabajo.
• Espera dentro de las llamadas a $. Un hook tiene 10 segundos de tiempo propio; las esperas en $.process.run o $.ui.ask no cuentan, pero tus propias promesas sí.
• No guardes ni desestructures $. Pásalo solo a funciones definidas en el nivel superior del archivo.
• Guarda lo que dibujas en $.state, no en variables del módulo: la recarga en caliente reinicia las variables. Para que algo sobreviva a /clear o entre sesiones, usa $.store.
• La banda sobre el prompt es compartida. Llama a next(e) e incluye su resultado en tu dibujo, o esconderás lo que dibujan otros mods.
• Registra los comandos al final de session.start o dentro de try/catch: un nombre ya usado lanza error y salta el resto del hook.
• Registra cada evento una sola vez por filtro, o el módulo no cargará.
• Decide según e.surface: algunos elementos solo dibujan en la terminal y otros solo en la app de escritorio.
• Cuida la caché de prompts: evita cambiar modelo o system prompt sin necesidad.
• Desarrolla con --plugin-dir: un mod instalado ejecuta una copia en caché, así que editar su carpeta no cambia nada hasta que lo actualizas.

Problemas comunes con los mods y cómo solucionarlos

Cómo compartir tu mod

Añade un marketplace.json junto a plugin.json dentro de .claude-plugin/:

{
  "name": "mis-mods",
  "owner": { "name": "tu-nombre" },
  "plugins": [{ "name": "guardian", "source": "./" }]
}

Sube la carpeta a GitHub y cualquiera podrá añadir tu marketplace e instalar el mod. Antes de publicar, valida el plugin y el catálogo con claude plugin validate. Si quieres más visibilidad, puedes enviarlo al directorio de Claude, y si añades el topic claude-code-mod a tu repositorio, los catálogos de la comunidad suelen incluirlo.

Si vas a publicar una nueva versión, sube el número de version en plugin.json; los usuarios la reciben con claude plugin marketplace update y claude plugin update.

Preguntas frecuentes sobre los mods de Claude Code

¿Qué es un mod de Claude Code?

Es un plugin con funciones en TypeScript o JavaScript que se ejecutan dentro de Claude Code. Se engancha a eventos como una llamada a herramienta, un prompt o el dibujo de la pantalla, y puede observarlos, cambiarlos o responder en su lugar.

¿Necesito saber programar para usar mods?

No. Puedes instalar mods de otras personas con un comando o describir el mod que quieres en una sesión y Claude lo escribe, lo instala y lo recarga en caliente.

¿Qué versión de Claude Code necesito?

La 2.1.287 o superior en la terminal y la 2.1.286 o superior en la app de escritorio. Los mods vienen activados por defecto.

¿Los mods funcionan en Claude.ai o solo en Claude Code?

Solo en Claude Code: en la CLI y en la pestaña Code de la app de escritorio. En la extensión de VS Code, en claude -p y en sesiones en la nube los hooks se ejecutan, pero la interfaz del mod no se dibuja.

¿En qué se diferencia un mod de un hook?

Un hook de configuración es un script que Claude Code lanza desde fuera. Un mod corre dentro del proceso de Claude Code, así que puede dibujar interfaz, reescribir eventos, crear comandos instantáneos y sustituir funciones integradas, cosas que un hook no puede hacer.

¿Son seguros los mods?

Son tan seguros como su autor. No van en sandbox y tienen los mismos permisos que Claude Code: pueden leer archivos, secretos y variables de entorno, lanzar procesos y hacer peticiones de red. Instala solo mods de fuentes de confianza y revísalos con claude plugin validate.

¿Un mod puede saltarse mis reglas de permisos?

En una máquina personal sin managed settings, un mod que aprueba llamadas puede aprobar incluso algo que una regla deny rechaza. En planes Team y Enterprise o con managed settings, el guardián sec-default impide que un mod de usuario anule las reglas deny. Ningún mod puede cambiar lo que muestra el aviso de permiso.

¿Cómo desactivo todos los mods?

Para una sesión, arranca con claude --safe-mode. Para siempre, pon "disableAllHooks": true en ~/.claude/settings.json. Para uno concreto, desactívalo desde /plugin.

¿Puede una empresa bloquear los mods?

Sí. Con allowManagedModsOnly en managed settings solo cargan los mods de la organización. También se pueden limitar los marketplaces permitidos, bloquear --plugin-dir con disableSideloadFlags o desplegar un mod de política que revise a los demás.

¿Pueden comunicarse dos sesiones de Claude Code con mods?

Sí. Con $.session.send un mod envía mensajes a otra sesión o a un subagente, y con el evento session.receive decide qué hacer con los que llegan. Así puedes montar, por ejemplo, una sesión que planifica y otra que construye.

¿Los mods gastan tokens o uso de mi plan?

Solo si llaman a un modelo con $.model.complete, $.model.fork o envían prompts. Un mod que solo dibuja o bloquea comandos no consume tokens. Ten en cuenta que cambiar de modelo invalida la caché y puede encarecer los turnos.

¿Dónde encuentro mods para instalar?

En el directorio de Claude, en los ejemplos oficiales de claude-code-playground y en catálogos de la comunidad como awesome-claude-code-mods.

Conclusión: Claude Code ya es tuyo

Los mods de Claude Code no son un cambio enorme a simple vista, pero marcan un giro importante: ya no se trata solo de crear skills o conectar herramientas, sino de que el propio entorno de trabajo se vuelve modificable. Puedes añadirle medidores, frenos de seguridad, paneles, comandos y hasta hacer que varias sesiones colaboren entre sí.

Mi recomendación para empezar:

Fuentes y documentación oficial

• Anthropic: Customize Claude Code with mods (anuncio oficial)
• Documentación oficial: Mods overview
• Documentación oficial: React to events
• Documentación oficial: Use the mods API
• Documentación oficial: Manage mods for your organization
• Lorena Bordonaba: Los mods de Claude Code, qué son y cómo usarlos
• DataPath: Claude Code Mods, así puedes personalizarlo con TypeScript
• CursosDesarrolloWeb: Mods de Claude Code en un equipo
• AcademIArtificial: Claude Code estrena mods para personalizar su funcionamiento
• Kanaries: Tutorial de Claude Code Mods con 15 ejemplos de la comunidad
• The AI Studio (Medium): 9 Claude Code Mods You Need to Install