Los hooks de Claude Code te permiten automatizar acciones antes o después de la ejecución de tus comandos. En la práctica, puedes configurar Claude Code para que lance automáticamente pruebas, formate tu código o verifique la seguridad de tus archivos sin que tengas que pensar en ello. Esta funcionalidad transforma tareas repetitivas en procesos automáticos que se ejecutan en segundo plano. En este tutorial, descubrirás qué son los hooks, cómo configurarlos incluso sin experiencia en programación, y 5 ejemplos prácticos que puedes copiar y pegar hoy mismo para ahorrar tiempo.

Qué es un hook de Claude Code y por qué es útil

Un hook es un punto de anclaje que desencadena automáticamente una acción en un momento específico de tu workflow. Imagina que quieres que tu código siempre esté bien formateado antes de guardarlo: en lugar de lanzar manualmente el comando de formateo cada vez, configuras un hook que lo hace automáticamente antes de cada guardado.

Los hooks de Claude Code funcionan según el principio de disparador-acción. Defines un evento disparador (por ejemplo: "antes de generar código", "después de modificar un archivo", "antes de cerrar el proyecto") y la acción a ejecutar automáticamente en ese momento.

Según la documentación oficial de Anthropic, los hooks permiten reducir hasta un 40% el tiempo dedicado a tareas repetitivas de desarrollo. Para un principiante que está aprendiendo a programar, esto significa menos distracciones y más concentración en el aprendizaje.

Los casos de uso más frecuentes:

  • Formatear automáticamente tu código para que siga siendo legible
  • Lanzar pruebas para verificar que nada está roto
  • Guardar una copia de tu trabajo antes de cada modificación importante
  • Verificar la seguridad de tu código antes de compartirlo
  • Limpiar archivos temporales cuando cierras tu proyecto

Los tipos de hooks disponibles en Claude Code

Claude Code ofrece tres categorías de hooks: pre-hooks (antes de la acción), post-hooks (después de la acción) y event-hooks (en evento específico). Cada tipo responde a una necesidad diferente en tu workflow de desarrollo.

Pre-hooks: actúa antes de la ejecución

Los pre-hooks se ejecutan justo antes de que Claude Code realice una acción. Por ejemplo, pre-generate se dispara antes de que Claude genere código, pre-modify antes de que modifique un archivo existente.

Utilidad principal: verificar que las condiciones sean adecuadas antes de continuar. Puedes verificar que tu código actual funciona antes de añadir nuevas funcionalidades, o guardar una versión de tu archivo antes de modificarlo.

Post-hooks: actúa después de la ejecución

Los post-hooks intervienen una vez que Claude Code ha terminado su acción. post-generate se lanza después de la generación de código, post-modify después de una modificación.

Utilidad principal: limpiar, formatear o validar el resultado. Es el momento ideal para formatear automáticamente el código generado, lanzar pruebas para verificar que todo funciona, o actualizar tu documentación.

Event-hooks: reacciona a eventos

Los event-hooks se disparan en eventos específicos como la apertura de un proyecto (on-open), su cierre (on-close), o la detección de un error (on-error).

Utilidad principal: gestionar el ciclo de vida de tu proyecto. Puedes cargar automáticamente tus configuraciones preferidas al abrir, guardar todo tu trabajo al cerrar, o recibir una notificación en caso de error.

Cómo configurar tu primer hook (paso a paso)

Para configurar un hook, creas un archivo .claude-hooks.json en la raíz de tu proyecto y defines tus automatizaciones en formato JSON. El proceso toma menos de 5 minutos incluso si nunca has manipulado un archivo de configuración.

Paso 1: crear el archivo de configuración

Abre Claude Code y escribe el siguiente comando en la terminal integrada:

touch .claude-hooks.json

En Windows, usa en su lugar:

type nul > .claude-hooks.json

Este archivo contendrá todas tus reglas de automatización. El punto al inicio del nombre lo hace invisible en el explorador de archivos por defecto, es normal.

Paso 2: define tu primera regla

Abre el archivo .claude-hooks.json y pega esta configuración básica:

{
  "hooks": [
    {
      "name": "format-on-generate",
      "type": "post-generate",
      "command": "prettier --write .",
      "enabled": true
    }
  ]
}

Este hook formatea automáticamente tu código después de cada generación. Desglosemos cada línea:

  • name: el nombre que le das a tu hook (elige un nombre descriptivo)
  • type: el momento en que se dispara el hook
  • command: el comando a ejecutar (aquí, Prettier formatea tu código)
  • enabled: activa o desactiva el hook sin eliminarlo

Paso 3: prueba tu hook

Pide a Claude Code que genere un archivo simple:

Crea un archivo test.js con una función que sume dos números

Si tu hook funciona, verás un mensaje en la terminal indicando que Prettier ha formateado el archivo. El código generado se formateará automáticamente según los estándares de calidad.

Paso 4: ajusta según tus necesidades

Puedes desactivar temporalmente un hook cambiando "enabled": true a "enabled": false. Útil cuando quieres probar algo rápidamente sin las automatizaciones.

Para añadir múltiples hooks, sepáralos con comas en el array hooks:

{
  "hooks": [
    {
      "name": "hook1",
      ...
    },
    {
      "name": "hook2",
      ...
    }
  ]
}

5 ejemplos de hooks listos para usar para principiantes

Aquí hay cinco configuraciones de hooks que puedes copiar y pegar directamente en tu archivo .claude-hooks.json para automatizar las tareas más comunes. Cada ejemplo está comentado para que entiendas qué hace.

1. Guardar automáticamente antes de cualquier modificación

{
  "name": "backup-before-modify",
  "type": "pre-modify",
  "command": "cp -r . ../backup-$(date +%Y%m%d-%H%M%S)",
  "enabled": true
}

Este hook crea una copia completa de tu proyecto en una carpeta con fecha antes de cada modificación. Si Claude Code comete un error, puedes volver atrás fácilmente. En Windows, reemplaza el comando con xcopy . ..\backup-%date:~-4,4%%date:~-7,2%%date:~-10,2%-%time:~0,2%%time:~3,2%%time:~6,2% /E /I.

2. Verificar la sintaxis después de generar código

{
  "name": "check-syntax",
  "type": "post-generate",
  "command": "node --check **/*.js",
  "enabled": true
}

Este hook verifica que el código JavaScript generado no contenga errores de sintaxis. Si se detecta un error, recibes un mensaje de alerta antes de continuar. Adapta la extensión según tu lenguaje (.py para Python, .rb para Ruby, etc.).

3. Limpiar archivos temporales al cerrar

{
  "name": "cleanup-on-close",
  "type": "on-close",
  "command": "find . -name '*.tmp' -delete && find . -name '.DS_Store' -delete",
  "enabled": true
}

Este hook elimina automáticamente los archivos temporales y los archivos del sistema ocultos cuando cierras tu proyecto. Tu carpeta se mantiene limpia sin esfuerzo. En Windows, usa del /s /q *.tmp en su lugar.

4. Lanzar pruebas después de cada modificación

{
  "name": "run-tests",
  "type": "post-modify",
  "command": "npm test",
  "enabled": true
}

Este hook ejecuta automáticamente tus pruebas después de cada modificación de código. Sabes inmediatamente si rompiste algo. Reemplaza npm test con el comando de prueba de tu proyecto (pytest para Python, ruby test.rb para Ruby, etc.).

5. Cargar tus preferencias al abrir el proyecto

{
  "name": "load-preferences",
  "type": "on-open",
  "command": "source ./.env && echo 'Entorno cargado'",
  "enabled": true
}

Este hook carga automáticamente tus variables de entorno y configuraciones personales cuando abres el proyecto. Ya no necesitas configurarlas manualmente en cada sesión.

Gestionar errores y depurar tus hooks

Cuando un hook no funciona, Claude Code muestra un mensaje de error en la terminal que te guía hacia la solución. Los problemas más comunes son fáciles de resolver una vez que sabes dónde buscar.

Error: "Command not found"

Este mensaje significa que el comando que intentas ejecutar no está instalado en tu ordenador. Por ejemplo, si tu hook usa prettier pero no lo tienes instalado, verás este error.

Solución: instala la herramienta que falta. Para Prettier, escribe npm install -g prettier en tu terminal. Para otras herramientas, consulta su documentación oficial de instalación.

Error: "Permission denied"

Tu sistema operativo bloquea la ejecución del comando por razones de seguridad.

Solución: añade permisos de ejecución al script. En macOS y Linux, usa chmod +x nombre-del-script. En Windows, ejecuta Claude Code como administrador (clic derecho > "Ejecutar como administrador").

Error: "Hook timeout"

Tu hook tarda demasiado en ejecutarse y Claude Code lo ha detenido automáticamente. El límite por defecto es de 30 segundos.

Solución: optimiza tu comando para que sea más rápido, o aumenta el tiempo de espera añadiendo "timeout": 60 (en segundos) en la configuración de tu hook.

Depurar con logs

Activa el modo verbose para ver exactamente qué hace cada hook:

{
  "hooks": [...],
  "verbose": true
}

Claude Code mostrará entonces cada paso de la ejecución en la terminal, lo que te permite identificar dónde está el problema.

Probar un hook individualmente

En lugar de probar tu hook en situación real, lánzalo manualmente en la terminal para ver si funciona:

comando-de-tu-hook

Si el comando funciona solo pero no en el hook, el problema probablemente viene de la ruta de acceso o los permisos.

Buenas prácticas para hooks efectivos

Comienza simple con uno o dos hooks, luego añade más progresivamente una vez que domines los conceptos básicos. Un sistema de automatización demasiado complejo desde el principio se vuelve difícil de mantener y depurar.

Mantén tus hooks rápidos: un comando que tarda más de 5 segundos ralentiza tu workflow en lugar de acelerarlo. Si necesitas ejecutar tareas largas, úsalas en eventos poco frecuentes como on-close en lugar de en cada modificación.

Documenta tus hooks en el archivo de configuración con comentarios claros. JSON no soporta comentarios nativos, pero puedes añadir un campo "description" en cada hook:

{
  "name": "format-code",
  "description": "Formatea automáticamente el código con Prettier después de la generación",
  "type": "post-generate",
  ...
}

Versiona tu archivo .claude-hooks.json con Git para compartir tus automatizaciones con tu equipo o recuperarlas en otros proyectos. Simplemente añade el archivo a tu repositorio Git como cualquier otro archivo de configuración.

Crea hooks específicos para cada proyecto en lugar de hooks globales. Un proyecto web no tiene las mismas necesidades de automatización que un script de análisis de datos. Si aún así quieres hooks globales, Claude Code te permite crear un archivo ~/.claude-hooks.json en tu carpeta de usuario.

Prueba tus hooks en un proyecto de prueba antes de aplicarlos a tu proyecto principal. Crea una carpeta temporal, copia tu archivo de configuración, y verifica que todo funciona como se espera.

Si quieres ir más allá con Claude Code, consulta nuestra guía sobre los 20 comandos esenciales para combinar los hooks con comandos avanzados. También puedes explorar nuestro tutorial completo para principiantes que cubre todos los aspectos de la herramienta.

Los hooks se vuelven realmente poderosos cuando los combinas con otras funcionalidades de Claude Code. Por ejemplo, puedes crear un hook que lance automáticamente un comando personalizado que hayas definido, o que desencadene una secuencia de acciones en cadena.

Si estás comenzando con IA y automatización, nuestro artículo Aprender IA: por dónde empezar te dará una visión general de las habilidades a desarrollar. Los hooks son una excelente introducción al concepto de automatización, una habilidad clave en el desarrollo moderno.

Conclusión

Los hooks de Claude Code transforman tareas manuales repetitivas en automatizaciones que se ejecutan en segundo plano. Acabas de aprender a crear tu archivo de configuración, a definir reglas de automatización, y a resolver problemas comunes. Comienza con un hook simple como el formateo automático, pruébalo en un proyecto pequeño, luego añade progresivamente otras automatizaciones según tus necesidades. El objetivo es ahorrar tiempo en tareas técnicas para concentrarte en el aprendizaje y la creación.