Hooks de Claude Code: eventos, ejemplos y cómo funcionan

Eventos de hooks de Claude Code

La referencia enumera más de treinta eventos. Estos son los que usa la mayoría de los hooks; un matcher limita un hook a ciertas herramientas, archivos u orígenes.

Dónde poner los hooks

Ejemplos de hooks de Claude Code, paso a paso

Añade cada bloque bajo la clave hooks de un archivo de configuración; si el archivo ya tiene un objeto hooks, añade el evento como una clave hermana en lugar de reemplazarlo. Ejecuta /hooks para confirmar que Claude Code lo cargó. También puedes pedirle a Claude que escriba el hook por ti.

1. Recibe una notificación de escritorio cuando Claude te necesite

   Un hook Notification en ~/.claude/settings.json. Este usa osascript en macOS; usa notify-send en Linux o PowerShell en Windows.

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

2. Formatea automáticamente cada archivo que edite Claude

   Un hook PostToolUse con el matcher Edit|Write lee la ruta editada del JSON recibido por stdin con jq y ejecuta Prettier sobre ella. Ponlo en .claude/settings.json para que lo comparta todo el equipo.

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

3. Bloquea un comando peligroso

   Un hook PreToolUse sobre Bash ejecuta este script. El código de salida 2 bloquea la llamada, y lo que escribas en stderr se convierte en el feedback para Claude, que así puede cambiar de rumbo. Salir con 0 significa que no hay decisión, así que se siguen aplicando los permisos normales.

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh, se ejecuta como hook PreToolUse sobre 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  # se convierte en el feedback para Claude
     exit 2                                               # 2 = bloquear la acción
   fi
   
   exit 0  # sin decisión: se aplica el flujo normal de permisos

4. Mantén a Claude trabajando hasta terminar la tarea

   Un hook Stop de tipo prompt le pregunta a un modelo si todo está terminado. Si responde ok: false, Claude sigue trabajando con el reason como su siguiente instrucción. Es el ejemplo clásico de hook Stop.

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

Fuente: documentación de Claude Code, Automate actions with hooks

Cómo deciden los hooks lo que pasa

• Entrada: cada hook recibe el evento como JSON por stdin, por ejemplo el nombre de la herramienta y tool_input, el ID de sesión y cwd.
• Salida 0: sin objeciones. En algunos eventos, como SessionStart y UserPromptSubmit, el stdout en texto plano se añade al contexto de Claude.
• Salida 2: bloquear, cuando el evento lo permite. El stderr vuelve a Claude o a ti, según el evento.
• JSON por stdout: control más fino, como hookSpecificOutput con una decisión de permisos, updatedInput para reescribir la entrada de una herramienta, o additionalContext.
• Otros códigos de salida: normalmente un error que no bloquea, salvo que el hook defina onFailure: "block".
• Los hooks que coinciden con un mismo evento se ejecutan en paralelo.

Hooks de tipo command, prompt, agent y HTTP

Hooks vs. skills vs. CLAUDE.md, y otros detalles a tener en cuenta

• CLAUDE.md y las skills son instrucciones que Claude suele seguir; los hooks se ejecutan siempre. Pon en un hook todo lo que nunca deba saltarse.
• PostToolUse no puede deshacer una acción que ya se ejecutó; usa PreToolUse para impedirla.
• Stop se dispara cada vez que Claude termina una respuesta, no solo al final de una tarea, y no cuando el usuario la interrumpe.
• Los hooks no pueden ejecutar slash commands ni llamar a herramientas por sí mismos; solo responden mediante códigos de salida, stdout, stderr o JSON.
• "disableAllHooks": true desactiva los hooks; los hooks administrados se siguen ejecutando salvo que la configuración administrada también los desactive.
• Los hooks son locales a tu configuración de Claude Code. Las comprobaciones a nivel de organización en todos los productos de Claude son otra función: los inference hooks de Claude.
• Un hook PreToolUse que filtra la salida de los tests es también una de las mejores formas de reducir el uso de tokens.

Los hooks mantienen a Claude Code a raya. Crewmark lo mantiene trabajando.

Los hooks son lo que hace seguro a un agente sin supervisión: el formateo, los tests y las protecciones se ejecutan siempre. Crewmark convierte una sesión de Claude Code, Codex, DeepSeek Harness u OpenCode en un empleado de IA con un rol, un objetivo y un horario, y la despierta con un heartbeat para que tome la siguiente issue de un tablero, con los hooks de tu proyecto en su sitio.

1. Haz commit de tus hooks

   Los hooks de .claude/settings.json se cargan en la sesión del empleado igual que en la tuya, así que sus ediciones se formatean y sus comandos arriesgados se bloquean.

2. Deja que el heartbeat inicie el trabajo

   Durante su horario, el empleado se despierta cada 15, 30 o 60 minutos en la misma conversación; consulta cómo hacer que Claude Code sea proactivo.

3. Responde solo a lo que te necesita

   Comenta en sus issues y te escribe cuando necesita una decisión. Lee qué es un empleado de IA.

Preguntas frecuentes sobre los hooks de Claude Code