Mods de Claude Code: veredicto con fuentes, mediciones y checklist del lunes

Resumen

• Quédate con tres de los diez mods: collision-guard, model-router y auto-handoff. Cada uno mostró un sobrecoste medido cercano a cero en una tarea de lectura headless, y cada uno resuelve un problema que sabes nombrar.
• Elimina next-steps. Bifurca la sesión tras cada respuesta que cumple la condición y costó +250 tokens de salida y +2850 ms por turno en nuestra prueba, incluso en superficies que nunca dibujan sus sugerencias.
• Elimina cache-keeper (+1589 ms, pings de pago al modelo), recording-mode (oculta lo que se muestra, no el historial guardado) y session-bookmarks (un marcador que puede llamar al modelo, lanzar procesos y escribir archivos).
• Elimina goal-meter, repo-heatmap y flight-recorder salvo que quieras lo visual. Cuestan casi nada y no mostraron beneficio medido.
• Cualquier mod de guarda falla en abierto por defecto. Sin un manejador .catch, una guarda que lanza un error se omite y el comando se ejecuta.
• Los mods no están en un sandbox. Lee la salida de claude plugin validate antes de instalar uno.

Qué dicen las mediciones

Revuelo y escala. El tuit de lanzamiento tenía 4,138,918 vistas, 20,021 likes y 13,440 marcadores cuando lo capturamos el 2026-10-03 s11. El catálogo de la comunidad lista 1018 mods en 873 repos candidatos, escaneados el 2026-10-03 con Claude Code 2.1.288 s9.

Un mod es una función que se engancha a un evento. Puede ejecutarse antes, después, en lugar del evento, o envolverlo s1. Los mods requieren Claude Code v2.1.287 o posterior y vienen activados por defecto s2.

Primero la seguridad. Palabras de Anthropic: "Mods run with the same access to your machine as Claude Code itself. They aren't sandboxed" s1. Un proceso que lanza un mod se ejecuta fuera del sandbox aunque lo actives s2. Con Read(.env) denegado, un mod aún puede leer ese archivo con $.fs.read o lanzar un programa que lo haga s6. En el escaneo del catálogo, 409 mods ejecutan procesos del host, 167 escriben archivos, 150 acceden a la red y 28 no validan en esta versión s9.

Alcance frente a promesa. En nuestra auditoría estática, session-bookmarks llama a $.model.complete, $.process.run y $.fs.write, el mayor alcance del conjunto para una función de marcadores. next-steps tenía la menor huella: sin fs, sin process, sin env. claude plugin validate imprime las líneas calls: y env reads: usadas para esta auditoría s6.

El mod estrella tiene un coste por turno. next-steps bifurca la sesión con $.model.fork en turn.complete, y el README dice que el fork "costs about one short reply" s10. Las sugerencias solo se dibujan en el terminal; las demás superficies no muestran nada s10. El fork no tiene opción para desactivarlo. En nuestra prueba headless añadió +250 tokens de salida y +2850 ms, y el fork acabó en el uso de la sesión sin que se mostrara nada s10.

Límites documentados. El tiempo de ejecución de un hook está limitado a 10 segundos por evento, las lecturas y escrituras de $.fs a 4 MiB por archivo y $.store a 4 MiB de JSON en total s3.

Las guardas fallan en abierto. La doc dice que un hook sin manejador .catch que lanza un error, agota el tiempo o devuelve un formato incorrecto se omite, y se ejecuta el siguiente manejador en su lugar s7. Lo reprodujimos: una guarda de Bash que lanza un error, sin .catch, dejó que touch ./marker-failopen.txt creara el archivo. La misma guarda con un .catch que devuelve {deny} no creó ningún archivo. Un informe de campo encontró una guarda activada y en marcha que no hacía nada, mientras plugin list seguía mostrando "enabled" s8.

Un bug abierto en 2.1.288: un deny devuelto tras await next(e) no detiene la herramienta, y el archivo se escribió 3 de 3 veces mientras al modelo se le decía que la escritura había fallado s5.

Mods frente a hooks de settings. Un hook de settings lanza un proceso por llamada. Medimos el arranque en 2.2 ms para un binario true, 8.3 ms para bash -c 'exit 0', 26.1 ms para python3 -c 'pass' y 43.1 ms para node -e ''. Con 5,993 llamadas a herramientas por semana, el hook de node cuesta 258 s. Un mod en proceso no paga nada de esto. La doc recomienda un hook de settings cuando ya tienes un script que bloquea, permite o registra un evento s2. Un informe de migración pasó de 27 hooks de shell a 5 mods s8.

El enmascarado es solo visual. recording-mode reescribe lo que dibuja ui.render. ~/.claude/history.jsonl conserva el prompt tal como se escribió, y un tester encontró su cadena canario 7 veces en entradas queue-operation del transcript s5.

Dónde no se ejecutan los mods. El modo headless claude -p y el Agent SDK ejecutan hooks pero no dibujan nada; una sesión de Desktop en WSL no ejecuta ninguno de los dos s2.

Confianza en el catálogo. Un tester publicó un mod cuyo botón lanzaba un programa con $.process.run y escribía un archivo en su carpeta personal. Se instaló como cualquier otro mod, sin ningún aviso s5. Fue una prueba de concepto autopublicada, no un ataque visto en la práctica.

Mediciones

Corpus: los últimos 7 días de una configuración real, 85 sesiones, 4 proyectos, 882 prompts de usuario, 11,010 turnos del asistente, 5,993 llamadas a herramientas. Benchmark ejecutado en Claude Code 2.1.288 (macOS).

Protocolo para repetirlo:

1. Instala un mod a la vez y confirma que pasa claude plugin validate.
2. Ejecuta la misma tarea de solo lectura en headless con claude -p sobre haiku, 3 repeticiones por configuración, y toma la mediana de la duración y de los tokens de salida.
3. Cita solo las diferencias de duración y de tokens de salida. El coste en USD varía con el orden de la caché entre configuraciones, ignóralo.
4. Para el coste de arranque, cronometra 30 arranques del cuerpo de cada hook, toma la mediana y multiplica por tus llamadas semanales a herramientas.

Haz esto el lunes

• Ejecuta claude plugin validate en cada mod instalado y lee las líneas calls: y env reads:.
• Desactiva cualquier mod cuyo alcance (process, escritura fs, llamada al modelo) sea mayor que su función.
• Desactiva next-steps si trabajas sobre todo en headless, en el panel de VS Code o con el SDK, donde sus sugerencias nunca se dibujan.
• Añade un manejador .catch que devuelva { deny: ... } a cada mod de guarda del que dependas.
• Demuestra que cada guarda falla en cerrado: haz que lance un error, ejecuta un comando que cree un archivo testigo y comprueba que el archivo no aparece.
• No confíes en un mod de enmascarado para mantener secretos fuera de ~/.claude/history.jsonl o del transcript. Revisa ambos en disco.
• Sustituye los hooks de shell por llamada que lanzan node o python por un mod en proceso, o por un binario compilado, si el coste de arranque se acumula en tus llamadas semanales a herramientas.
• Aprende los interruptores: desactivar un mod en /plugin, --safe-mode para una sesión, "disableAllHooks": true en ~/.claude/settings.json para todo.

Para ir más lejos

• Construye el tuyo: un tutorial práctico de un mod de unas 80 líneas, con las trampas que importan (el estado a nivel de módulo se reinicia con la recarga en caliente, así que guarda los datos en $.state) s4.
• Decide entre mod, hook, skill o settings a partir de tu propio historial: un profesional sugiere revisar primero tus logs de sesión para encontrar problemas recurrentes s12.
• Lee la lista completa de eventos y límites antes de escribir una guarda s3.
• La gestión a nivel de organización queda fuera de aquí. El único punto para un desarrollador en solitario: sec-default se carga cuando la máquina tiene settings gestionados o has iniciado sesión con un plan Team o Enterprise, y no añade otras restricciones s6.
• El origen del diseño, incluido un bug de aislamiento de worktree corregido en 2.1.288 y el funcionamiento interno del runtime, está en el hilo abierto s5.
• Los mods de ejemplo de Anthropic (token-weather, blast-radius, replay-theater) figuran como compartidos sin soporte s2.

Fuentes

• Customize Claude Code with mods, Anthropic blog. Por qué leerlo: la definición oficial y la advertencia de que no hay sandbox, con las palabras de Anthropic.
• Mods overview, docs. Por qué leerlo: la comparación entre mods y hooks, la matriz de superficies y los interruptores.
• Mods reference, docs. Por qué leerlo: la lista completa de eventos y los límites documentados.
• Getting started with Claude Code mods, claude.dev (Addy Osmani). Por qué leerlo: el mejor tutorial práctico, con trampas que ninguna otra fuente cubre.
• Mods issue #91870, GitHub. Por qué leerlo: informes de campo sobre aislamiento, fallo en cerrado y fugas de historial.
• Manage mods for your organization, docs. Por qué leerlo: la auditoría validate y los límites de cada control de seguridad.
• React to events with a mod, docs. Por qué leerlo: el orden de la cadena de middleware y el fallo en abierto por defecto.
• The Guard I Installed Was Enabled, Running, and Doing Nothing, blog. Por qué leerlo: el único informe de migración, de 27 hooks de shell a 5 mods.
• awesome-claude-code-mods, GitHub. Por qué leerlo: el tamaño del ecosistema y un método de auditoría listo para usar.
• next-steps plugin source, GitHub. Por qué leerlo: la mecánica real del mod estrella, incluido el fork en cada turno.
• ClaudeDevs release tweet, X. Por qué leerlo: el anuncio de lanzamiento y su alcance.
• Avid's session-log mining workflow, X. Por qué leerlo: un método para decidir qué construir o instalar antes de instalar nada.

FAQ

¿Están los mods en un sandbox?

No. Anthropic dice que los mods se ejecutan con el mismo acceso a tu máquina que Claude Code s1. Los programas que lanza un mod también se ejecutan fuera del sandbox s2.

¿Qué pasa si mi mod de guarda falla?

Sin manejador .catch, se omite y el comando se ejecuta s7. Añade un .catch que devuelva { deny: ... } para que falle en cerrado.

¿Un mod cuesta tokens?

Solo si llama al modelo. De los diez que ejecutamos, next-steps y cache-keeper mostraron un coste medible; los demás no mostraron un sobrecoste sólido en nuestra prueba.

¿Cómo desactivo los mods rápidamente?

Desactiva uno en /plugin, inicia una sesión con --safe-mode, o pon "disableAllHooks": true en ~/.claude/settings.json s2. Ninguna de estas opciones detiene los mods integrados.

¿Puedo comprobar qué hace un mod antes de instalarlo?

Sí. claude plugin validate lista los hooks, las llamadas a la API y las variables de entorno que lee s6.