SpyBara
Go Premium

plugins/mods/overview.md 2026-10-01 23:59 UTC to 2026-10-02 16:57 UTC

This page contains 84 additions and 64 deletions.

2026
Thu 1 23:59 Fri 2 18:59

Descripción general de mods

Agregue paneles, comandos y reglas de llamadas de herramientas a Claude Code con un mod. Vea qué puede hacer un mod, cómo crear o instalar uno, y dónde se ejecutan los mods.

Un mod es un plugin que cambia cómo se ve y se comporta Claude Code. Está hecho de controladores de eventos JavaScript o TypeScript: Claude Code llama a uno cuando ocurre un evento, como una llamada de herramienta, un mensaje enviado, o una parte de la interfaz siendo dibujada, y el controlador puede observar el evento, cambiarlo, o hacerse cargo de él. Use un mod para agregar una característica propia a Claude Code, como un panel que muestre qué tan lleno está su contexto después de cada solicitud. Para los archivos en un mod y un ejemplo completo, vea Cómo funciona un mod.

Qué puede hacer un mod

Los settings hooks, skills, líneas de estado, y 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, por lo que puede hacer cosas que ellos no pueden:

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

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

Obtener un mod

Para comenzar con un mod:

Instalar o actualizar un mod

Un mod se instala como un plugin, desde un marketplace. Proporciona 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 marketplaces, alcances, la extensión de VS Code y la aplicación Desktop, y mantener 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 una sesión está abierta, ejecuta /reload-plugins en esa sesión para cargarlo. De lo contrario, se carga la próxima vez que inicies Claude Code.

Probar 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 construyó. 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 riesgoso, como rm -rf o un force push, 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 lo que hace uno antes de cargarlo, lista 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.

Decidir 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, por lo 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 tu cuenta de usuario pueda, iniciar programas y hacer 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, 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 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.

Un mod que aprueba llamadas a herramientas puede aprobar una que una regla ask solicitaría, o que uno de tus propios hooks PreToolUse bloqueó. Extender permisos con hooks enumera lo que tal mod puede aprobar, incluido cuándo puede aprobar una llamada que una regla deny rechaza.

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

Enumerar lo que hace un mod antes de instalarlo

Antes de instalar un mod, puedes enumerar qué eventos maneja y qué le pide a Claude Code que haga, como leer un archivo o hacer una solicitud de red, sin ejecutarlo. Obtén primero 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: en la salida enumeran los eventos que el mod maneja y qué le pide a Claude Code que haga. Revisar qué puede hacer un mod muestra la salida y qué llamadas buscar.

Activar o desactivar mods

Los mods requieren Claude Code v2.1.287 o posterior, y están activados de forma predeterminada. En tu shell, ejecuta claude --version para verificar, y actualiza Claude Code si el tuyo es más antiguo.

Para desactivar los mods, elige cuántos detener y por cuánto tiempo. Para activarlos de nuevo, deshaz el mismo cambio:

  • Un mod: deshabilita o desinstala su plugin desde la pestaña Installed en /plugin
  • Cada mod instalado, para una sesión: inicia Claude Code con --safe-mode, que también deshabilita tus otras personalizaciones
  • Cada mod que instalaste, en cada sesión: 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 tu organización administra 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 comienzan en Evitar que los mods instalados por el usuario se carguen.

disableAllHooks y el 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 llegan más lejos. disableAllHooks y Qué se ejecuta con allowManagedHooksOnly enumeran lo que cada uno le hace a un plugin y a sus hooks de configuración.

Para saber si los mods pueden cargarse para ti, consulta Verificar si los mods pueden cargarse.

Ver qué mods cargó una sesión

Para ver qué mods cargó una sesión de terminal, ejecuta /plugin en el prompt de Claude Code. Una línea atenuada bajo las pestañas da el conteo y los nombres, como 1 mod active · first-mod. Si un mod que instalaste no aparece allí, 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, como 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 Claude hace 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 en 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 dibuje la interfaz de nuevo, y deja que la herramienta se ejecute como de costumbre.
  • El hook ui.render se ejecuta cada vez que Claude Code dibuja el spinner. Mantiene 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 enumera un directorio y lee dos archivos, muestra Thinking · tool calls: 1…, luego 2…, luego 3….