$ man how-to/how-to-setup-claude-code-hooks

Los hooks son comandos de shell que se ejecutan automaticamente en puntos especificos del ciclo de vida de Claude Code. Te dan control deterministico sobre el comportamiento del agente. En lugar de esperar que Claude recuerde formatear codigo despues de una edicion, un hook lo garantiza. La palabra clave es deterministico. Las instrucciones de CLAUDE.md son sugerencias - el modelo generalmente las sigue pero podria no hacerlo. Los hooks son garantias. Un hook pre-command que bloquea rm -rf siempre lo bloqueara. Un hook post-edit que ejecuta Prettier siempre formateara el archivo. Los hooks ejecutan tu codigo, no el de Claude. Ejecutan comandos de shell en tu maquina. Esto los hace poderosos (puedes hacer cualquier cosa que un script de shell pueda hacer) y peligrosos (un hook malo puede romper tu flujo de trabajo). Empieza simple, agrega complejidad segun sea necesario.

PATTERN

Claude Code soporta hooks en estos puntos del ciclo de vida: PreToolUse: Se ejecuta antes de que Claude ejecute una herramienta (edicion de archivo, comando bash, etc.). Usa esto para bloquear comandos peligrosos, validar rutas de archivos o inyectar contexto. Si tu hook devuelve un codigo de salida distinto de cero, la llamada a la herramienta se bloquea. PostToolUse: Se ejecuta despues de que Claude ejecuta una herramienta. Usa esto para formatear archivos editados, ejecutar linters, enviar notificaciones o registrar cambios. La llamada a la herramienta ya ocurrio - estas reaccionando a ella. Notification: Se ejecuta cuando Claude necesita input humano o quiere notificarte. Usa esto para enviar mensajes de Slack, reproducir sonidos o disparar notificaciones del sistema cuando Claude esta esperando aprobacion. Stop: Se ejecuta cuando Claude termina una respuesta. Usa esto para limpieza, registro o disparar flujos de trabajo post-respuesta. Cada hook recibe contexto sobre lo que lo activo: el nombre de la herramienta, la ruta del archivo, el comando o el mensaje de notificacion. Usas este contexto para decidir que debe hacer tu hook.

CODE

Ejecuta /hooks en Claude Code para abrir la configuracion interactiva de hooks. O edita tu configuracion directamente. Los hooks viven en la configuracion de Claude Code (ya sea a nivel de proyecto en .claude/settings.json o a nivel de usuario en ~/.claude/settings.json). El formato es un objeto JSON que mapea tipos de hooks a arrays de configuraciones de hooks. Cada hook tiene: un matcher (que herramienta o evento lo activa), un command (que ejecutar) y opcionalmente un timeout. Ejemplo: un hook PostToolUse que formatea archivos TypeScript despues de ediciones. El matcher verifica si la herramienta fue "Edit" o "Write" y el archivo termina en .ts o .tsx. El comando ejecuta Prettier en el archivo editado. Cada vez que Claude edita un archivo TypeScript, se auto-formatea. Ejemplo: un hook PreToolUse que bloquea comandos bash peligrosos. El matcher verifica si la herramienta es "Bash" y el comando contiene "rm -rf" o "drop table" o "force push." Si coincide, el hook sale con codigo 1 y bloquea el comando. Claude ve el bloqueo y ajusta su enfoque. Empieza con estos dos patrones: auto-formateo despues de ediciones y bloqueo de comandos peligrosos. Proporcionan valor inmediato con complejidad minima.

PATTERN

Escaneo de seguridad: Un hook PreToolUse que revisa archivos editados en busca de secretos codificados (claves API, contraseñas, tokens) antes de que la edicion se aplique. Usa un patron grep simple contra el nuevo contenido. Bloquea la edicion si se detectan secretos. Notificacion en inactividad: Un hook Notification que envia una notificacion de macOS o mensaje de Slack cuando Claude esta esperando aprobacion. Util cuando ejecutas tareas largas - puedes trabajar en otra cosa y recibir un aviso cuando Claude te necesita. Auto-testing: Un hook PostToolUse que ejecuta el archivo de test relevante despues de cualquier edicion de archivo fuente. Si editas src/auth.ts, el hook ejecuta tests/auth.test.ts automaticamente. Claude ve los resultados del test en su siguiente turno. Seguridad de git: Un hook PreToolUse que previene que Claude ejecute git push --force, git reset --hard o git checkout . sin confirmacion explicita. Estos son los comandos destructivos de git que pueden perder trabajo. Inyeccion de contexto: Un hook PreToolUse que se ejecuta al inicio de sesion y agrega la fecha de hoy, la rama actual de git y mensajes de commits recientes al contexto. Claude empieza cada sesion con conciencia situacional fresca.

PRO TIP

Los hooks se ejecutan sincronicamente. Un hook lento bloquea a Claude de proceder. Mantén los hooks rapidos - menos de 2 segundos. Si necesitas ejecutar algo lento (una suite de tests completa, un build), hazlo en segundo plano y reporta resultados asincronicamente. Los errores de hooks son visibles para Claude. Si tu hook imprime a stderr o sale con un codigo distinto de cero, Claude lo ve como retroalimentacion. Esto es util: un hook que bloquea un comando e imprime "Bloqueado: nunca hagas force push a main" le enseña a Claude a evitar ese comando en turnos futuros. Prueba los hooks fuera de Claude Code primero. Escribe el comando de shell, ejecutalo manualmente, verifica que funciona. Luego agregalo como hook. Depurar un hook roto dentro de una sesion activa de Claude Code es frustrante. Los matchers son coincidencias de cadenas, no regex (en la configuracion basica). Usa el campo command para logica de coincidencia compleja. Tu script de hook puede inspeccionar el contexto completo y decidir si actuar o dejar pasar. El orden de los hooks importa. Los hooks del mismo tipo se ejecutan en orden de array. Si tienes dos hooks PreToolUse, el primero se ejecuta primero. Si bloquea la herramienta, el segundo nunca se ejecuta.