Mods de Claude Code: qué son y el que incluimos en cada agente

El 1 de octubre de 2026, Claude Code 2.1.287 salió con una sola línea en el changelog: "Added Claude Mods". Cuatro días después, AgentsRoom empezó a cargar uno de los nuestros en los agentes Claude que ejecuta.

Este artículo explica qué es un mod, qué puede hacer que los puntos de extensión anteriores no podían, cómo escribir, cargar y probar uno, y qué aprendimos al incluir un mod en cada agente Claude que AgentsRoom inicia. Los datos sobre Claude Code vienen de su documentación y su changelog, consultados el 9 de noviembre de 2026, con Claude Code 2.1.318 instalado.

La respuesta corta. Un mod es un plugin de Claude Code con un hooks module: un archivo JavaScript o TypeScript cuyas funciones Claude Code llama desde su propio proceso cuando ocurre un evento. Una función puede dejar pasar el evento, modificarlo o responderlo en lugar de Claude Code. Así es como un mod dibuja un panel, añade un comando o detiene un comando shell antes de que se ejecute.

Qué es un mod

Claude Code ya tenía plugins: una carpeta con un manifiesto en .claude-plugin/plugin.json que agrupa skills, subagentes, hooks de settings y servidores MCP para que se instalen como una sola unidad. Un mod es una cosa más que un plugin puede contener. Cuando el hooks/hooks.json del plugin nombra un archivo de código bajo su clave modules, Claude Code carga ese archivo y llama a la función register que exporta. A partir de ahí, el plugin se llama mod.

Dentro de register, cada llamada a on(event, hook) asocia una función a un evento: tool.call antes de que se ejecute una herramienta, prompt.submit cuando envías un prompt, session.start, command.run para un comando slash, ui.render cuando Claude Code dibuja una parte de su pantalla, y otros. Cada hook recibe tres cosas:

• $, la API de los mods: todo lo que un mod puede hacer fuera de su propio código, como $.ui, $.command, $.fs, $.process o $.http.
• e, el evento, como datos simples: para una llamada a una herramienta, el nombre de la herramienta y sus argumentos.
• next, que pasa el evento a los demás mods y luego al comportamiento propio de Claude Code, y devuelve el resultado.

Lo que el hook hace con next decide lo que pasa. Devuelve next(e) y solo habrás observado. Llama a next con una copia modificada de e y habrás reescrito el evento. Devuelve tu propio resultado sin llamar a next y lo habrás respondido tú: la herramienta nunca se ejecuta, o Claude Code nunca dibuja lo suyo.

La documentación también llama hooks a estas funciones. No son los hooks que escribes en settings.json, a los que Claude Code ahora llama settings hooks.

Mod, hook de settings, skill o servidor MCP

Los cuatro se solapan, y el mod es el más pesado. Elige el más ligero que haga el trabajo.

Un plugin puede contener los cuatro, así que un mod puede distribuirse junto al skill y al servidor MCP con los que trabaja.

Los tres archivos de un mod

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json es el manifiesto habitual de un plugin: un nombre, una versión, una descripción. hooks.json apunta al código, { "modules": ["./register.ts"] }, una sola ruta relativa a ese archivo. register.ts es el hooks module. Claude Code carga .js y .ts directamente, sin bundler ni paso de build, y el único import sin ruta permitido es claude-code, para los tipos y algunas utilidades.

El mod que incluimos: ¿quién cambió este archivo?

AgentsRoom ejecuta varios agentes de código sobre el mismo repositorio y muestra, en su pestaña Cambios, qué agente cambió qué archivo, para que puedas revisar y hacer commit del trabajo de cada agente por separado. Los archivos escritos con las herramientas Edit y Write de Claude eran fáciles: Claude Code los informa mediante un hook de settings. Los escritos por un comando shell, no. Un sed -i, un heredoc, un codemod o un rm nunca pasan por una herramienta de archivos.

Antes de los mods, adivinábamos. AgentsRoom leía la transcripción de la sesión del agente para saber cuándo empezaba y terminaba cada comando Bash, y luego comparaba la fecha de modificación del archivo con esos intervalos. Funcionaba casi siempre y fallaba de tres maneras que sabíamos nombrar:

• un archivo borrado no tiene fecha de modificación, así que un borrado nunca se atribuía;
• un comando de solo lectura como grep abría un intervalo durante el cual el agente podría haber escrito cualquier cosa;
• dependía del formato de la transcripción, que Claude Code puede cambiar cuando quiera.

Un mod elimina la adivinanza. Nuestro mod agentsroom-changes engancha tool.call para las dos herramientas shell. Justo antes de que se ejecute el comando, toma una instantánea del repositorio (git status más el tamaño y la fecha de modificación de cada ruta modificada). Justo después, toma una segunda. Las rutas que difieren son lo que ese comando cambió, borrados incluidos, y el mod las envía a la app de escritorio AgentsRoom a través de un endpoint HTTP local. Una llamada que el propio Claude Code marca como de solo lectura no reclama nada.

Aquí está el hook, recortado. El archivo completo tiene 177 líneas, la mayoría para la instantánea y sus límites.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

La app de escritorio copia el mod en su propia carpeta e inicia cada agente Claude con claude --plugin-dir <that folder>, solo cuando el Claude Code instalado es la 2.1.287 o posterior. Lo publicamos en AgentsRoom 1.201.0 el 5 de octubre de 2026.

Lo que aprendimos al publicarlo

Un mod nunca debe costarle al usuario una llamada a una herramienta. Nuestro hook se coloca delante de cada comando shell que Claude ejecuta. Si lanza una excepción, o espera a la red, el trabajo de Claude se detiene. Cada paso está protegido, cada envío a la app de escritorio sale sin esperar respuesta, y la única espera que aceptamos son dos instantáneas git status, limitadas a 15 segundos cada una. Un envío perdido cuesta una atribución, nunca el comando.

No hagas nada cuando nadie te ha llamado. El mod lee una variable de entorno que AgentsRoom define para sus agentes. Si falta, por ejemplo porque alguien copió la carpeta en su propia configuración, cada hook pasa directamente a next(e).

Una carpeta cargada con --plugin-dir está vigilada. Claude Code recarga el mod cuando cambia un archivo de esa carpeta, y una recarga vuelve a ejecutar register. Eso decidió cómo lo instalamos: la app de escritorio solo escribe un archivo del mod cuando su contenido ha cambiado, porque reescribirlo a ciegas en cada arranque de agente recargaría el mod en todas las consolas de Claude ya abiertas.

Cuenta con que la API cambie. Los eventos y los métodos pueden cambiar de una versión a otra, y la propia documentación lo dice. Cuando un mod se carga desde --plugin-dir, Claude Code escribe las declaraciones de tipos de la versión en uso en .claude-plugin/types/; comprobamos los tipos contra esas, no contra una página web. Y si una versión deja de cargar nuestro mod, nada se rompe: el mod nunca se declara listo, y AgentsRoom vuelve al antiguo método de la transcripción.

Escribe el tuyo

Tienes dos caminos.

Pídeselo a Claude. En una sesión interactiva de Claude Code, describe el mod que quieres ("muestra la rama git actual encima del prompt"). Claude usa un skill integrado, plugin-authoring, escribe el mod en una carpeta para esa sesión, y Claude Code te pregunta una sola vez si quieres activar los mods que escribe Claude. Di que sí y el mod se carga cuando termina el turno, y luego se recarga después de cada turno que lo modifique.

Escribe tú mismo los tres archivos, y luego:

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate imprime una línea hooks: con los eventos que maneja tu módulo y una línea calls: con cada método de la API de los mods que llama. Si falta un evento que querías manejar, Claude Code tampoco llamará a ese hook. El análisis estático tiene sus reglas: escribe cada llamada completa ($.ui.toast(...), nunca const ui = $.ui), pasa los nombres de eventos como literales de cadena, e importa solo tus propios archivos por ruta relativa.

Para compartir un mod, trátalo como el plugin que es: envía la carpeta, o publícalo en un marketplace (un repositorio con un .claude-plugin/marketplace.json) para que la gente lo instale con /plugin install <name>@<marketplace>.

Mods que puedes leer hoy

• Integrados en Claude Code: /plugin, pestaña Installed, sección Built-in. Entre ellos, el panel /diff y el cargador que lee AGENTS.md como instrucciones del proyecto, cuyo código Anthropic publica en la carpeta mods del repositorio anthropics/claude-code, con sus tests. También integrado, y desactivado hasta que lo actives: You should know, un agente lateral que señala lo que podría habérsete pasado a ti o a Claude.
• Los ejemplos de Anthropic, en el repositorio claude-code-playground: una previsión de la ventana de contexto dibujada encima del prompt, una protección que retiene un comando shell arriesgado y muestra lo que cambiaría, y un comando /replay que recorre paso a paso las ediciones del último turno.
• El nuestro, descrito más arriba: un mod sin ninguna interfaz, con un único hook tool.call, una buena forma que copiar si lo que necesitas son datos y no un panel.

Antes de instalar el mod de otra persona

Un mod no está aislado en un sandbox. Se ejecuta con tus permisos: puede leer y escribir tus archivos, leer tus variables de entorno y tus ajustes (claves de API incluidas), lanzar programas, hacer peticiones de red, ver cada prompt y cada llamada a una herramienta, y aprobar una llamada a una herramienta antes de que te lo pregunten. Si activaste el sandbox de Claude Code, este cubre los comandos Bash que Claude ejecuta, no los procesos que lanza un mod.

Así que lee antes de instalar. Clona el mod y ejecuta claude plugin validate sobre la carpeta: las líneas hooks: y calls: te dicen qué escucha y a qué accede, sin ejecutar nada. Un mod que solo dibuja una franja encima del prompt no tiene ningún motivo para llamar a $.http o $.process. Para detener todos los mods que instalaste, arranca con --safe-mode durante una sesión, o pon "disableAllHooks": true en ~/.claude/settings.json.

Dónde funcionan los mods

Un mod que dibuja debería comprobar dónde se ejecuta y recurrir al texto donde no se dibuja nada.

En AgentsRoom

No instalas nada: desde Claude Code 2.1.287, cada agente Claude arranca con el mod, y la pestaña Cambios muestra los archivos que cada uno de sus comandos shell creó, modificó o borró, junto al agente que lo hizo. Con un Claude Code más antiguo, AgentsRoom sigue atribuyendo las escrituras shell a partir de la transcripción, como antes.

La misma idea funciona en otros CLI cuando es posible: oh-my-pi recibe una extensión con el mismo contrato, y los demás CLI siguen atribuyendo las escrituras shell como antes. Si quieres ir más allá con lo que Claude Code expone en cada paso, nuestra guía de hooks de Claude Code cubre los hooks de settings junto a los que se sitúa un mod.

Preguntas frecuentes

¿Qué es un mod en Claude Code?

Un mod es un plugin de Claude Code que contiene un hooks module: un archivo JavaScript o TypeScript cuyas funciones Claude Code llama desde su propio proceso cuando ocurre algo, como una llamada a una herramienta, un prompt enviado o una parte de la pantalla que hay que dibujar. Cada función puede dejar pasar el evento, modificarlo o responderlo ella misma. Eso es lo que permite a un mod dibujar un panel, añadir un comando o retener un comando shell arriesgado.

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

Claude Code 2.1.287 o posterior en el terminal, publicada el 1 de octubre de 2026, cuyo changelog dice "Added Claude Mods". La pestaña Code de la app Claude Desktop los admite desde la 2.1.286. En la extensión de VS Code los hooks se ejecutan, y lo que un mod dibuja necesita la extensión 2.1.299 o posterior. Ejecuta claude --version para comprobarlo.

¿Qué diferencia hay entre un mod y un hook de Claude Code?

Un hook en settings.json ejecuta un comando shell, una petición HTTP o un prompt cuando se dispara un evento, fuera de Claude Code. Los hooks de un mod son funciones que se ejecutan dentro de Claude Code. Pueden hacer lo que un hook de settings no puede: dibujar en la interfaz, añadir un comando slash que se ejecuta sin un turno de Claude, reescribir una llamada a una herramienta o responderla sin ejecutar la herramienta, y compartir estado entre hooks.

¿Es seguro instalar mods de Claude Code?

Un mod no está aislado en un sandbox. Se ejecuta con tus permisos, puede leer tus archivos y tus variables de entorno, lanzar programas, hacer peticiones de red y aprobar una llamada a una herramienta. Instala solo mods de autores en los que confíes, y ejecuta antes claude plugin validate sobre la carpeta: lista los eventos que el mod escucha y las llamadas que hace, sin ejecutarlo.

¿Dónde encuentro ejemplos de mods de Claude Code?

Anthropic publica el código de algunos mods integrados, como el panel /diff y el cargador de AGENTS.md, en la carpeta mods del repositorio anthropics/claude-code, y mods de ejemplo en el repositorio anthropics/claude-code-playground. El de AgentsRoom descrito en este artículo es un cuarto tipo de ejemplo: un mod sin interfaz, con un único hook tool.call.

¿Puedo desactivar los mods?

Sí. Desactiva un mod desde la pestaña Installed de /plugin, inicia una sola sesión con --safe-mode, o pon disableAllHooks a true en ~/.claude/settings.json para detener todos los mods que instalaste, junto con tus hooks de settings. --safe-mode y disableAllHooks dejan funcionando los mods integrados: esos se desactivan uno a uno en /plugin.