Mods de Claude Code: tutorial para crear el tuyo paso a paso

Llevaba semanas con la misma manía: escribir /context cada dos por tres para ver cuánto me quedaba antes de compactar y luego revisar el uso del plan para saber si el límite de 5 horas me iba a dejar tirado a media tarde.

Dos consultas para una pregunta: ¿me da para seguir?

Con los mods de Claude Code esa pregunta ya tiene respuesta permanente en mi terminal. Y lo mejor es cómo llegué hasta ahí: no escribí ni una línea de código. Se lo fui pidiendo a Claude, turno a turno, hasta que quedó así:

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✻ Listo. He movido la validación al hook y los tests pasan.                                                │
│                                                                                                            │
│ ctx █░░░░░░░░░ 14% ~93 turnos   5h ▒░░░░░░░░░ 1% →7% ↻4h20   sem █████▒▒░░░ 54% →72% ↻1d17h   caché ◕ 42m  │
│ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ >                                                                                                      │ │
│ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Cuatro lecturas en una línea: el contexto gastado, el límite de 5 horas, el semanal y los minutos de vida que le quedan a la caché. Las partes con ▒ son la previsión: lo que vas a gastar hasta que se renueve el límite si sigues a este ritmo. Además tiene un panel lateral con el detalle y un aviso flotante cuando la caché está a punto de caducar.

En este post vas a encontrar:

• Qué es un mod y cuándo te compensa frente a un hook, una skill o un MCP
• Cómo pedirle a Claude que te construya uno, con los prompts reales que usé
• Los cuatro sitios donde un mod puede enseñarte cosas: línea, panel, aviso y status line
• Un guardián que comprueba algo antes de cada commit y frena a Claude si falla
• Ideas de mods para pedir, cómo instalarlos y qué riesgo asumes con los ajenos

¿Qué es un mod de Claude Code? ¶

Un mod es un plugin de Claude Code con un módulo de JavaScript o TypeScript dentro. Ese módulo se engancha a lo que pasa en tu sesión (una llamada a herramienta, un prompt enviado, un turno que termina o una parte de la interfaz que se está dibujando) y puede mirarlo, cambiarlo o quedarse con él.

Si leíste el post sobre function hooks de Claude Code, esto te sonará. Aquella propuesta estaba detrás de un flag experimental. Hoy se llama mods, viene activada por defecto desde Claude Code 2.1.287 y la documentación oficial avisa de que, si aún tienes CLAUDE_CODE_ENABLE_FUNCTION_HOOKS puesto, lo quites: ya no hace nada.

Por dentro funciona como un middleware de Express o Koa. Cada evento pasa por tu mod antes de llegar a Claude Code, y tu mod puede hacer tres jugadas:

1. Observar: deja pasar el evento y apunta lo que ha ocurrido. Es lo que hace la barra de consumo.
2. Reescribir: cambia el evento antes de que siga. Por ejemplo, añadir texto al spinner.
3. Contestar: se queda con el evento y responde por su cuenta. Por ejemplo, bloquear un comando.

🔑 Un mod se carga una vez y se queda vivo en la sesión. Un hook de settings arranca un proceso de shell por cada evento. Por eso un mod puede guardar estado, redibujar interfaz y responder comandos al instante.

Mods, hooks de settings, skills y MCP: cuál usar ¶

La documentación oficial trae una tabla comparativa que resume bien cuándo tirar de cada pieza. Te la dejo adaptada:

Tampoco tienes que elegir uno. Un plugin puede llevar skills, servidores MCP y un mod a la vez, y se instala igual que los que ya conoces de la lista de plugins más populares de Claude Code.

Para la barra de consumo no había duda. Ninguna de las otras tres piezas puede dibujar nada en la terminal.

Guía interactiva gratis

Antes de modificar el agente, aprende a leer su contexto

Si la ventana de contexto o los límites aún te suenan a chino, el curso tiene una parada entera sobre el contexto y otra sobre skills y MCP, las piezas que luego empaqueta un plugin.

Entra en el curso gratis →

¿Cómo se le pide un mod a Claude? ¶

Describiendo lo que quieres ver, no cómo programarlo.

Es el camino que recomienda el propio artículo de Anthropic. Claude Code trae de serie una skill llamada plugin-authoring (en /plugin aparece como cc-plugin-plugin-authoring) que le enseña a Claude dónde guardar el estado, qué eventos usar y cómo validar el resultado. Tú no necesitas saberte la API. Necesitas saber qué quieres mirar y cuándo.

Mi primer prompt fue tan escueto como esto:

Quiero un mod que me muestre una barra chula y bonita de cuánto % de contexto
he consumido, cuánto del límite de 5 horas y cuánto del semanal.

Funcionó, pero un prompt más completo te ahorra iteraciones. El ejemplo que publica Anthropic para su mod Token Weather tiene una estructura que copiaría siempre:

Hazme un mod de Claude Code llamado token-weather: una previsión en vivo de mi
ventana de contexto, en la banda de encima del prompt.

Qué debe enseñar, en una línea:
- Un icono y una palabra según lo lleno que esté el contexto: por debajo del 25 %
  ☀ Despejado (amarillo), 25–49 % ☁ Nublado (cian)... y 90 % o más ↯ Compacta ya (rojo).
- El porcentaje usado y los tokens, tipo "134.4k / 200k".
- Un minigráfico de los últimos 12 turnos con ▁▂▃▄▅▆▇█.
- Cuánto sumó el último turno, tipo "▲ +98.3k last turn".

Debe actualizarse después de cada turno.

Fíjate en lo que tiene: dónde aparece (la banda encima del prompt), qué enseña con ejemplos literales de cómo debe verse, umbrales y colores concretos y cuándo se actualiza. No dice ni un nombre de evento ni de función.

A partir de ahí pasan tres cosas:

1. Claude escribe el mod en una carpeta propia de la sesión, ~/.claude/dev-mods/<id-de-sesión>/<nombre-del-mod>/.
2. En cuanto aparece el primer fichero, Claude Code te pregunta una única vez: “Enable hot reloading for this session?”. Esa respuesta la das tú; ni el modo de permisos ni ninguna regla la contestan por ti.
3. Si aceptas, el mod se carga al terminar el turno. Desde ese momento, cada cambio que pidas se recarga solo cuando acaba el turno que lo hizo.

Ese tercer punto lo cambia todo. Pides “más corto”, termina el turno y lo ves. Pides “en una línea”, termina el turno y lo ves. Es como trabajar con un diseñador sentado a tu lado que entrega en treinta segundos.

⚠️ La carpeta dev-mods es temporal y se limpia más adelante. Si el mod te gusta, pídele a Claude que lo copie fuera antes de cerrar el chiringuito. Lo vemos en la sección de instalar.

La conversación entera: los prompts que usé ¶

Token Garden no salió así a la primera. Estos son los mensajes que fui escribiendo, tal cual, y lo que cambió con cada uno:

El nombre se quedó aunque ya no hay ni una planta. Pasa en las mejores familias.

Lo que más me gustó del proceso es lo barato que sale equivocarse. Las frases de jardinería me parecieron una idea estupenda durante dos turnos. Al tercero ya no las entendía ni yo, y deshacerlo costó un mensaje.

Los cuatro sitios donde un mod te enseña cosas ¶

Esto me lió al principio, así que te lo dejo claro. Un mod puede dibujar en cuatro sitios distintos, y cada uno sirve para algo:

La línea es la que viste al principio del post. El panel de Token Garden se abre con /tokens y cuenta lo que te queda, no lo que llevas gastado:

╭─ Lo que te queda ──────────────────────────────────────────╮
│ Contexto        77% libre                                  │
│ █████░░░░░░░░░░░░░░░░░░░                                   │
│ 154.8k tokens libres de 200k · ~14 turnos al ritmo actual  │
│ ▂▂▃▃▄▅ últimos turnos                                      │
│                                                            │
│ Límite 5 horas  71% libre                                  │
│ ███████▒▒▒▒▒▒▒▒▒▒░░░░░░░                                   │
│ a este ritmo llegarás al 72% · se renueva en 3h00          │
│                                                            │
│ Límite semanal  46% libre                                  │
│ █████████████▒▒▒▒▒░░░░░░                                   │
│ a este ritmo llegarás al 72% · se renueva en 1d17h         │
│                                                            │
│ Caché           ◕ 42m de vida                              │
│ ██████████████████░░░░░░                                   │
│ te aviso cuando queden 5m                                  │
╰────────────────────────────────────────────────────────────╯

Un detalle que conviene saber antes de pedir un panel: si lo abres tú (con un comando o un botón), aparece con cualquier ancho de terminal. Si el mod lo abre solo al empezar la sesión, solo se coloca al lado cuando la terminal tiene 144 columnas o más. Por debajo, espera.

El aviso flotante es el que más me ha sorprendido. Es una cajita que aparece arriba a la derecha con el nombre del plugin, se queda unos segundos y desaparece. Si pasas el ratón por encima se queda quieta, y si haces clic se cierra:

╭──────────────────────────────────────────────╮
│ token-garden                                 │
│ ⏳ La caché caduca en 4m. Si tardas más en    │
│ escribir, el próximo mensaje sale caro y se  │
│ re-cachearán ~134.4k tokens.                 │
╰──────────────────────────────────────────────╯

💡 Cuando pidas un aviso que solo salta en condiciones raras (como “a la caché le quedan 5 minutos”), pide también un comando de demo que lo lance a mano. Yo pedí /aviso-cache para no tener que esperar una hora sin tocar el teclado.

¿Qué hay dentro de la carpeta de un mod? ¶

Pocas cosas. Esta es la estructura de Token Garden:

token-garden/
├── .claude-plugin/
│   ├── plugin.json        ← nombre, versión y descripción del plugin
│   └── types/             ← los tipos de tu versión de Claude Code (los genera él)
├── hooks/
│   ├── hooks.json         ← dice qué fichero tiene el código
│   ├── register.tsx       ← el mod: unas 270 líneas que escribió Claude
│   └── register.test.ts   ← los tests
└── types/
    └── index.d.ts         ← qué datos guarda el mod entre recargas

Lo que cada uno aporta:

• plugin.json es el manifiesto de cualquier plugin. Nada especial.
• hooks.json apunta al módulo. Un mod tiene uno y solo uno.
• register.tsx es el mod en sí. Ahí viven los enganches a eventos y lo que se dibuja.
• types/index.d.ts declara cada dato que el mod guarda. Si Claude se olvida de declarar uno, la validación falla y le dice qué añadir.
• .claude-plugin/types/ lo escribe Claude Code cada vez que carga el mod: unas 14.000 líneas con cada evento y cada función de tu versión exacta. Es lo que consulta Claude para no inventarse la API.

¿De dónde saca el mod los números? ¶

De Claude Code. Un mod puede preguntarle por el uso de la sesión y recibe las mismas cifras que ves en la status line: tokens de contexto, tamaño de la ventana y, para cada límite, el porcentaje usado y la hora a la que se renueva. Esa consulta no gasta tokens.

Además, Claude Code avisa al mod cada vez que algo cambia: después de cada turno y cada vez que un límite sube un punto entero. Así el mod no tiene que estar preguntando todo el rato.

Dos detalles que conviene saber antes de pedir nada:

• Los límites solo llegan si tienes suscripción, y después de la primera respuesta del modelo. Con API key solo vas a ver el contexto.
• El porcentaje de los límites es de tu cuenta, no de la sesión. Si tienes tres terminales abiertas, el 54 % semanal es la suma de todas.

Ese segundo punto me resolvió la previsión sin guardar ni un dato extra. Lo vemos en un momento.

¿Por qué la barra se redibuja sola? ¶

Porque el dibujo está suscrito a los datos.

Claude Code guarda los datos del mod fuera del propio mod, en un almacén que sobrevive a las recargas. Eso importa: cada vez que pides un cambio, el mod se recarga desde cero, y si los datos vivieran dentro se perderían. Cuando el mod dibuja la barra lee esos datos, y esa lectura lo suscribe: cualquier cambio posterior redibuja la barra sin que nadie lo pida.

Cuatro cosas escriben en ese almacén: el arranque de la sesión, cada medición nueva de uso, el final de cada turno y un reloj que hace tic cada minuto. Ese reloj existe por la caché: sin él, la cuenta atrás se quedaría congelada mientras tú piensas, porque no pasa nada más.

Si vienes de React, es el mismo modelo mental que un estado global con selectores.

¿Cómo se calcula la previsión de los límites? ¶

Con una regla de tres y una observación: si sabes cuándo se renueva una ventana y cuánto dura, sabes cuándo se abrió.

La ventana de 5 horas se abrió 5 horas antes de su renovación, y la semanal, 7 días antes. Con eso tienes el tiempo transcurrido y el porcentaje gastado, o sea, tu ritmo medio desde que empezó la ventana. Lo prolongas hasta la renovación y ves dónde acabas.

Salen dos casos:

• Si al ritmo actual no llegas al 100 %, la barra pinta con ▒ hasta donde acabarás y el texto dice →72% ↻1d17h: llegarás al 72 % y se renueva en 1 día y 17 horas.
• Si llegas antes, la barra se llena hasta el final y el texto cambia a ⚠ agotado en 2h00.

Como el porcentaje es de la cuenta entera, esta previsión ya incluye lo que has gastado en otras sesiones dentro de la misma ventana. Mi idea inicial era guardar un historial de “las últimas sesiones”, y resulta que el propio dato ya lo traía.

El cálculo usa un ritmo medio, así que en la semanal cuenta también las noches y los fines de semana sin tocar el teclado. Si trabajas a ráfagas, la previsión se quedará corta al principio del día. Para no inventar con pocos datos, durante el primer 5 % de la ventana (15 minutos en la de 5 horas) solo muestra cuándo se renueva.

El contexto va aparte: el mod mira cuántos tokens ha sumado cada uno de los últimos cinco turnos y calcula cuántos turnos así caben en lo que queda libre. Si un turno resta tokens, es que hubo compactación, y lo descarta.

Domina la herramienta a fondo

Los hooks, agentes y MCP que hay debajo de cualquier mod

Un mod se apoya en lo que Claude Code ya hace por dentro. En la masterclass verás hooks, agentes, CLAUDE.md, MCP y los workflows que usamos en proyectos reales.

Entrar a la masterclass →

Masterclass en directo · 2h30

¿Se puede saber cuánto le queda a la caché? ¶

A ojo, sí.

La caché de prompt tiene un tiempo de vida desde la última petición: 1 hora en sesiones con suscripción como la mía, 5 minutos en muchos casos con API key. Si escribes cuando ya ha caducado, Claude Code vuelve a mandar y cachear todo el contexto, y ese mensaje sale bastante más caro. Es uno de los agujeros por los que se escapa la cuota que repaso en cómo ahorrar tokens en Claude Code.

Claude Code no le dice al mod cuánto dura su caché ni cuándo fue la última petición. Así que la estimación es casera: el mod apunta la hora a la que termina cada turno y cuenta una hora desde ahí. En la línea aparece un reloj que se vacía (●◕◑◔○) y cambia a ámbar por debajo de 15 minutos y a rosa por debajo de 5. Cuando quedan 5 minutos salta el aviso flotante, una sola vez hasta el siguiente turno.

⚠️ Si usas API key, pídele a Claude que cambie la duración de la caché a 5 minutos. El mod no tiene forma de saberlo por sí mismo.

Este es un buen ejemplo de algo que la IA te tiene que contar. Cuando pedí la caché, Claude me avisó de que la API no daba ese dato y de que lo iba a aproximar. Si no te lo dice, pregúntaselo: “¿hay algo de esto que estés suponiendo en vez de leerlo?”.

Un hook que comprueba algo y frena a Claude ¶

Hasta aquí todo es mirar y dibujar. Pero un mod también puede ponerse en medio de lo que hace Claude y pararlo.

El caso más útil que se me ocurre: que Claude no pueda hacer git commit si una comprobación falla. Le pedí esto:

Hazme un mod llamado commit-guard. Cada vez que Claude vaya a ejecutar un
git commit, antes ejecuta `git diff --cached --check`. Si falla, bloquea el
commit, enséñame un aviso flotante y dile a Claude qué ha fallado para que lo
arregle él. Si pasa, que el commit siga normal.

git diff --cached --check es una comprobación que trae git de serie: falla si lo que vas a commitear tiene espacios sobrantes al final de línea o marcadores de conflicto olvidados. Sirve para cualquier proyecto, pero puedes cambiarla por tu linter, tus tests o lo que quieras.

Así se ve cuando salta (recreación):

⏺ Bash(git commit -m "feat: añade validación del formulario")
  ⎿  Error: commit-guard: `git diff --cached --check` falló. Corrige esto antes de hacer commit:
     src/form.js:12: trailing whitespace.

⏺ Hay un espacio al final de la línea 12 de src/form.js. Lo quito y repito el commit.

Y arriba a la derecha:

╭──────────────────────────────────────────────╮
│ commit-guard                                 │
│ 🚫 Commit bloqueado: la comprobación ha      │
│ fallado                                      │
╰──────────────────────────────────────────────╯

Lo bonito es que el mensaje del bloqueo le llega a Claude como resultado de su herramienta. No se queda atascado: lee qué ha fallado, lo arregla y lo vuelve a intentar.

Tiene un límite que conviene conocer. El mod lee el texto del comando, así que un alias, un script que haga el commit por dentro o un $(...) se le cuelan. Anthropic dice lo mismo de su mod Blast Radius: es una red de seguridad, no un sistema de permisos. Si necesitas un bloqueo duro, usa las reglas de permisos de Claude Code.

Consejos para pedirle mods a la IA ¶

Después de una tarde entera iterando, estas son las cosas que me habría gustado saber al empezar:

1. Describe lo que ves, no cómo se hace. “Una línea encima del prompt con…” funciona mejor que “un hook de ui.render que…”. Claude ya sabe la API; tú sabes lo que quieres mirar.
2. Da ejemplos literales. Escribe cómo quieres que se vea el texto: 134.4k / 200k, →72% ↻3h00. Es la forma más rápida de que acierte a la primera.
3. Pon números a los umbrales. “Rojo a partir del 90 %” en vez de “rojo cuando esté lleno”.
4. Un cambio por turno. Cada turno recarga el mod. Si pides cinco cosas a la vez y algo no te gusta, no sabrás cuál deshacer.
5. Pide comandos de demo para todo lo que salte en condiciones raras.
6. Pide que lo valide y lo pruebe. “Pasa claude plugin validate, escribe tests y ejecútalos” debería ir al final de cada petición gorda.
7. Pregunta qué está suponiendo. Como con la caché: hay datos que el mod no puede leer y tiene que estimar.
8. Si no lo entiendes tú, no vale. Mis frases de jardinería eran muy ingeniosas y no servían para nada. Lo gráfico ganó.

🎯 Si vas a hacer tu primer mod, empieza por algo que mires veinte veces al día. La línea encima del prompt es el mejor punto de partida: Claude Code no dibuja nada ahí, así que no rompes nada.

Validar y probar sin leer el código ¶

No necesitas leer el código para comprobar que el mod hace lo que dice. Hay tres comandos, y lo normal es pedirle a Claude que los ejecute él:

claude plugin validate ./token-garden   # qué eventos escucha y a qué llama
claude plugin test ./token-garden       # ejecuta sus tests
tsc -p ./token-garden                   # comprueba los tipos

El primero es el más interesante para ti, porque resume el mod en dos líneas que se entienden sin programar:

❯ hooks: session.start, command.run{command=tokens}, command.run{command=aviso-cache}, turn.complete,
         session.measure, ui.render{component=AbovePrompt}, ui.render{component=Pane, requestId=token-garden}
❯ calls: $.clock.every, $.clock.now, $.command.register, $.session.usage, $.state.get, $.state.set,
         $.ui.open, $.ui.resolve, $.ui.toast

hooks dice a qué eventos se engancha y calls qué le pide a Claude Code. Si un mod de “temas de colores” aparece llamando a $.http.fetch (red) y $.process.run (ejecutar programas), algo huele raro.

Por el camino, Claude se encontró varios errores que resolvió solo leyendo los mensajes de la validación y de los tests: un evento que necesitaba otra forma de escribirse, tipos más estrictos de lo esperado o tests a los que les faltaba simular una parte de Claude Code. Ninguno necesitó que yo interviniera. Lo único que tuve que hacer fue pedirle que validara y testeara cada vez.

¿Cómo instalas el mod de forma permanente? ¶

Un mod se comparte igual que cualquier otro plugin: dentro de un marketplace. Puede ser tan sencillo como una carpeta con el mod dentro y un .claude-plugin/marketplace.json que lo nombre:

mis-mods/
├── .claude-plugin/
│   └── marketplace.json   ← nombre del marketplace y lista de plugins
└── token-garden/          ← la carpeta del mod, copiada desde dev-mods

Con eso, desde tu shell:

claude plugin marketplace add ./mis-mods
claude plugin install token-garden@mis-mods --scope user

Si lo subes a un repositorio de GitHub, ese repo se convierte en tu marketplace. Cualquiera puede instalarlo desde una sesión de Claude Code con tres comandos:

/plugin marketplace add tu-usuario/mis-mods
/plugin install token-garden@mis-mods
/reload-plugins

Para actualizarlo, un git push normal. Y si quieres que lo encuentre gente que no tiene tu enlace, el directorio de Claude acepta plugins con mods en claude.ai/directory/manage.

Para comprobar qué mods tiene cargados tu sesión, abre /plugin. Bajo las pestañas aparece una línea tenue del estilo 1 mod active · token-garden. Si el tuyo no sale, claude --debug te dirá por qué.

Ideas de mods para pedirle a Claude ¶

La documentación resume lo que puede hacer un mod en cinco capacidades: dibujar paneles y bandas con botones, redibujar partes de Claude Code como el spinner, meterse en una llamada a herramienta, añadir comandos propios que se ejecutan sin gastar un turno y compartir datos entre sus distintas piezas.

Traducido a cosas que podrías pedir mañana:

• Contador en el spinner. “Añade al spinner cuántas herramientas ha usado Claude en este turno.” Es el ejemplo de la documentación oficial.
• /aqui. “Un comando que me diga la carpeta actual y lo que hay dentro, sin pasar por Claude.” Se ejecuta al instante y no gasta tokens.
• Freno de mano para comandos peligrosos. “Antes de un rm -rf o un git reset --hard, enséñame qué se perdería y dame botones para seguir o cancelar.” Es Blast Radius, uno de los ejemplos de Anthropic.
• Repaso de cambios. “Al acabar cada turno, déjame recorrer los ficheros que ha editado Claude, diff a diff.” Es Replay Theater, otro de los ejemplos oficiales.
• Turnos lentos. “Si un turno tarda más de dos minutos, avísame con un toast.” El ejemplo de la skill de Claude hace justo eso.
• Guardián de rama. “Si Claude intenta hacer push a main, bloquéalo y dile que use una rama.”
• Coste en vivo. “Enséñame encima del prompt cuánto llevo gastado en esta sesión.” El uso de la sesión trae también el coste.

Si quieres ver cómo están hechos por dentro, Anthropic publica tres mods de ejemplo (token-weather, blast-radius y replay-theater) en el repositorio claude-code-playground. Y varios mods que vienen dentro de Claude Code (como /diff o la carga de AGENTS.md) están en la carpeta mods/ del repositorio oficial. Sí, parte de Claude Code ya está construido con mods.

¿Es seguro instalar mods de otros? ¶

Tanto como instalar un paquete de npm de un desconocido. O sea, depende de quién lo haya escrito.

Un mod se ejecuta con tus permisos y no está aislado. Según la documentación oficial, una vez cargado puede:

• Leer y escribir ficheros en cualquier sitio donde llegue tu usuario, arrancar programas y hacer peticiones de red
• Leer tus secretos: variables de entorno y ficheros de configuración, API keys incluidas
• Ver cada prompt que envías y cada llamada a herramienta que hace Claude
• Reescribir prompts o llamadas, o enviar un prompt como si lo hubieras escrito tú
• Aprobar una llamada a herramienta sin preguntarte
• Gastar tu cuota llamando a un modelo con tu plan o tu API key

Incluso si tienes el sandbox activado, ese sandbox aísla los comandos Bash que ejecuta Claude, no los procesos que arranca un mod. La única parte de la interfaz que un mod no puede tocar es el aviso de permisos.

🛡️ Antes de instalar un mod ajeno, clónalo y pasa claude plugin validate por su carpeta. Las líneas hooks: y calls: te dicen qué eventos escucha y qué le pide a Claude Code sin ejecutar nada.

Si algo va mal, tienes tres niveles de apagado: desactivar un mod concreto desde /plugin, arrancar una sesión con --safe-mode (que apaga todos los mods instalados y el resto de personalizaciones) o poner "disableAllHooks": true en ~/.claude/settings.json para todas las sesiones. Ojo, que esto último también apaga tus hooks de settings y tu status line personalizada.

¿Dónde funcionan los mods? ¶

Los hooks se ejecutan en casi cualquier sitio donde se cargue el plugin. Lo que se dibuja es más restrictivo:

Para Token Garden esto significa que en VS Code no verás la barra, aunque el mod siga recogiendo datos por detrás. El guardián de commits, en cambio, funciona en todas partes, porque bloquear no necesita dibujar nada.

TL;DR ¶

• 🧩 Un mod es un plugin con código que se engancha a los eventos de Claude Code para mirarlos, cambiarlos o pararlos. Viene activado por defecto desde la 2.1.287.
• 🗣️ No necesitas saberte la API: describe dónde, qué, con qué umbrales y cuándo, acepta la recarga en caliente y ve pidiendo cambios turno a turno.
• 🖥️ Tienes cuatro sitios para enseñar cosas: la línea encima del prompt, un panel, un aviso flotante y la status line.
• 🚫 Un mod puede comprobar algo antes de un comando y bloquearlo, y Claude recibe el motivo para arreglarlo él solo.
• 🛡️ Un mod ejecuta con tus permisos y sin sandbox. Pasa claude plugin validate antes de instalar nada ajeno.

Preguntas frecuentes sobre los mods de Claude Code ¶

¿Qué versión de Claude Code necesito para usar mods? ¶

La 2.1.287 o posterior. Compruébalo con claude --version. Los mods vienen activados por defecto y no hace falta ningún flag. Si tenías CLAUDE_CODE_ENABLE_FUNCTION_HOOKS de la época de early access, quítalo porque ya se ignora.

¿Necesito saber programar para crear un mod? ¶

No para pedirlo. Claude Code trae una skill que le enseña a Claude a escribir mods, y tú solo describes lo que quieres ver. Sí te ayuda entender las cuatro superficies (línea, panel, aviso y status line) y pedir siempre que valide y pruebe lo que escribe.

¿Qué diferencia hay entre un mod y un hook de settings? ¶

Un hook de settings ejecuta un comando de shell (o una petición HTTP, o un prompt) en cada evento y se comunica por JSON. Un mod se carga una vez dentro de Claude Code y se queda vivo: mantiene estado, dibuja interfaz que se actualiza y puede registrar comandos propios.

¿Cómo muestro el porcentaje de contexto en la terminal? ¶

Pídele a Claude un mod que lo dibuje en la línea encima del prompt. Claude Code le da al mod los tokens de contexto y el tamaño de la ventana después de cada turno, y la línea se redibuja sola cada vez que cambian.

¿Puedo ver el límite de 5 horas y el semanal desde un mod? ¶

Sí, con el porcentaje usado y la hora de renovación de cada uno. Solo llegan si usas Claude Code con suscripción y después de la primera respuesta del modelo. Con API key solo verás el contexto.

¿Qué es un toast en Claude Code? ¶

Un aviso flotante que aparece arriba a la derecha de la conversación con el nombre del plugin que lo lanza. Dura unos segundos, se queda quieto si pasas el ratón por encima y se cierra con un clic. Cualquier mod puede lanzar uno.

¿Un mod puede bloquear lo que hace Claude? ¶

Sí. Puede engancharse a una llamada a herramienta, ejecutar una comprobación y negarla con un motivo que Claude recibe como error. Lee el texto del comando, así que no es un sistema de permisos: para bloqueos duros usa las reglas de permisos de Claude Code.

¿Cómo pruebo un mod sin instalarlo? ¶

Si se lo pides a Claude, él mismo lo deja en una carpeta temporal con recarga en caliente. Si lo tienes en una carpeta, arranca con claude --plugin-dir ./mi-mod: se carga solo para esa sesión y se recarga cada vez que guardas.

¿Cómo comparto un mod con mi equipo? ¶

Igual que cualquier plugin: mételo en un repositorio con un .claude-plugin/marketplace.json y tu equipo lo instala con /plugin marketplace add usuario/repo y /plugin install nombre@marketplace. Las actualizaciones llegan con un git push.

¿Cómo desactivo todos los mods si algo va mal? ¶

Arranca con claude --safe-mode para una sesión sin mods instalados ni otras personalizaciones. Para apagarlos siempre, pon "disableAllHooks": true en ~/.claude/settings.json, sabiendo que también apaga tus hooks de settings y tu status line. Los mods integrados de Claude Code no se ven afectados por ninguna de las dos opciones.

Fuentes ¶

• Getting started with Claude Code mods — artículo de Anthropic que construye Token Weather y presenta Blast Radius y Replay Theater
• Mods overview — documentación oficial: qué puede hacer un mod, seguridad, dónde se ejecutan y mods integrados
• Mods de ejemplo en claude-code-playground — código de token-weather, blast-radius y replay-theater
• Mods integrados en el repositorio de Claude Code — diff, agents-md, sec-default y telemetry con sus tests

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter