Guía de Hooks en Claude Code

¿Qué son los Hooks en Claude Code?

Los hooks en Claude Code son comandos personalizados que se ejecutan automáticamente en momentos específicos del flujo de trabajo. Piensa en ellos como "gatillos" que activan acciones predefinidas cuando ocurren ciertos eventos, como cuando Claude edita un archivo o ejecuta un comando.

En lugar de depender de que Claude "recuerde" hacer ciertas tareas, los hooks garantizan que estas acciones sucedan de manera consistente y automática.

¿Por qué usar Hooks?

Los hooks te permiten:

• Automatizar tareas repetitivas: Como formatear código automáticamente después de cada edición
• Mantener estándares: Asegurar que el código siga las convenciones de tu equipo
• Recibir notificaciones: Saber cuándo Claude necesita tu atención
• Proteger archivos importantes: Prevenir modificaciones accidentales a archivos críticos
• Registrar actividad: Llevar un historial de los comandos ejecutados

Tipos de Eventos de Hooks

Claude Code ofrece varios momentos donde puedes ejecutar hooks:

PreToolUse

Se ejecuta antes de que Claude use una herramienta. Útil para validar o bloquear acciones.

PostToolUse

Se ejecuta después de que Claude complete una acción. Perfecto para tareas de limpieza o formateo.

UserPromptSubmit

Se activa cuando envías un mensaje a Claude, antes de que lo procese.

Notification

Se ejecuta cuando Claude Code envía notificaciones.

Stop

Se activa cuando Claude termina de responder.

Tu Primer Hook: Registro de Comandos

Vamos a crear un hook simple que registre todos los comandos de terminal que ejecuta Claude.

Paso 1: Abrir la Configuración de Hooks

Ejecuta el comando /hooks en Claude Code y selecciona el evento PreToolUse.

Paso 2: Agregar un Filtro

Selecciona + Add new matcher... y escribe Bash para que el hook solo se active con comandos de terminal.

Paso 3: Crear el Hook

Selecciona + Add new hook... e ingresa este comando:

jq -r '"\(.tool_input.command) - \(.tool_input.description // "Sin descripción")"' >> ~/.claude/registro-comandos.txt

Paso 4: Guardar la Configuración

Selecciona "User settings" para que el hook se aplique a todos tus proyectos.

Paso 5: Probar el Hook

Pide a Claude que ejecute un comando simple como ls y luego revisa tu archivo de registro:

cat ~/.claude/registro-comandos.txt

Deberías ver entradas como:

ls - Lista archivos y directorios

Ejemplos Prácticos Adicionales

Hook de Formateo Automático

Formatea automáticamente archivos TypeScript después de editarlos:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Hook de Notificaciones de Escritorio

Recibe notificaciones cuando Claude necesite tu atención:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Esperando tu respuesta'"
          }
        ]
      }
    ]
  }
}

Hook de Protección de Archivos

Bloquea ediciones a archivos sensibles:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

Consideraciones de Seguridad

Importante: Los hooks se ejecutan automáticamente con tus credenciales del sistema. Siempre revisa el código de los hooks antes de implementarlos para evitar riesgos de seguridad.

Buenas Prácticas:

• Revisa todos los comandos antes de agregarlos
• Usa hooks de fuentes confiables
• Prueba los hooks en un entorno seguro primero
• Mantén backups de tu configuración

Dónde se Almacenan los Hooks

Los hooks se guardan en:

• Configuración de usuario: ~/.claude/settings.json (aplica a todos los proyectos)
• Configuración de proyecto: .claude/settings.json (solo para el proyecto actual)

Próximos Pasos

1. Experimenta con el hook de registro de comandos
2. Identifica tareas repetitivas en tu flujo de trabajo
3. Crea hooks personalizados para automatizar esas tareas
4. Comparte tus hooks útiles con tu equipo

Recursos Adicionales

• Consulta la documentación oficial de hooks para casos de uso avanzados
• Explora ejemplos de la comunidad en el repositorio público de Claude Code
• Únete a foros de desarrolladores para compartir y descubrir nuevos hooks

Los hooks son una herramienta poderosa para personalizar tu experiencia con Claude Code. Comienza con ejemplos simples y gradualmente construye automatizaciones más complejas según tus necesidades específicas.

Abrazo. Bliss. 🤓

---

Conviértete en Power-User de Claude Code en mi talller.