Cómo configurar los hooks de Claude Code para automatizar procesos con inteligencia artificial

Los hooks de Claude Code son disparadores deterministas que ejecutan tus comandos de terminal en momentos clave de su ciclo de trabajo. Úsalos para formatear archivos de forma automática tras editarlos, asegurar el cumplimiento de estándares, bloquear acciones riesgosas, cargar contexto al iniciar una sesión o recibir alertas cuando se requiera tu atención, todo sin depender de que el modelo lo "recuerde".

Por qué son importantes

Los prompts sirven para dar sugerencias; los hooks ofrecen certeza total. Se activan siempre que ocurre el evento previsto (por ejemplo, antes de usar una herramienta, tras editar un archivo o al abrir y cerrar una sesión). Esto garantiza formatos consistentes, cumplimiento de políticas y pautas de seguridad claras en todo tu equipo, sin necesidad de recordatorios manuales.

Qué puedes lograr con ellos

• Prevenir acciones riesgosas: Bloquea modificaciones en archivos .env, configuraciones de producción o la carpeta /.git (mediante PreToolUse con control de códigos de salida).

• Aplicar estándares al instante: Ejecuta herramientas como prettier, gofmt o tu linter tras cada edición o guardado (PostToolUse).

• Cargar contexto de forma automática: En SessionStart, incorpora tareas recientes o listas de verificación directamente a la conversación.

• Alertas directas y eficientes: Recibe avisos en tu escritorio cuando Claude necesite tu aprobación (Notification).

• Controlar prompts y herramientas: Aprueba, rechaza o solicita confirmación con el control de decisiones de PreToolUse y PermissionRequest.

Los hooks se configuran a nivel de usuario, proyecto o proyecto local, y también pueden aplicarse de forma centralizada mediante políticas empresariales. Claude Code

Eventos clave que realmente vas a utilizar

• PreToolUse / PermissionRequest / PostToolUse: Supervisan el uso de herramientas (Bash, Edit, Write, Read, Grep, WebFetch, Task y subagentes). Permiten autorizar, denegar o pedir confirmación, ajustar parámetros de entrada y retroalimentar tras la ejecución.

• UserPromptSubmit: Valida o enriquece tus instrucciones antes de que Claude las procese, permitiéndote sumar texto o contexto estructurado.

• SessionStart / SessionEnd: Prepara el entorno, carga la información necesaria al inicio y registra actividades o limpia procesos al terminar.

• Notification, Stop, SubagentStop, PreCompact: Gestionan alertas, controlan el cierre de respuestas y administran la compresión de contexto.

Configuración rápida y segura en 5 pasos

1. Abre el panel de configuración: Ejecuta /hooks dentro de Claude Code y selecciona un evento (por ejemplo, PreToolUse).

2. Define el criterio de activación (matcher): Usa Edit|Write para vigilar cambios en archivos o Bash para controlar comandos de terminal. El comodín * abarca todas las acciones.

3. Configura el hook: Elige type: "command" e introduce tu comando de shell (este recibe datos en formato JSON mediante stdin; puedes procesarlo con jq o Python).

4. Elige el nivel de almacenamiento:

   • ~/.claude/settings.json (personal, a nivel de usuario),

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

   • .claude/settings.local.json (exclusivo para uso local),

   • o mediante políticas empresariales (gestión centralizada).

5. Verifica los resultados: Revisa tu configuración con /hooks, ejecuta un comando de prueba y valida el registro de actividad.

Ejemplos listos para implementar

1) Registro de comandos de terminal (auditoría rápida)

Regístralo bajo PreToolUse con el filtro Bash:

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

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

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

Este script se activa antes de cada llamada de Bash y documenta la acción en un archivo de registro. Claude Code

2) Formato automático de TypeScript tras cada cambio

Configura PostToolUse con el filtro 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; }"
          }
        ]
      }
    ]
  }
}

{
  "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; }"
          }
        ]
      }
    ]
  }
}

{
  "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) Protección de archivos críticos (bloqueo con código de salida 2)

Configura PreToolUse con el filtro 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)\""
          }
        ]
      }
    ]
  }
}

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

{
  "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 2 detiene la operación de inmediato y envía el mensaje de stderr a Claude o al usuario, respetando las reglas de cada evento. Claude Code

4) Notificaciones en el escritorio cuando Claude requiera tu intervención

Hook para Notification:

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

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

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

Claude Code

5) Incorporación de contexto al iniciar sesión

El evento SessionStart te permite sumar lineamientos de trabajo o listas de control:

• Envía texto plano mediante stdout (con código de salida 0) para aportar información, o

• Genera una respuesta en formato JSON utilizando hookSpecificOutput.additionalContext.

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

• 0: Ejecución exitosa. La salida estándar (stdout) puede procesarse en formato JSON para un control granular (por ejemplo: "allow"|"deny"|"ask" en PreToolUse, "block" en PostToolUse o Stop, y el envío de additionalContext).

• 2: Error de bloqueo. Omite el JSON, muestra la salida de error (stderr) como mensaje explicativo y detiene la acción según las reglas establecidas (por ejemplo, frenando un PreToolUse).

• Cualquier otro código distinto de cero: No bloquea la ejecución y muestra el contenido de stderr únicamente en modo detallado (verbose).

Integración continua y flujos automatizados (ventaja adicional)

Combina los hooks con el modo headless para ejecutar Claude Code en pipelines de CI, scripts de compilación o procesos de pre-commit: claude -p "<prompt>" --output-format stream-json. Ten en cuenta que este modo opera por sesión, por lo que debes indicarlo en cada ejecución. Anthropic

Seguridad y mejores prácticas operativas

• Los hooks se ejecutan de manera automática con tus credenciales de usuario. Revisa cuidadosamente cada script y sigue las Prácticas recomendadas de seguridad: utiliza comillas en las variables, valida las entradas, evita rutas sensibles y recurre siempre a rutas absolutas.

• Los cambios de configuración no se aplican en caliente: Claude crea una copia de respaldo de los hooks al iniciar la sesión y solicita tu confirmación en /hooks antes de aceptar modificaciones, protegiéndote contra alteraciones no autorizadas.

• A nivel corporativo, es posible implementar políticas obligatorias en toda la organización para asegurar el estándar operativo.

Preguntas frecuentes

¿Qué son los hooks de Claude Code?
Son comandos de terminal personalizados que se ejecutan durante eventos específicos del ciclo de vida de Claude Code (como PreToolUse, PostToolUse o SessionStart) para hacer cumplir políticas, automatizar procesos o agregar contexto útil. Claude Code

¿Dónde se configuran?
En los archivos ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json o mediante las políticas centrales de tu empresa. El comando interactivo /hooks facilita toda la edición. Claude Code

¿Cómo se detiene una acción que implica riesgos?
Devuelve un código de salida 2 desde un hook de PreToolUse o PermissionRequest para rechazar la operación y mostrarle el motivo a Claude, o gestiona la decisión con las respuestas JSON "deny/ask/allow". Claude Code

¿Es posible cargar contexto de forma automática?
Sí. Los eventos UserPromptSubmit y SessionStart permiten incorporar texto o información estructurada a través de additionalContext directamente a la conversación antes de que Claude comience a trabajar. Claude Code

¿Son compatibles con plugins y herramientas MCP?
Totalmente. Los plugins pueden aportar sus propios hooks y puedes orientar reglas a herramientas MCP específicas usando filtros. Incluso es posible correr varios hooks en paralelo para un mismo evento. Claude Code