Noticias
8 min

Guía para principiantes de los hooks de Claude

Los hooks de Claude Code son scripts que se ejecutan automáticamente en momentos clave de la sesión: formateo, bloqueo de comandos peligrosos y notificaciones. Esta guía explica cómo instalarlos.

En el artículo de hoy vamos a aprender qué son los hooks de Claude Code, qué hacen, cómo instalarlos y por qué (y cuándo) pueden ser útiles. ¡Vamos al lío!

Un hook de Claude Code es un pequeño script (o un endpoint HTTP, o un prompt para un LLM) que se dispara automáticamente en momentos concretos de una sesión de Claude Code. El modelo decide qué hacer a continuación, ejecuta la acción, observa el resultado, decide de nuevo: un bucle agéntico. Los hooks se insertan en puntos con nombre de ese bucle y te permiten intervenir sin estar presente.

La razón por la que los hooks importan es la diferencia entre las reglas que le pides a Claude que siga y las reglas que siempre se ejecutan. Puedes decirle a Claude en tu CLAUDE.md que ejecute Prettier después de cada edición de un archivo, y la mayoría de las veces lo hará. Pero "la mayoría de las veces" no es siempre. Un hook hace que ocurra cada vez, sin excepción. El enfoque del propio Anthropic en su presentación de tres minutos es el que hay que interiorizar: "Si algo tiene que ocurrir siempre sin fallo, no lo pongas en un prompt. Ponlo en un hook."

Qué ocurre cuando se dispara un hook

El modelo mental es bastante sencillo. Claude Code emite un evento ("Voy a ejecutar un comando bash", "Acabo de editar un archivo", "He terminado de responderte", etc.). Tu hook es un script que escucha uno de esos eventos y ejecuta el comando de shell, el endpoint HTTP o el pequeño prompt de IA que hayas configurado. El script recibe los detalles del evento como JSON por la entrada estándar. Puede hacer lo que quiera con esa información: registrarla, transformarla, bloquear la acción o lanzar una notificación; y luego señalar a Claude mediante un código de salida.

Esa es toda la característica. Todo lo demás es en qué evento te enganchas, qué hace tu script y cómo se comunica de vuelta con Claude. En pocas palabras: haz una cosa cuando esta cosa termina.

Hay aproximadamente veintisiete eventos disponibles en la referencia de Anthropic, hasta ahora. Aquí están los 5 mejores:

Los cinco eventos que merece la pena conocer

  • UserPromptSubmit se dispara en el momento en que pulsas Enter (y probablemente nunca lo supiste), antes de que Claude lea tu mensaje. Útil para añadir silenciosamente el estado actual de tu repo (rama de git, últimos commits) de modo que cada turno empiece con el contexto correcto.
  • PreToolUse se dispara después de que Claude haya decidido usar una herramienta pero antes de que la herramienta se ejecute. Esta es la capa de seguridad: bloquea la acción, reescribe sus argumentos o introduce una advertencia en el contexto de Claude.
  • PostToolUse se dispara después de que la herramienta termina. El lugar habitual para formateadores, linters y ejecutores de tests: cualquier cosa que reaccione a lo que Claude acaba de hacer y necesite seguir un curso de acción posterior (como eval, QA).
  • Notification se dispara cuando Claude quiere tu intervención (un permiso que aprobar, una pregunta que responder). Útil para captar los momentos en que te has ausentado, aunque tengo la costumbre de olvidar que me he ausentado y dos horas más tarde no hemos avanzado.
  • Stop se dispara cuando Claude termina su turno. El lugar adecuado para notificaciones de finalización, registros de coste o cualquier cosa que quieras al final.

Los otros veintidós cubren necesidades muy específicas: truncamiento de contexto, ciclo de vida de subagentes, vigilancia de archivos, arranque de sesión. Acude a ellos, como usuario de nivel intermedio a avanzado, cuando te topes con un problema que resuelven. Durante las primeras semanas usando hooks, los cinco de arriba son más que suficientes.

Un settings.json, tres niveles de anidamiento

Los hooks viven en tu archivo settings.json. La forma de la configuración es evento > matcher (en qué filtrar) > handler (qué ejecutar). Aquí está el ejemplo canónico de Anthropic, un hook PreToolUse que bloquea los comandos rm:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

settings.json vive en tres ámbitos. ~/.claude/settings.json es tu configuración global personal. .claude/settings.json dentro de un repo es la configuración del equipo, commiteada en git para que todo el que trabaje en el proyecto tenga los mismos hooks. .claude/settings.local.json es la anulación personal gitignored para un proyecto. Usa $CLAUDE_PROJECT_DIR (una variable de entorno que Claude Code expone) al referenciar scripts guardados en tu repo: funciona independientemente del directorio de trabajo en el que se encuentre Claude. La guía de configuración de proyecto de Claude Code cubre toda la estructura de la carpeta .claude/ por si no has configurado un repo así antes.

Lo que puede hacerte tropezar

Un hook de comando de shell se comunica de vuelta con Claude mediante su estado de salida. Exit 0 significa éxito. Exit 2 significa un error bloqueante: Claude se detiene y tu texto de stderr se devuelve como mensaje de sistema para que el modelo sepa por qué. Cualquier otra salida distinta de cero (el exit 1 estándar, un grep fallido, un error de parseo) se trata como un error no bloqueante. La acción continúa de todos modos y Claude no ve tu mensaje.

La trampa: exit 1 no bloquea. Solo exit 2 bloquea. La mayoría de desarrolladores recurre a exit 1 porque es lo que se siente natural en Unix. Si tu guarda de rm -rf sale con 1, la guarda no funciona. Prueba cada hook bloqueante.

La alternativa estructurada, para hooks que necesitan un control más fino, es la salida en JSON. Sal con 0, imprime un objeto JSON a stdout y puedes devolver cosas que los códigos de salida no pueden: reescribir los argumentos de la herramienta antes de que se ejecute, devolver un permissionDecision de allow / deny / ask, o inyectar contexto adicional que Claude verá en la próxima petición. Merece la pena conocerlo, pero el camino básico de códigos de salida cubre la mayoría de casos de inicio.

¿Cómo encaja un servidor MCP en todo esto? ¿Encaja?

Claude Code tiene varias capas de personalización. Es fácil confundirlas, así que vale la pena ser explícito:

  • CLAUDE.md alberga tus guías de estilo y convenciones de proyecto. El modelo normalmente las sigue. Normalmente.
  • Los servidores MCP dan a Claude capacidades que de otro modo no tendría: consultar Jira, leer Figma, llamar a tus APIs internas. Añaden nuevas herramientas a la caja.
  • Los comandos slash son flujos de trabajo que activas explícitamente tecleando /test o /deploy. Macros iniciadas por el usuario.
  • Los hooks son automáticos, determinísticos y orientados a eventos. Se disparan tanto si el usuario o el modelo los piden como si no. Ese es el punto.

La frase de la comunidad: usas MCP para darle a Claude un martillo; usas hooks para impedir físicamente que Claude se golpee su propio pulgar con él. La respuesta corta es no: herramientas distintas para tipos de trabajo distintos.

Los hooks que los usuarios instalan primero

Puedes escribir hooks desde cero en cualquier lenguaje que se ejecute en tu máquina. Probablemente no deberías empezar por ahí a menos que seas desarrollador. La comunidad ya ha construido y compartido gran parte de este trabajo; esto es lo primero a lo que recurrir.

Auto-formateador en PostToolUse(Edit|Write)

El primer hook universal. El propio vídeo de Anthropic lo llama "el hook más común"; todas las guías de la comunidad coinciden. Conecta el formateador de tu proyecto (Prettier, Black, Ruff, gofmt, rustfmt) para que se dispare siempre que Claude toque un archivo. Unas diez líneas de configuración en settings.json. El beneficio llega en el momento en que Claude hace su primera edición: no más discusiones de revisión por la indentación, sintaxis rara, no más quejas del hook de pre-commit y quizá incluso una compilación correcta a la primera.

El bloqueador de bash peligroso

En octubre de 2025 un desarrollador vio cómo Claude Code ejecutaba rm -rf en su directorio home (issue de GitHub #10077, referenciado después por la mitad de los artículos de la comunidad). Un handler PreToolUse que haga pattern matching del comando bash, salga con 2 en cualquier cosa de tu lista de "absolutamente no" y explique por qué en stderr lo habría detenido. Patrones base a considerar: rm -rf en directorios que te importan, git push --force a main, ediciones de cualquier cosa bajo .secrets/ o .env*, y curl | sh.

Dippy, de Lily Dayton, es la implementación más cuidada de este patrón en la comunidad: parseo basado en AST para aprobar automáticamente comandos bash seguros mientras te pregunta por los destructivos. Resuelve la fatiga de permisos sin desactivar la seguridad por completo. Si te encuentras queriendo saltarte los permisos porque los avisos son constantes, instala Dippy en su lugar.

Como apunte, nunca he tenido nada parecido a este tipo de problema: trabajo en un repo local y Claude necesita permiso para acceder a archivos externos de cualquier tipo; para mí estas son historias de terror en las que el usuario ha decidido que el modelo está listo para hacer todo su trabajo por él.

Notificador de finalización en Stop

Útil para ejecuciones agénticas largas en las que prefieres ausentarte a vigilar la terminal. CC Notify es la implementación pulida de la comunidad: notificaciones de escritorio, saltos con un clic de vuelta a VS Code, seguimiento de la duración de las tareas. O construye la tuya propia con tres líneas de configuración más notify-send (Linux), osascript (macOS) o un webhook de Slack (multiplataforma).

Claudio va en la otra dirección: sonidos nativos del sistema vía hooks. Greg Baugues en haihai.ai/hooks hace lo mismo con una ambientación sonora del puente de Star Trek más teatral: pitidos para las llamadas a herramientas, un actor de voz británico diciendo "creating pull request", el maullido triste de un gato en Stop. La frase inicial de Greg es la introducción de una sola frase más útil sobre hooks que nadie haya escrito: "Voy a usar esto para hacer que Claude maúlle. Siempre he querido un gato, pero soy alérgico."

Ejecuta su configuración durante una semana y tu terminal se convierte en el puente de la USS Enterprise. El punto no son los sonidos: es que escuchar el flujo de eventos te enseña más rápido que cualquier página de referencia. Aprendes con qué frecuencia se dispara PreToolUse para comandos bash (mucho), qué eventos son raros y cuándo Claude está trabajando frente a cuándo te está esperando. Tras esa semana, la intuición de dónde poner un hook de productividad real la tienes integrada.

Si tu suite de tests tiene un modo "relacionado con este archivo" (vitest related, jest --findRelatedTests, pytest --picked), conéctalo. Claude hace un cambio, el test falla, Claude se da cuenta y lo reintenta en el mismo turno mientras tú todavía estás leyendo la explicación. La advertencia honesta: esto solo funciona si tu suite de tests es rápida y está bien aislada. Un hook de treinta segundos en cada edición de archivo arrastra la sesión a un ritmo penoso; por ello, fíltralo por ruta de archivo y sal pronto si el conjunto de tests relacionados está vacío.

TDD Guard, de Nizar Selander, va un paso más allá: monitoriza las operaciones de archivo en tiempo real y bloquea los cambios que violan los principios de TDD. Merece una mirada si tu equipo se toma en serio el test-first.

Aplicación de estilo de código

TypeScript Quality Hooks conecta la compilación de TypeScript, el auto-fix de ESLint y el formateo de Prettier al evento post-tool-use con caché de configuración SHA256 para ejecuciones por debajo de cinco segundos. La colección de fcakyon en fcakyon/claude-codex-settings es más amplia: un conjunto curado de hooks para calidad de código y regulación del uso de herramientas (forzar Tavily sobre WebFetch, por ejemplo).

Para casos extremos relevantes para Converly, como mantener la salida en inglés británico incluso cuando el modelo por defecto usa ortografía americana, Britfix merece la pena instalarlo. Nicho, pero del tipo de hook de "cosa pequeña que se acumula" que es difícil de escribir desde cero.

No escribas el tuyo propio desde cero

El mejor recurso para "qué hooks existen que yo podría querer instalar" es awesome-claude-code: más de 44.000 estrellas, un CSV curado de skills, hooks, comandos slash, líneas de estado y herramientas de desarrollo. La sección de Hooks lista actualmente 13 proyectos con nombre (la mayoría de los de arriba vinieron de ahí). La lista se actualiza con frecuencia conforme la comunidad publica cosas nuevas.

Algunas entradas específicas de la lista awesome que merece la pena conocer como principiante, más allá de las categorías ya cubiertas:

  • cchooks, de GowayLee: un SDK ligero de Python para escribir hooks. Si tu lógica de hook supera las diez líneas de bash, este es el siguiente paso. Buena documentación.
  • claude-hooks, de John Lindquist: equivalente en TypeScript, misma idea.
  • parry, de Dmytro Onypko: un escáner de prompt injection para entradas y salidas de hooks. Merece la pena conocerlo si tus hooks procesan texto no fiable.
  • Plannotator, de backnotprop: intercepta ExitPlanMode y te ofrece una interfaz visual de revisión de planes para que puedas editar el plan de Claude antes de que se ejecute. Del tipo de cosa que nunca escribirías tú mismo pero que es genial una vez la ves.

Además de las colecciones más amplias que merece la pena marcar:

La parte de seguridad que nadie menciona hasta que algo va mal

Los hooks se ejecutan con el acceso completo de shell de tu usuario. Ejecutan cualquier comando que tú pongas en settings.json, o peor, cualquier comando que alguien más haya puesto en una configuración que tú has pegado de internet. A principios de año un conjunto de paquetes npm maliciosos fue cazado backdooreando sesiones de Claude Code secuestrando el evento SessionStart. Cinco paquetes, typosquatteados sobre nombres reales, con binarios ocultos que se disparaban en cada arranque de sesión.

Tres reglas que arreglan los modos de fallo obvios:

  1. Lee el comando del hook antes de pegarlo en settings. Si no entiendes lo que hace, no lo ejecutes.
  2. Fija la versión de cualquier paquete npm que instales (some-hook-package@1.4.2, no some-hook-package). Evita el ataque de cadena de suministro en el que la versión maliciosa se publica como el siguiente parche.
  3. Trata los paquetes de hooks igual que tratarías cualquier otro código que se ejecuta como tú en tu máquina. Si no ejecutarías un script aleatorio de internet, no lo pegues en tu configuración de hooks.

El incidente de npm es del tipo de cosa que solo te preocupa después de que le ocurra a otra persona. Merece cinco minutos de cautela ahora para evitar ser la otra persona.

Por dónde empezar

Elige uno de estos e instálalo antes de comer:

  • El auto-formateador si tu equipo tiene discusiones de estilo sobre el código escrito por Claude. Diez minutos, elimina toda una categoría de ruido en revisión.
  • CC Notify o Claudio si ejecutas tareas agénticas largas y quieres ausentarte de la terminal. Veinte minutos de configuración, útil de inmediato.
  • Dippy si has estado saltando los avisos de permiso porque son constantes. La razón honesta por la que la mayoría acaba en modo YOLO es la fricción; Dippy elimina la fricción sin eliminar la seguridad.

Sea cual sea el que elijas, ejecútalo una semana antes de añadir un segundo. Los hooks se acumulan: cada uno te enseña algo sobre cómo Claude se mueve por el bucle, lo que hace que el siguiente sea más fácil de escribir. El objetivo de los hooks no es montar la configuración perfecta el día uno: es darle a Claude Code unos cuantos reflejos automáticos para las cosas que de otro modo harías manualmente, y luego olvidar que existen hasta que se ganan su sitio.

Artículos relacionados