Automatizar flujos de trabajo con hooks

​

Configura tu primer hook

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

notify-send 'Claude Code' 'Claude Code needs your attention'

powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

​

Qué puedes automatizar

• Recibe notificaciones cuando Claude necesita entrada
• Formatea automáticamente el código después de ediciones
• Bloquea ediciones a archivos protegidos
• Reinyecta contexto después de compactación
• Audita cambios de configuración

​

Recibe notificaciones cuando Claude necesita entrada

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

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

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Formatea automáticamente el código después de ediciones

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

Bloquea ediciones a archivos protegidos

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Reinyecta contexto después de compactación

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Audita cambios de configuración

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Cómo funcionan los hooks

• "type": "http": POST de datos de evento a una URL. Consulta HTTP hooks.
• "type": "prompt": evaluación LLM de un solo turno. Consulta Hooks basados en prompts.
• "type": "agent": verificación multi-turno con acceso a herramientas. Consulta Hooks basados en agentes.

​

Lee entrada y devuelve salida

​

Entrada del hook

{
  "session_id": "abc123",          // ID único para esta sesión
  "cwd": "/Users/sarah/myproject", // directorio de trabajo cuando se activó el evento
  "hook_event_name": "PreToolUse", // qué evento activó este hook
  "tool_name": "Bash",             // la herramienta que Claude está a punto de usar
  "tool_input": {                  // los argumentos que Claude pasó a la herramienta
    "command": "npm test"          // para Bash, este es el comando de shell
  }
}

​

Salida del hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr se convierte en retroalimentación de Claude
  exit 2 # exit 2 = bloquea la acción
fi

exit 0  # exit 0 = permite que proceda

• Exit 0: la acción procede. Para hooks UserPromptSubmit y SessionStart, cualquier cosa que escribas en stdout se añade al contexto de Claude.
• Exit 2: la acción se bloquea. Escribe una razón en stderr, y Claude la recibe como retroalimentación para que pueda ajustar.
• Cualquier otro código de salida: la acción procede. Stderr se registra pero no se muestra a Claude. Alterna el modo detallado con Ctrl+O para ver estos mensajes en la transcripción.

​

Salida JSON estructurada

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow": procede sin mostrar un aviso de permiso
• "deny": cancela la llamada a herramienta y envía la razón a Claude
• "ask": muestra el aviso de permiso al usuario como es normal

​

Filtra hooks con matchers

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Configura la ubicación del hook

​

Hooks basados en prompts

• "ok": true: la acción procede
• "ok": false: la acción se bloquea. La "reason" del modelo se alimenta de vuelta a Claude para que pueda ajustar.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks basados en agentes

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Limitaciones y solución de problemas

​

Limitaciones

• Los hooks de comando se comunican solo a través de stdout, stderr y códigos de salida. No pueden activar comandos o llamadas a herramientas directamente. Los HTTP hooks se comunican a través del cuerpo de respuesta en su lugar.
• El tiempo de espera del hook es 10 minutos por defecto, configurable por hook con el campo timeout (en segundos).
• Los hooks PostToolUse no pueden deshacer acciones ya que la herramienta ya se ha ejecutado.
• Los hooks PermissionRequest no se activan en modo no interactivo (-p). Usa hooks PreToolUse para decisiones de permiso automatizadas.
• Los hooks Stop se activan cada vez que Claude termina de responder, no solo en la finalización de tareas. No se activan en interrupciones del usuario.

​

Hook no se activa

• Ejecuta /hooks y confirma que el hook aparece bajo el evento correcto
• Verifica que el patrón del matcher coincida exactamente con el nombre de la herramienta (los matchers distinguen mayúsculas de minúsculas)
• Verifica que estés activando el tipo de evento correcto (por ejemplo, PreToolUse se activa antes de la ejecución de la herramienta, PostToolUse se activa después)
• Si usas hooks PermissionRequest en modo no interactivo (-p), cambia a PreToolUse en su lugar

​

Error de hook en la salida

• Tu script salió con un código no cero inesperadamente. Pruébalo manualmente canalizando JSON de muestra:
  Reportar código incorrecto

  Copiar

  Preguntar a la IA

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Verifica el código de salida
  
• Si ves “command not found”, usa rutas absolutas o $CLAUDE_PROJECT_DIR para referenciar scripts
• Si ves “jq: command not found”, instala jq o usa Python/Node.js para análisis JSON
• Si el script no se ejecuta en absoluto, hazlo ejecutable: chmod +x ./my-hook.sh

​

/hooks no muestra hooks configurados

• Reinicia tu sesión o abre /hooks para recargar. Los hooks añadidos a través del menú /hooks tienen efecto inmediatamente, pero las ediciones manuales de archivos requieren una recarga.
• Verifica que tu JSON sea válido (las comas finales y comentarios no están permitidos)
• Confirma que el archivo de configuración está en la ubicación correcta: .claude/settings.json para hooks de proyecto, ~/.claude/settings.json para hooks globales

​

El hook Stop se ejecuta para siempre

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Permite que Claude se detenga
fi
# ... resto de tu lógica de hook

​

Falló la validación JSON

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# En ~/.zshrc o ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Técnicas de depuración

​

Aprende más

• Referencia de Hooks: esquemas de eventos completos, formato de salida JSON, hooks asincronos y hooks de herramientas MCP
• Consideraciones de seguridad: revisa antes de desplegar hooks en entornos compartidos o de producción
• Ejemplo de validador de comandos Bash: implementación de referencia completa