≡En resumen
- Un hook es una regla que se ejecuta siempre que ocurre un evento, a diferencia de una instrucción en CLAUDE.md, que Claude puede interpretar.
- PreToolUse puede permitir, denegar o pedir confirmación antes de que Claude use una herramienta, e incluso modificar sus argumentos.
- Un comando que termina con código de salida 2 bloquea la acción y su mensaje de error se le devuelve a Claude como motivo.
- Se definen en archivos de ajustes JSON y se combinan entre niveles; los hooks gestionados por la empresa no se pueden quitar desde niveles inferiores.
- Ejecutan código en tu máquina con tus permisos: revisa siempre los hooks de proyectos o plugins de terceros antes de confiar en ellos.
01 ¿Qué son los hooks de Claude Code?
Los hooks son puntos de enganche del ciclo de vida de Claude Code, el agente de programación de Anthropic. Cuando ocurre un evento concreto (Claude está a punto de ejecutar un comando, acaba de editar un archivo, has enviado un prompt o la sesión arranca), Claude Code ejecuta la acción que tú hayas configurado para ese evento.
La diferencia con pedirle algo a Claude es el grado de garantía. Si escribes en tu archivo de instrucciones "formatea siempre el código después de editar", el modelo lo intentará, pero puede olvidarlo en una sesión larga. Un hook de PostToolUse que lanza el formateador después de cada edición se ejecuta siempre, sin depender del criterio del modelo.
02 Eventos de hooks disponibles
La lista de eventos ha crecido mucho desde que se lanzaron los hooks y hoy supera la treintena, desde el arranque de la sesión hasta la compactación del contexto o la creación de worktrees. Estos son los que más vas a usar en la práctica:
| Evento | Cuándo se dispara | Uso típico |
|---|---|---|
| SessionStart | Al iniciar o reanudar una sesión | Cargar contexto dinámico, variables de entorno o el estado del proyecto |
| UserPromptSubmit | Cuando envías un prompt, antes de que Claude lo procese | Añadir contexto, validar o bloquear prompts con datos sensibles |
| PreToolUse | Antes de ejecutar una herramienta | Bloquear comandos peligrosos, proteger archivos o reescribir argumentos |
| PermissionRequest | Cuando Claude Code va a mostrar un aviso de permiso | Aprobar o denegar automáticamente según tus propias reglas |
| PostToolUse | Después de que una herramienta termina bien | Formatear, ejecutar el linter o lanzar tests tras una edición |
| Notification | Cuando Claude Code envía una notificación | Avisarte en el escritorio, Slack o el móvil cuando necesita tu atención |
| Stop / SubagentStop | Cuando Claude o un subagente termina de responder | Comprobar que la tarea está realmente acabada antes de parar |
| PreCompact / PostCompact | Antes y después de compactar el contexto | Guardar notas o reinyectar información clave |
| SessionEnd | Al cerrar la sesión | Limpieza, registros o métricas de uso |
03 Cómo se configuran los hooks
Los hooks se declaran en la clave hooks de un archivo de ajustes. Cada evento tiene una lista de grupos con un matcher (qué herramienta o caso filtra) y una lista de acciones. El matcher admite el nombre exacto de una herramienta, varios separados por | (por ejemplo Edit|Write) o una expresión regular, y las herramientas MCP se nombran como mcp__servidor__herramienta.
| Ubicación | Alcance | ¿Se comparte? |
|---|---|---|
| ~/.claude/settings.json | Todos tus proyectos | No, solo en tu equipo |
| .claude/settings.json | Un proyecto | Sí, se puede subir al repositorio |
| .claude/settings.local.json | Un proyecto, solo para ti | No, queda fuera de git |
| Ajustes gestionados | Toda la organización | Sí, los impone el administrador |
| hooks/hooks.json de un plugin | Mientras el plugin está activo | Sí, con el plugin |
| Frontmatter de una skill o subagente | Solo mientras se ejecuta esa skill o subagente | Sí, con la skill o el subagente |
En .claude/settings.json añades al evento PreToolUse un grupo con "matcher": "Bash" y una acción de tipo command que ejecuta ${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh, con el filtro opcional "if": "Bash(rm *)" para que solo se lance con comandos rm.
El script lee por la entrada estándar un JSON con la herramienta y sus argumentos. Si la ruta es peligrosa, devuelve un JSON con permissionDecision: "deny" y un motivo; si no, termina con código 0 y deja que el flujo de permisos normal decida.
04 Códigos de salida y control de decisiones
Un hook de tipo command recibe la información del evento en JSON por la entrada estándar y se comunica con Claude Code mediante su código de salida y lo que imprime. Esto es lo que debes saber para que haga lo que esperas:
| Resultado | Efecto |
|---|---|
| Código 0 | Éxito. Si la salida es un único objeto JSON, se aplican sus campos; si no, se trata como texto. |
| Código 2 | Error bloqueante: en los eventos que lo admiten se detiene la acción y el texto de stderr se le pasa a Claude como motivo. |
| Otro código (incluido 1) | Error no bloqueante: la acción sigue y tú ves un aviso de error del hook. |
| JSON con permissionDecision | En PreToolUse: allow, deny, ask o defer, con un motivo opcional. |
| JSON con updatedInput | Sustituye los argumentos de la herramienta antes de ejecutarla. |
| JSON con additionalContext | Añade texto al contexto de Claude. |
05 Casos de uso reales de los hooks
Formateo automático
PostToolUse con matcher Edit|Write que lanza Prettier, Pint o Black sobre el archivo modificado.
Proteger archivos
PreToolUse que deniega cualquier edición de .env, migraciones ya aplicadas o carpetas de producción.
Comandos seguros
Bloquear rm -rf, git push --force o llamadas a la base de datos de producción con un motivo claro.
Avisos
Notification que manda un aviso al escritorio o a un canal cuando Claude espera tu respuesta.
Calidad antes de terminar
Stop que ejecuta los tests y, si fallan, impide que Claude dé la tarea por cerrada.
Contexto al arrancar
SessionStart que inyecta la rama actual, las incidencias abiertas o el estado del despliegue.
En equipos de producto, los hooks son la forma de convertir las normas del equipo en algo que se cumple solo. En nuestra agencia de desarrollo web los usamos para pasar el formateador y el análisis estático después de cada cambio, de modo que el código que genera Claude llega a revisión con el mismo estilo que el resto del proyecto.
06 Hooks frente a CLAUDE.md, permisos y skills
Claude Code ofrece varias formas de guiar al agente y es fácil confundirlas. Las instrucciones de CLAUDE.md son contexto que el modelo lee y procura seguir; los hooks son código que se ejecuta pase lo que pase. Los modos de permisos y sus reglas deciden qué puede hacer Claude sin preguntarte, y los hooks pueden completar esas reglas con lógica que una regla simple no expresa.
| Necesitas | Usa | Por qué |
|---|---|---|
| Convenciones, comandos y arquitectura del proyecto | CLAUDE.md | Es contexto que Claude lee en cada sesión |
| Permitir o prohibir herramientas concretas | Reglas de permisos | Son declarativas y fáciles de auditar |
| Una garantía que no dependa del modelo | Hook | Se ejecuta siempre que ocurre el evento |
| Un procedimiento de varios pasos bajo demanda | Skill | Se carga solo cuando hace falta |
| Repartir hooks, skills y servidores MCP a todo el equipo | Plugin | Empaqueta la configuración para instalarla de una vez |
07 Seguridad y buenas prácticas
- ✓Guarda los scripts en .claude/hooks/ y llámalos con ${CLAUDE_PROJECT_DIR} para que funcionen desde cualquier carpeta.
- ✓Valida y entrecomilla las rutas que llegan en el JSON de entrada; nunca las pases sin revisar a la shell.
- ✓Usa el filtro if o un matcher concreto para no lanzar el hook en cada herramienta.
- ✓Haz que los hooks sean rápidos: se ejecutan en el camino crítico de cada acción.
- ✓Explica siempre el motivo al denegar, para que Claude pueda corregir su enfoque.
- ✓Revisa con /hooks qué hooks están activos y de dónde vienen (usuario, proyecto, local o plugin).
- ✓Para desactivarlos todos temporalmente, usa disableAllHooks en un archivo de ajustes.
08 Cómo crear tu primer hook paso a paso
-
1
Elige el evento
Piensa qué quieres garantizar: si es antes de una acción, PreToolUse; si es después, PostToolUse; si es al terminar, Stop.
-
2
Escribe el script
Crea un script en .claude/hooks/ que lea el JSON de la entrada estándar, tome la decisión y salga con el código adecuado.
-
3
Declara el hook
Añádelo en .claude/settings.json con su matcher, o pide a Claude que lo haga: puede editar el archivo de ajustes por ti.
-
4
Pruébalo
Provoca el evento a propósito, por ejemplo pidiendo una edición, y comprueba que el hook se lanza y responde como esperas.
-
5
Compártelo
Sube la configuración al repositorio o empaquétala en un plugin para que todo el equipo trabaje con las mismas reglas.
Los hooks son una pieza más de la automatización de un equipo que trabaja con agentes. Si quieres llevar esa lógica más allá del código y automatizar procesos con IA en el resto de la empresa, o comparar herramientas que amplían Claude Code, consulta nuestro directorio de herramientas para Claude.
Preguntas frecuentes sobre Hooks de Claude Code
Es una acción que Claude Code ejecuta automáticamente cuando ocurre un evento, como antes de usar una herramienta o al terminar una respuesta. Puede ser un comando de shell, una petición HTTP, una llamada a una herramienta MCP o una consulta a un modelo.
En la clave hooks de un archivo de ajustes: ~/.claude/settings.json para todos tus proyectos, .claude/settings.json para un proyecto compartido o .claude/settings.local.json para uso personal. También pueden venir de ajustes gestionados, plugins, skills y subagentes.
Usa el evento PreToolUse con matcher Bash y un script que, si detecta el comando, termine con código de salida 2 y explique el motivo por stderr, o devuelva un JSON con permissionDecision deny.
Sí. Los hooks se ejecutan en todos los modos de permisos, y una denegación devuelta por un hook bloquea la acción aunque el modo no pida confirmación.
Escribe /hooks en una sesión. Se abre un explorador de solo lectura con cada hook configurado y su origen: usuario, proyecto, local, plugin o sesión.
Sí, con disableAllHooks en true en un archivo de ajustes. No existe un interruptor por hook: para quitar uno concreto hay que borrar su entrada. Los hooks gestionados por la organización solo se desactivan desde ese mismo nivel.
Fuentes consultadas
Sobre el autor
Germán Gutiérrez
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil en LinkedIn ↗