Los hooks de Claude Code son activadores determinísticos que ejecutan tus comandos del shell en puntos específicos del ciclo de vida de Claude Code. Úsalos para auto-formatear archivos después de ediciones, imponer reglas de proyecto, bloquear operaciones riesgosas, inyectar contexto al inicio de la sesión o notificarte cuando se necesiten entradas, sin depender del modelo para 'recordar'.

Por qué los hooks son importantes

Los prompts son excelentes para sugerencias; los hooks son garantías. Se activan cada vez que ocurre el evento coincidente (por ejemplo, antes de que una herramienta se ejecute, después de una edición, cuando una sesión comienza/termina). Eso significa formateo constante, aplicación de políticas y control de seguridad en todo tu equipo, sin necesidad de prompts adicionales.

Qué pueden hacer los hooks de Claude Code

• Anticipar acciones riesgosas: Bloquear escrituras en .env, configuración de producción, o /.git. (Usar PreToolUse con control de código de salida.)

• Aplicar estándares automáticamente: Ejecutar prettier, gofmt, o tu linter después de cada edición/escritura (PostToolUse).

• Inyectar contexto automáticamente: Al SessionStart, carga tickets recientes o una lista de verificación de codificación en la conversación.

• Notificaciones sin clics: Pop-ups de escritorio cuando Claude necesita aprobación (Notification).

• Regular prompts/herramientas: Aprobar, denegar o solicitar confirmación mediante control de decisiones PreToolUse / PermissionRequest.

Los hooks se configuran en las configuraciones de usuario, proyecto o proyecto local, y también se pueden aplicar mediante configuraciones de política empresarial. Claude Code

Los eventos de hook que realmente usarás

• PreToolUse / PermissionRequest / PostToolUse — envolver llamadas a herramientas (Bash, Edit, Write, Read, Grep, WebFetch, Task/subagents). Permitir, denegar o preguntar; modificar entradas; o dar feedback después.

• UserPromptSubmit — validar o enriquecer los prompts antes de que Claude los procese; puedes inyectar texto o contexto estructurado.

• SessionStart / SessionEnd — configurar el entorno, cargar contexto y limpiar/registrar al final.

• Notification, Stop, SubagentStop, PreCompact — alertas, control de fin de respuesta y hooks de compactación.

Una configuración rápida y segura (5 pasos)

1. Abre la interfaz de Hooks: ejecuta /hooks dentro de Claude Code. Elige un evento (por ejemplo, PreToolUse).

2. Agrega un emparejador: por ejemplo, Edit|Write para interceptar cambios de archivos, o Bash para gobernar comandos de shell. * coincide con todo.

3. Agrega el hook: elige type: "command" e ingresa tu comando del shell (recibe JSON en stdin; usa jq/Python para analizar).

4. Elige almacenamiento:

   • ~/.claude/settings.json (usuario),

   • .claude/settings.json (proyecto, confirma en el repositorio),

   • .claude/settings.local.json (solo local),

   • o política empresarial (aplicado centralmente).

5. Verifica y prueba: /hooks muestra tu configuración; ejecuta un comando rápido y verifica tu registro/salida.

Ejemplos listos para copiar

1) Registrar cada comando Bash (auditoría rápida)

Regístralo en PreToolUse con emparejador Bash:

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

Esto se ejecuta antes de cada llamada a la herramienta Bash y añade una línea a un archivo de registro. Claude Code

2) Auto-formatear TypeScript después de ediciones/escrituras

PostToolUse con emparejador Edit|Write:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|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; }"
          }
        ]
      }
    ]
  }
}

Claude Code

3) Proteger archivos sensibles (bloquear con código de salida 2)

PreToolUse con emparejador Edit|Write:

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

El código de salida 2 bloquea la acción y muestra tu stderr a Claude (y/o al usuario) según las reglas del evento. Claude Code

4) Recibir alertas de escritorio cuando Claude te necesita

Hook de Notification:

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

Claude Code

5) Precargar contexto al inicio de la sesión

SessionStart puede inyectar orientación adicional o una lista de verificación:

• Escribir texto plano en stdout (código de salida 0) para agregar contexto, o

• Devolver JSON con hookSpecificOutput.additionalContext.

Control avanzado: códigos de salida y decisiones en JSON

• 0: éxito. stdout puede ser analizado como JSON para control estructurado (por ejemplo, "allow"|"deny"|"ask" en PreToolUse; "block" en PostToolUse/Stop; añadir additionalContext).

• 2: error bloqueante. Omite JSON; utiliza stderr como el mensaje y bloquea según las reglas del evento (por ejemplo, denegar un PreToolUse).

• Otro no cero: no bloqueante; muestra stderr en modo detallado.

Uso en CI y no interactivo (bonus)

Combina hooks con modo sin cabecera para ejecutar Claude Code en CI, scripts de construcción o trabajos de estilo pre-commit: claude -p "<prompt>" --output-format stream-json. El modo sin cabecera es por sesión, así que actívalo en cada ejecución. Anthropic

Esenciales de seguridad y gobernanza

• Los hooks se ejecutan automáticamente con las credenciales de tu usuario; revisa cuidadosamente los scripts y sigue las Mejores Prácticas de Seguridad (citar variables, validar entradas, evitar rutas sensibles, usar rutas absolutas).

• Las ediciones de configuración no se aplican de inmediato: Claude toma una instantánea de los hooks al inicio de la sesión y te pide revisar cambios en /hooks, una protección contra modificaciones maliciosas.

• La empresa puede aplicar hooks de política en toda la organización para asegurar la consistencia.

Preguntas frecuentes

¿Qué son los hooks de Claude Code?
Comandos shell definidos por el usuario que se ejecutan en eventos específicos del ciclo de vida en Claude Code (por ejemplo, PreToolUse, PostToolUse, SessionStart) para imponer reglas, automatizar tareas o agregar contexto. Claude Code

¿Dónde los configuro?
En ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, o mediante configuraciones de política empresarial; /hooks ofrece un editor interactivo. Claude Code

¿Cómo bloqueo acciones peligrosas?
Devuelve el código de salida 2 desde un hook de PreToolUse/PermissionRequest para denegar la acción y enviar tu mensaje de error a Claude; o usa control de decisiones JSON para "denegar/preguntar/permitir". Claude Code

¿Puedo agregar contexto automáticamente?
Sí—UserPromptSubmit y SessionStart pueden inyectar texto o additionalContext estructurado en la conversación antes de que Claude proceda. Claude Code

¿Funcionan los hooks con plugins/herramientas MCP?
Sí—los plugins pueden contribuir hooks, y puedes dirigirte a herramientas MCP via emparejadores; múltiples hooks pueden ejecutarse en paralelo para un solo evento. Claude Code