SpyBara
Go Premium

plugins/mods/overview.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 56 additions and 56 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Thu 8 22:58 Wed 14 22:58 Thu 15 23:58 Mon 19 23:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59

Descripción general de los mods

Agrega paneles, comandos y reglas para llamadas a herramientas a Claude Code con un mod. Descubre lo que puede hacer un mod, cómo crear o instalar uno y dónde se ejecutan los mods.

Un mod es un plugin que cambia la apariencia y el comportamiento de Claude Code. Está compuesto por controladores de eventos en JavaScript o TypeScript: Claude Code llama a uno cuando ocurre un evento, como una llamada a herramienta, un prompt enviado o una parte de la interfaz que se está dibujando, y el controlador puede observar el evento, modificarlo o tomar el control. Usa un mod para agregar una funcionalidad propia a Claude Code, como un panel que grafique qué tan lleno está tu contexto después de cada solicitud. Para conocer los archivos de un mod y ver un ejemplo completo, consulta Cómo funciona un mod.

[!NOTE]

Los hooks existentes de Claude Code también se ejecutan ante eventos, como un comando de shell, una solicitud HTTP o un prompt que configuras en un archivo de configuración. En cambio, los controladores de un mod son funciones que se ejecutan dentro de Claude Code. Claude Code llama hooks a ambos tipos: en estas páginas, "hook" se refiere al controlador de un mod, y el tipo definido en el archivo de configuración es un "hook de configuración".

Qué puede hacer un mod

Los hooks de configuración, los skills, las líneas de estado y los servidores MCP funcionan desde fuera de Claude Code: cada uno ejecuta un script o le da a Claude texto o herramientas. Un mod se ejecuta dentro de Claude Code, así que puede hacer cosas que ellos no pueden:

  • Dibujar una interfaz que puedes usar: un panel junto a la transcripción o una franja encima del prompt, con pestañas, botones y campos de texto. Consulta Dibujar en la interfaz.
  • Redibujar la propia interfaz de Claude Code: reemplazar o cambiar el estilo de partes que Claude Code dibuja por sí mismo, como la fila de una llamada a herramienta, el indicador de actividad o el diálogo en el que Claude hace preguntas. Consulta Cambiar lo que Claude Code ya dibuja.
  • Intervenir en una llamada a herramienta o en una solicitud: por ejemplo, retener una llamada a herramienta mientras le haces una pregunta al usuario, responderla sin ejecutar la herramienta o enviar una solicitud a un modelo diferente. Consulta Proteger o cambiar una llamada a herramienta y Seguir un turno.
  • Ejecutar tu propio código con un comando: un /command que ejecuta tu función de inmediato, sin un turno de Claude, incluso mientras Claude está trabajando. Consulta Agregar un comando o una herramienta.
  • Compartir datos entre hooks: los hooks de un mod comparten las variables de su archivo, así que lo que un hook registra, otro puede mostrarlo. Por ejemplo, un hook puede contar las llamadas a herramientas mientras otro muestra el recuento junto al indicador de actividad, o uno puede leer el uso de tokens de cada solicitud mientras otro lo grafica en un panel. Consulta Reaccionar a eventos.

Los mods funcionan en la CLI de Claude Code, en la pestaña Code de la aplicación Claude Desktop y en la extensión de VS Code. Consulta Dónde se ejecutan los mods para entender cómo se comportan en otros lugares, como en claude -p y las sesiones en la nube. Si un hook de configuración, un skill o un servidor MCP ya hace lo que necesitas, compáralos antes de escribir un mod. Para administrar mods para una organización, consulta Administrar mods para tu organización.

Obtén un mod

Para empezar con un mod:

Instalar o actualizar un mod

[!WARNING]

Un mod es código que se ejecuta con tus permisos. Puede leer y escribir tus archivos, iniciar procesos y hacer solicitudes de red. Instala mods solo de autores y marketplaces en los que confíes. Consulta Decide si confiar en un mod.

Un mod se instala como un plugin, desde un marketplace. Indica el nombre del plugin, una @ y el nombre del marketplace. Estos ejemplos instalan un plugin llamado token-chart desde un marketplace llamado your-org:

  • En una sesión de Claude Code, ejecuta /plugin install token-chart@your-org.
  • En tu shell, ejecuta claude plugin install token-chart@your-org.

Instalar plugins cubre los marketplaces, los alcances, la extensión de VS Code y la aplicación de escritorio, y mantener los plugins actualizados, todo lo cual se aplica sin cambios a un plugin que contiene un mod.

Si instalas o actualizas un mod desde tu shell mientras hay una sesión abierta, ejecuta /reload-plugins en esa sesión para cargarlo. De lo contrario, se carga la próxima vez que inicies Claude Code.

Prueba un mod de ejemplo

Anthropic comparte mods de ejemplo en el directorio claude-code/mods del repositorio claude-code-playground. Cada uno es un plugin completo, y su README explica cómo se creó. El repositorio los comparte tal como están, sin soporte.

  • token-weather: dibuja un pronóstico de tu ventana de contexto encima del prompt
  • blast-radius: retiene un comando de shell arriesgado, como rm -rf o un push forzado, y muestra lo que cambiaría, con botones para continuar o cancelar
  • replay-theater: agrega un comando /replay que recorre paso a paso las ediciones de archivos que Claude hizo en el último turno

Un mod de ejemplo se ejecuta con tus permisos. Para ver qué hace uno antes de cargarlo, enumera sus hooks y llamadas.

Para probar uno, clona el repositorio y carga el directorio del mod para una sesión con --plugin-dir. Para confirmar que el mod se cargó, comprueba qué mods cargó la sesión.

Para conservar uno, agrega el directorio claude-code/mods del clon como marketplace y luego instala el mod desde claude-code-playground-mods. El marketplace apunta a tu clon, por lo que el mod deja de cargarse si lo mueves o lo eliminas.

Decide si confiar en un mod

Un mod es código que se ejecuta con tus permisos, dentro de Claude Code. Instala mods solo de autores y marketplaces en los que confíes.

A qué puede acceder un mod

Un mod se ejecuta con tus permisos, así que antes de instalar uno, debes saber a qué tiene acceso. Una vez que se carga, un mod puede:

  • Actuar en tu máquina como tú: leer y escribir archivos en cualquier lugar donde pueda hacerlo tu cuenta de usuario, iniciar programas y realizar solicitudes de red
  • Leer tus secretos: variables de entorno y archivos de configuración, incluida una clave de API que guardes en cualquiera de ellos
  • Ver tu sesión: cada prompt que envías y cada llamada a herramienta que hace Claude
  • Cambiar tu sesión: reescribir un prompt o una llamada a herramienta, enviar un prompt como si lo hubieras escrito tú o enviar un mensaje a otra de tus sesiones
  • Actuar sin preguntarte: aprobar una llamada a herramienta antes de que se te pregunte
  • Gastar tu uso: llamar a un modelo con tu plan o tu clave de API

Los mods no se ejecutan en un sandbox. Si activas el sandboxing, el sandbox aísla los comandos de Bash que ejecuta Claude, y un proceso que inicia un mod se ejecuta fuera de él.

Con configuración administrada o con un /login de Team o Enterprise como credencial de la sesión, de forma predeterminada la aprobación de un mod no permite que una llamada eluda tus reglas ask ni tus hooks PreToolUse. Sin ninguno de los dos, un mod puede aprobar una llamada para la que una regla ask te pediría confirmación, o que tu hook PreToolUse bloqueó. Para comprobar cuándo un mod también puede aprobar una llamada que una regla deny rechaza, consulta Extender permisos con hooks.

Un mod puede cambiar el estilo de gran parte de la interfaz de Claude Code, pero no de la solicitud de permiso. No puede cambiar lo que te muestra una solicitud.

Enumera lo que hace un mod antes de instalarlo

Antes de instalar un mod, puedes enumerar qué eventos maneja y qué le pide hacer a Claude Code, como leer un archivo o realizar una solicitud de red, sin ejecutarlo. Primero obtén los archivos del plugin, por ejemplo, clonando su repositorio. Luego, en tu shell, ejecuta claude plugin validate en el directorio del plugin:

claude plugin validate ./some-mod

Las líneas hooks: y calls: de la salida enumeran los eventos que maneja el mod y lo que le pide hacer a Claude Code. Revisa lo que puede hacer un mod muestra la salida y qué llamadas debes buscar.

Activar o desactivar los mods

Los mods están activados de forma predeterminada. En la terminal, usa Claude Code v2.1.287 o posterior. La app de escritorio incluye su propia copia de Claude Code, y los mods funcionan ahí a partir de v2.1.286. Comprueba la versión en el lugar donde usas los mods:

  • Terminal: en tu shell, ejecuta claude --version. Si tu versión es anterior, actualiza Claude Code.
  • App de escritorio: en una sesión local en la pestaña Code, escribe /status y lee la fila Claude Code, que muestra una versión como 2.1.286. Si tu versión es anterior, actualiza la app de escritorio.

Para desactivar los mods, elige cuántos detener y durante cuánto tiempo. Para volver a activarlos, deshaz el mismo cambio:

  • Un mod: deshabilita o desinstala su plugin desde la pestaña Installed en /plugin
  • Todos los mods instalados, durante una sesión: inicia Claude Code con --safe-mode, que también deshabilita tus otras personalizaciones
  • Todos los mods que instalaste, en todas las sesiones: establece "disableAllHooks": true en ~/.claude/settings.json. Tus hooks de configuración y tu línea de estado personalizada también se detienen. Lo que administra tu organización sigue ejecutándose.

Si usas Claude Code a través de una organización, un administrador también puede limitar qué mods se cargan. Los administradores pueden empezar en Impedir que se carguen los mods instalados por usuarios.

disableAllHooks y el ajuste allowManagedModsOnly de tu organización detienen un mod y dejan el resto de su plugin en su lugar: el plugin sigue instalado, y sus skills, comandos, agentes y servidores MCP se cargan. Otros ajustes y flags tienen un alcance mayor. disableAllHooks y Qué se ejecuta con allowManagedHooksOnly indican qué hace cada uno a un plugin y a sus hooks de configuración.

Para saber si los mods pueden cargarse en tu caso, consulta Comprobar si los mods pueden cargarse.

[!NOTE]

Si estableciste CLAUDE_CODE_ENABLE_FUNCTION_HOOKS durante el acceso anticipado, elimínalo. Claude Code v2.1.287 y posteriores lo ignoran, por lo que establecerlo en 0 no mantiene los mods desactivados.

Ver qué mods cargó una sesión

Para ver qué mods cargó una sesión de la terminal, ejecuta /plugin en el prompt de Claude Code. Una línea atenuada debajo de las pestañas muestra la cantidad y los nombres, como 1 mod active · first-mod. Si un mod que instalaste no aparece ahí, consulta Averiguar por qué un mod no hace nada.

Cómo funciona un mod

Un mod es un plugin cuyo código registra controladores de eventos, llamados hooks. Claude Code ejecuta un hook cuando ocurre su evento, por ejemplo cuando Claude llama a una herramienta o cuando se dibuja el spinner. Un mod pequeño tiene tres archivos:

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

Este es un register.js completo. Cuenta las llamadas a herramientas que hace Claude y muestra el conteo junto al spinner mientras Claude trabaja, como en Thinking · tool calls: 3….

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

El archivo registra dos hooks, y ambos usan la variable calls de la parte superior:

  • El hook tool.call se ejecuta cada vez que Claude está a punto de usar una herramienta. Suma uno a calls, le pide a Claude Code que vuelva a dibujar la interfaz y deja que la herramienta se ejecute como de costumbre.
  • El hook ui.render se ejecuta cada vez que Claude Code dibuja el spinner. Conserva el propio spinner de Claude Code y agrega el conteo después de la palabra.

Esta grabación muestra el mod en acción. Observa la línea del spinner encima del cuadro del prompt: mientras Claude lista un directorio y lee dos archivos, muestra Thinking · tool calls: 1…, luego 2… y luego 3….