¿Qué son los hooks de Claude Code?
Los hooks de Claude Code son comandos de shell que se ejecutan automáticamente en puntos concretos del ciclo de vida del agente, como antes de que se ejecute una herramienta o al terminar un turno. Como se ejecutan siempre en lugar de depender del modelo, son una forma fiable de imponer reglas y añadir comprobaciones.
Eventos
Los hooks se definen en archivos settings.json y se asocian a un evento. En los eventos de herramientas, un matcher permite apuntar a herramientas concretas, como Bash o Edit.
- PreToolUse: antes de que se ejecute una herramienta; puede bloquear la llamada.
- PostToolUse: después de que termine una herramienta, por ejemplo para formatear el archivo editado.
- UserPromptSubmit: antes de que tu mensaje llegue al modelo.
- Stop: cuando el agente termina su turno.
- SessionStart: cuando empieza una sesión, útil para añadir contexto.
- Notification: cuando Claude Code envía una notificación.
Cómo funciona
El comando del hook recibe los detalles del evento, como el nombre y la entrada de la herramienta, en JSON por la entrada estándar. Su código de salida le dice a Claude Code qué hacer: 0 significa continuar y 2 bloquea la acción y pasa el mensaje de error al modelo. Para un control más fino, un hook también puede devolver una decisión y un motivo en JSON.
Para qué se usan
Los hooks convierten en regla todo lo que el modelo podría olvidar.
- Bloquear comandos peligrosos o lecturas de archivos como .env.
- Ejecutar un formateador o un linter después de cada edición.
- Reescribir comandos para que su salida sea más corta.
- Enviar una notificación o ejecutar pruebas al terminar un turno.
Cosas a tener en cuenta
Los hooks se ejecutan con los permisos de tu usuario y sin preguntar, así que no añadas el hook de otra persona sin leerlo. Un hook lento ralentiza cada llamada a una herramienta, por lo que conviene mantenerlos rápidos. El texto que devuelve un hook puede acabar en el contexto del modelo, así que mantenlo breve.
Hooks en AgentVera
AgentVera ejecuta varias de sus funciones como hooks en los agentes de Claude Code. En cambio, el perfil de contexto “Lean” no carga los hooks del nivel de usuario.
- “Smart tools”: cuatro hooks que bloquean lecturas repetidas de archivos, reducen las ejecuciones completas de pruebas a las pruebas afectadas, informan de nuevos errores de tipos justo después de una edición y comparten el resultado de un comando entre agentes. Todos vienen activados por defecto.
- RTK: los comandos Bash de Claude Code se reescriben mediante un hook en versiones con salida más corta (git status → rtk git status).
- Codex no tiene hooks, así que RTK funciona allí mediante instrucciones, y las “smart tools” solo se ejecutan en agentes locales de Claude Code.
- Herramientas inteligentesRecorta lecturas repetidas, ejecuciones completas de tests y comandos repetidos antes de que lleguen al modelo.
- Ahorro de tokensPerfiles de contexto, salida de comandos más corta con RTK, tamaño del contexto en vivo y compactación automática, activado por defecto en todos los agentes.
Preguntas frecuentes
¿Dónde se configuran los hooks de Claude Code?
En archivos settings.json: ~/.claude/settings.json para tu usuario, .claude/settings.json para el proyecto y .claude/settings.local.json solo para tu máquina. También puedes gestionarlos con el comando /hooks.
¿Cómo bloquea un hook un comando?
Si un hook PreToolUse termina con el código 2, la llamada a la herramienta se bloquea y la salida de error del hook llega al modelo como motivo.
¿Son seguros los hooks?
Los hooks son comandos de shell que se ejecutan con tus permisos, así que son tan seguros como lo que contienen. Lee los hooks de proyecto que vengan con un repo antes de ejecutarlos.
¿Qué diferencia hay entre un hook y una skill?
Un hook es un comando que se ejecuta cada vez que ocurre un evento determinado; el modelo no decide. Una skill es un conjunto de instrucciones y archivos que el modelo carga cuando considera que es relevante.