Los hooks de Claude Code son comandos de shell definidos por el usuario que se ejecutan en varios puntos del ciclo de vida de Claude Code. Los hooks proporcionan control determinístico sobre el comportamiento de Claude Code, asegurando que ciertas acciones siempre ocurran en lugar de depender de que el LLM elija ejecutarlas.

Para documentación de referencia sobre hooks, consulta Referencia de hooks.

Los casos de uso de ejemplo para hooks incluyen:

  • Notificaciones: Personaliza cómo recibes notificaciones cuando Claude Code está esperando tu entrada o permiso para ejecutar algo.
  • Formato automático: Ejecuta prettier en archivos .ts, gofmt en archivos .go, etc. después de cada edición de archivo.
  • Registro: Rastrea y cuenta todos los comandos ejecutados para cumplimiento o depuración.
  • Retroalimentación: Proporciona retroalimentación automatizada cuando Claude Code produce código que no sigue las convenciones de tu base de código.
  • Permisos personalizados: Bloquea modificaciones a archivos de producción o directorios sensibles.

Al codificar estas reglas como hooks en lugar de instrucciones de prompting, conviertes sugerencias en código a nivel de aplicación que se ejecuta cada vez que se espera que se ejecute.

Debes considerar las implicaciones de seguridad de los hooks al agregarlos, porque los hooks se ejecutan automáticamente durante el bucle del agente con las credenciales de tu entorno actual. Por ejemplo, el código de hooks malicioso puede exfiltrar tus datos. Siempre revisa tu implementación de hooks antes de registrarlos.

Para las mejores prácticas de seguridad completas, consulta Consideraciones de Seguridad en la documentación de referencia de hooks.

​
Resumen de Eventos de Hook

Claude Code proporciona varios eventos de hook que se ejecutan en diferentes puntos del flujo de trabajo:

  • PreToolUse: Se ejecuta antes de las llamadas de herramientas (puede bloquearlas)
  • PostToolUse: Se ejecuta después de que las llamadas de herramientas se completan
  • Notification: Se ejecuta cuando Claude Code envía notificaciones
  • Stop: Se ejecuta cuando Claude Code termina de responder
  • SubagentStop: Se ejecuta cuando las tareas del subagente se completan

Cada evento recibe datos diferentes y puede controlar el comportamiento de Claude de diferentes maneras.

​
Inicio Rápido

En este inicio rápido, agregarás un hook que registra los comandos de shell que Claude Code ejecuta.

​
Prerrequisitos

Instala jq para procesamiento JSON en la línea de comandos.

​
Paso 1: Abrir configuración de hooks

Ejecuta el comando slash /hooks y selecciona el evento de hook PreToolUse.

Los hooks PreToolUse se ejecutan antes de las llamadas de herramientas y pueden bloquearlas mientras proporcionan retroalimentación a Claude sobre qué hacer de manera diferente.

​
Paso 2: Agregar un matcher

Selecciona + Add new matcher… para ejecutar tu hook solo en llamadas de herramientas Bash.

Escribe Bash para el matcher.

Usa una cadena vacía "" para coincidir con todas las herramientas. El carácter * no es un matcher válido por sí solo.

​
Paso 3: Agregar el hook

Selecciona + Add new hook… e ingresa este comando:

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​
Paso 4: Guardar tu configuración

Para la ubicación de almacenamiento, selecciona User settings ya que estás registrando en tu directorio home. Este hook se aplicará entonces a todos los proyectos, no solo a tu proyecto actual.

Luego presiona Esc hasta que regreses al REPL. ¡Tu hook ahora está registrado!

​
Paso 5: Verificar tu hook

Ejecuta /hooks nuevamente o verifica ~/.claude/settings.json para ver tu configuración:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​
Paso 6: Probar tu hook

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

cat ~/.claude/bash-command-log.txt

Deberías ver entradas como:

ls - Lists files and directories

​
Más Ejemplos

Para una implementación de ejemplo completa, consulta el ejemplo de validador de comandos bash en nuestra base de código pública.

​
Hook de Formato de Código

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

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

​
Hook de Notificación Personalizada

Obtén notificaciones de escritorio cuando Claude necesite entrada:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Awaiting your input'"
          }
        ]
      }
    ]
  }
}

​
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)\""
          }
        ]
      }
    ]
  }
}

​
Aprende más

  • Para documentación de referencia sobre hooks, consulta Referencia de hooks.
  • Para mejores prácticas de seguridad integrales y pautas de seguridad, consulta Consideraciones de Seguridad en la documentación de referencia de hooks.
  • Para pasos de solución de problemas y técnicas de depuración, consulta Depuración en la documentación de referencia de hooks.