SpyBara
Go Premium

plugins/mods/overview.md 2026-09-30 23:00 UTC to 2026-10-01 21:59 UTC

This page contains 269 additions and 0 deletions.

2026
Thu 1 23:02

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

Puede comenzar con un mod de una de tres formas:

Instalar o actualizar un mod

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

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

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

Si instala o actualiza un mod desde su shell mientras una sesión está abierta, ejecute /reload-plugins en esa sesión para cargarlo. De lo contrario, se carga la próxima vez que inicie Claude Code.

Decidir si confiar en un mod

Un mod es código que se ejecuta con sus permisos, dentro de Claude Code. Instale mods solo de autores y mercados en los que confíe.

A qué puede acceder un mod

Un mod se ejecuta con sus permisos, por lo que antes de instalar uno, sepa a qué tiene acceso. Una vez que se carga, un mod puede:

  • Actuar en su máquina como usted: leer y escribir archivos en cualquier lugar donde su cuenta de usuario pueda, iniciar programas, y hacer solicitudes de red
  • Leer sus secretos: variables de entorno y archivos de configuración, incluida una clave API que mantenga en cualquiera de ellos
  • Ver su sesión: cada mensaje que envía y cada llamada de herramienta que Claude hace
  • Cambiar su sesión: reescribir un mensaje o una llamada de herramienta, enviar un mensaje como si lo hubiera escrito, o enviar un mensaje a otra de sus sesiones
  • Actuar sin pedirle: aprobar una llamada de herramienta antes de que se le pregunte
  • Gastar su uso: llamar a un modelo en su plan o clave API

Un mod que aprueba llamadas de herramientas puede aprobar una que una regla ask solicitaría, o que uno de sus 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 el mensaje de permiso. No puede cambiar lo que un mensaje le muestra.

Enumerar lo que hace un mod antes de instalarlo

Antes de instalar un mod, puede enumerar qué eventos engancha y qué le pide a Claude Code que haga, como leer un archivo o hacer una solicitud de red, sin ejecutarlo. Obtenga primero los archivos del plugin, por ejemplo clonando su repositorio. Luego, en su shell, ejecute 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 su shell, ejecute claude --version para verificar, y actualice Claude Code si el suyo es más antiguo.

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

  • Un mod: deshabilite o desinstale su plugin desde la pestaña Installed en /plugin
  • Cada mod instalado, para una sesión: inicie Claude Code con --safe-mode, que también deja fuera sus otras personalizaciones
  • Cada mod que instaló, en cada sesión: establezca "disableAllHooks": true en ~/.claude/settings.json. Sus settings hooks y línea de estado personalizada también se detienen. Lo que su organización administra sigue ejecutándose.

Si usa 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.

Para saber si los mods pueden cargarse para usted, vea Verificar si los mods pueden cargarse.

Ver qué mods cargó una sesión

Para ver qué mods cargó una sesión de terminal, ejecute /plugin en el mensaje 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 instaló no aparece allí, vea 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 de 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. Observe la línea del spinner encima del cuadro de mensaje: mientras Claude enumera un directorio y lee dos archivos, lee Thinking · tool calls: 1…, luego 2…, luego 3….