Resumen rápido: Los hooks de Claude Code son scripts de automatización que se ejecutan en puntos específicos del ciclo de vida durante las sesiones de codificación de IA, lo que permite a los desarrolladores ejecutar comandos personalizados, validar acciones, formatear código, enviar notificaciones y aplicar reglas del proyecto. Estos hooks se integran con el flujo de trabajo de Claude a través de eventos como SessionStart, PreToolUse y PostToolUse, admitiendo patrones de ejecución basados en comandos, basados en HTTP y basados en prompts con tiempos de espera configurables y comportamiento de códigos de salida.
El sistema de hooks de Claude Code transforma el asistente de codificación de IA de una herramienta útil a un entorno de desarrollo completamente automatizado. La mayoría de los desarrolladores no se dan cuenta del nivel de control disponible a través de los hooks.
Sin embargo, esto es lo importante: los hooks no se tratan solo de ejecutar scripts después de editar archivos. Proporcionan puntos de intercepción a lo largo de todo el proceso de toma de decisiones de Claude. Antes de que ejecute un comando. Después de que una llamada a una herramienta falle. Cuando necesita permiso. Incluso antes de procesar los prompts del usuario.
Esta guía cubre todo lo que proporciona la documentación oficial, además de patrones prácticos que las discusiones de la comunidad revelan que realmente funcionan en entornos de producción.
Lo que realmente hacen los hooks de Claude Code
Según la documentación oficial de Claude Code, los hooks son comandos shell definidos por el usuario, puntos finales HTTP o inyecciones de prompts que se ejecutan en puntos específicos del ciclo de vida de Claude Code. Reciben entrada JSON estructurada a través de stdin y controlan el flujo de trabajo a través de códigos de salida o respuestas HTTP.
La automatización va más allá de lo que sugieren la mayoría de las guías. Los hooks pueden bloquear completamente la ejecución de herramientas, inyectar contexto adicional en el razonamiento de Claude, activar servicios externos y aplicar reglas de validación que Claude debe respetar.
Existen tres tipos de hooks principales:
- Hooks de comandos: Scripts de shell que se comunican a través de stdout, stderr y códigos de salida
- Hooks HTTP: Puntos finales remotos que reciben solicitudes POST y devuelven respuestas JSON
- Hooks de prompts: Instrucciones dinámicas inyectadas en el contexto de Claude en eventos específicos
Cada tipo sirve a diferentes patrones de automatización. Los hooks de comandos manejan la validación y el formato local. Los hooks HTTP se integran con servicios y bases de datos externas. Los hooks de prompts modifican el comportamiento de Claude sin procesos externos.
Ciclo de vida de los hooks y sistema de eventos
La documentación oficial define múltiples eventos de hooks (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification y otros) que se activan durante el flujo de ejecución de Claude Code. Comprender cuándo se activa cada uno determina qué automatización es posible.
| Evento | Cuándo se activa | Puede bloquear |
|---|---|---|
| SessionStart | Cuando una sesión comienza o se reanuda | No |
| UserPromptSubmit | Cuando envías un prompt, antes de que Claude lo procese | Sí |
| PreToolUse | Antes de que se ejecute una llamada a una herramienta | Sí |
| PermissionRequest | Cuando aparece un diálogo de permiso | Sí |
| PostToolUse | Después de que una llamada a una herramienta tiene éxito | No |
| PostToolUseFailure | Después de que una llamada a una herramienta falla | No |
| Notification | Cuando Claude Code envía una notificación | No |
| SubmitMessage | Cuando Claude envía un mensaje al usuario | No |
| ContextCompaction | Cuando la ventana de contexto se acerca a los límites | No |
La capacidad de bloqueo es lo más importante. Los hooks PreToolUse pueden prevenir operaciones peligrosas antes de que se ejecuten. El código de salida 1 bloquea la acción. El código de salida 0 la permite. El código de salida 2 hace que Claude reconsidere.
Pero espera. Los hooks PostToolUse no pueden deshacer acciones ya que la herramienta ya se ejecutó. Esta limitación da forma a cómo se estructura la lógica de validación. Las comprobaciones críticas pertenecen a PreToolUse. La limpieza y el formato pertenecen a PostToolUse.
Explora las ventajas de las herramientas de IA al configurar Claude Code
Si estás trabajando con hooks de Claude Code, es posible que también estés eligiendo otras herramientas de IA en tu flujo de trabajo. Get AI Perks recopila créditos de inicio y descuentos de software para herramientas de IA y nube en un solo lugar. La plataforma incluye más de 200 ofertas, con condiciones de ventaja y guía de reclamo para cada una.
¿Buscas ventajas de Claude u otras herramientas de IA?
Consulta Get AI Perks para:
- explorar ofertas de Claude y otras herramientas de IA
- comparar las condiciones de las ventajas antes de solicitarlas
- encontrar descuentos de inicio en toda tu pila de herramientas
👉 Visita Get AI Perks para explorar las ventajas actuales de software de IA.
Configuración y estructura de archivos
Los hooks se definen en el archivo .claude/settings.json dentro de un proyecto. El esquema de configuración admite hooks globales y correspondencias específicas de herramientas que filtran cuándo se ejecutan los hooks.
Estructura básica de hook de comando:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
La variable ${file} se expande a la ruta de archivo real de la entrada de la herramienta. Según la documentación oficial, los hooks admiten estas expansiones de variables en los campos de comando y args.
Jerarquía de ubicación de los hooks
Claude Code verifica varias ubicaciones para las definiciones de hooks, con un orden de precedencia claro:
- A nivel de proyecto: .claude/settings.json en el espacio de trabajo actual
- A nivel de usuario: ~/.claude/settings.json para todas las sesiones
- Proporcionado por el plugin: Hooks incluidos con los plugins instalados
Los hooks de proyecto anulan los hooks de usuario para el mismo evento. Esto permite reglas de formato específicas del proyecto mientras se mantienen manejadores de notificación globales.
Patrones de correspondencia para ejecución selectiva
El sistema de correspondencia filtra los hooks a herramientas o condiciones específicas. Sin correspondencias, los hooks se activan para cada ocurrencia de su evento.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
El campo pathPattern acepta sintaxis glob. El campo toolName coincide con las herramientas integradas de Claude como edit_file, execute_command, read_file y create_directory.
Las discusiones de la comunidad revelan que las combinaciones de correspondencia funcionan con lógica Y. Todos los correspondencias especificados deben coincidir para que el hook se ejecute.
Hooks de comandos: Integración de scripts de shell
Los hooks de comandos ejecutan comandos o scripts de shell con entrada JSON estructurada. Representan el tipo de hook más común para la automatización local.
La documentación oficial especifica que los hooks de comandos reciben JSON a través de stdin con esta estructura:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Los scripts analizan esta entrada para tomar decisiones. Un hook de validación en Python podría verse así:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
El código de salida 0 permite la operación. El código de salida 1 la bloquea y muestra el mensaje de stderr a Claude. El código de salida 2 activa un comportamiento especial dependiendo del evento.
Comportamiento del código de salida 2
Según la documentación oficial de referencia de hooks, el código de salida 2 tiene un significado específico del evento (PreToolUse: bloquea y solicita reconsideración; UserPromptSubmit: proporciona contexto sin bloquear; PermissionRequest: bloquea el permiso):
- PreToolUse: Bloquea la herramienta y solicita a Claude que reconsidere con el mensaje de stderr como contexto
- UserPromptSubmit: Proporciona la salida de stderr como contexto adicional sin bloquear
- PermissionRequest: Bloquea la concesión del permiso
Esto crea un punto intermedio entre el bloqueo estricto y la concesión. Claude recibe comentarios sobre por qué la acción podría ser problemática y puede ajustar su enfoque.
Hooks de comandos asíncronos
La bandera async: true ejecuta los hooks en segundo plano sin bloquear el flujo de trabajo de Claude. Esto es importante para operaciones lentas como notificaciones de implementación o recopilación de métricas.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Cuando se activa un hook asíncrono, Claude Code inicia el proceso y continúa de inmediato. El campo timeout establece el tiempo máximo de ejecución en segundos. Si no se especifica, los hooks asíncronos utilizan un tiempo de espera predeterminado de 10 minutos.
En serio: los hooks asíncronos no pueden bloquear operaciones, ya que se ejecutan después de que Claude procede. Funcionan para registro, notificaciones y limpieza, no para validación.
Hooks HTTP: Integración de servicios externos
Los hooks HTTP envían cargas útiles JSON a puntos finales remotos y analizan las respuestas para controlar las decisiones. Permiten la integración con servicios de validación, bases de datos y herramientas de terceros.
Configuración básica de hook HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
La estructura de la carga útil coincide con la entrada del hook de comando, pero llega como cuerpo de la solicitud POST HTTP. La respuesta determina la próxima acción de Claude.
Manejo de respuestas HTTP
Según la documentación oficial, los hooks HTTP interpretan las respuestas según el código de estado y el contenido del cuerpo:
| Código de estado | Efecto | Fuente del mensaje |
|---|---|---|
| 200 | Permitir operación | Cuerpo de la respuesta (opcional) |
| 400 | Bloquear operación | Cuerpo de la respuesta mostrado a Claude |
| 500 | Error del hook, permitir operación | Registrado pero no mostrado a Claude |
| Otro | Permitir operación | El fallo del hook no bloquea el flujo de trabajo |
El cuerpo de la respuesta puede incluir un campo de mensaje que Claude ve como contexto. Esto permite a los servicios de validación explicar por qué se bloqueó una operación.
Interpolación de variables de entorno
Los hooks HTTP admiten la sintaxis ${VAR} en url, headers y otros campos de cadena. Las variables se expanden desde el entorno donde se ejecuta Claude Code.
Según la documentación oficial de MCP, la expansión de variables de entorno incluye una sintaxis de fallback predeterminada: ${VAR:-default} se expande a VAR si está configurada, de lo contrario, utiliza el valor predeterminado.
Restricción de seguridad: Según el problema de GitHub #28044, los hooks HTTP solo pueden acceder a variables de entorno explícitamente listadas en el campo de configuración allowedEnvVars. Esto evita la exposición accidental de credenciales.
Hooks de prompts: Inyección de contexto
Los hooks de prompts inyectan instrucciones dinámicas en el contexto de Claude en eventos específicos. Modifican el comportamiento sin procesos externos o llamadas a API.
| { “event”: “SessionStart”, “prompt”: “Estás trabajando en un proyecto TypeScript. Usa siempre comprobaciones estrictas de nulos y prefiere async/await sobre las promesas.” } |
El texto inyectado se convierte en parte de las instrucciones del sistema de Claude para esa sesión. Los hooks de prompts también pueden usar variables de plantilla que se expanden según los datos del evento.
Generación dinámica de prompts
Según la documentación oficial, los hooks de prompts admiten campos de comando que generan prompts dinámicos:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
El comando recibe la entrada JSON estándar a través de stdin y produce el texto del prompt a stdout. Esto permite la generación de instrucciones conscientes del contexto basada en el estado del proyecto.
Hooks basados en agentes
Los hooks de agentes especifican un subagente que maneja el evento en lugar de la inyección directa de prompts. El subagente recibe contexto sobre el evento y puede realizar razonamientos de varios pasos.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Una llamada a la herramienta falló. Analiza el error y sugiere correcciones.” } |
El subagente nombrado debe definirse en la configuración del proyecto. Los hooks de agentes permiten una lógica de decisión compleja que la inyección de prompts simple no puede proporcionar.
Patrones prácticos de hooks
Las discusiones de la comunidad y los ejemplos oficiales revelan patrones de automatización específicos que funcionan de manera confiable en producción.
Formatear código automáticamente después de las ediciones
El patrón más común formatea el código automáticamente después de que Claude edita archivos:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
La variable ${toolInput.path} se expande a la ruta del archivo editado. PostToolUse asegura que el formato ocurra después de ediciones exitosas pero no bloquea el flujo de trabajo de Claude.
Bloquear modificaciones de archivos protegidos
Los hooks PreToolUse aplican reglas de protección de archivos:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
El script valida la ruta de destino contra patrones protegidos y sale con el código 1 para bloquear ediciones prohibidas.
Recibe notificaciones cuando Claude necesita entrada
Según la guía de flujo de trabajo oficial, los hooks de Notificación pueden activar alertas de escritorio o enviar mensajes a servicios externos:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Esto se activa cada vez que Claude Code envía una notificación, incluso cuando espera entrada del usuario o después de completar una tarea.
Reinyectar contexto después de la compactación
Los hooks de ContextCompaction restauran el contexto importante cuando la ventana de conversación se llena:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
La salida del comando se inyecta nuevamente en el contexto de Claude después de que la compactación elimina mensajes anteriores. Esto evita la pérdida de instrucciones críticas específicas del proyecto.
Auditar cambios de configuración
Rastrea cuándo Claude modifica los archivos de configuración:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
La ejecución asíncrona evita bloquear Claude mientras se completan las operaciones de git. Esto crea un rastro de auditoría de los cambios de configuración sin staging manual.
Salida JSON y control de decisiones
Los hooks de comandos pueden generar JSON estructurado para proporcionar comentarios detallados más allá de los simples códigos de salida. Según la referencia oficial, la salida JSON permite respuestas de varios campos que Claude interpreta para la toma de decisiones.
| { “allowed”: false, “message”: “Este archivo está protegido por la política del equipo”, “suggestion”: “Crea un nuevo archivo en src/features/ en su lugar” } |
El campo allowed controla si la operación procede. El mensaje aparece para Claude como contexto. El campo suggestion proporciona enfoques alternativos.
Para que los hooks produzcan JSON, deben:
- Escribir JSON válido a stdout
- Salir con el código 0 (para permitido) o 1 (para bloqueado)
- Incluir como mínimo el campo booleano allowed
Claude Code analiza el JSON y lo utiliza para mejorar el bucle de retroalimentación. Los códigos de salida aún determinan la decisión principal, pero el JSON proporciona un contexto más enriquecido.
Referencia de campos de entrada de hooks
Todos los hooks reciben un objeto JSON a través de stdin con campos comunes y datos específicos del evento. Comprender el esquema completo permite una lógica de hook más sofisticada.
Campos de entrada comunes
Cada hook recibe estos campos base:
- event: El nombre del evento del hook (p. ej., “PreToolUse”)
- sessionId: Identificador único para la sesión actual de Claude
- turnId: Identificador del turno de conversación actual
- timestamp: Marca de tiempo ISO 8601 cuando se activó el evento
Campos de eventos de herramientas
Los eventos PreToolUse, PostToolUse y PostToolUseFailure incluyen:
- toolName: Nombre de la herramienta que se está invocando (edit_file, execute_command, etc.)
- toolInput: Objeto que contiene los parámetros de entrada de la herramienta
- toolResponse: Datos de salida de la herramienta (solo PostToolUse)
- error: Detalles del error, incluyendo mensaje y código (solo PostToolUseFailure)
La estructura de toolInput varía según la herramienta. Para edit_file contiene path y content. Para execute_command contiene command y args.
Campos de eventos de permiso
Los eventos PermissionRequest incluyen:
- permissionType: Tipo de permiso solicitado (file_write, command_execute, etc.)
- requestedAction: Acción específica que requiere permiso
- resourcePath: Ruta de archivo o identificador de recurso afectado
Hooks de herramientas MCP
Según la referencia oficial de hooks, los hooks pueden coincidir con herramientas del Protocolo de Contexto del Modelo (MCP) utilizando el campo del matcher mcpTool. Esto permite la ejecución de hooks cuando Claude utiliza herramientas externas proporcionadas por servidores MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
El valor mcpTool coincide con el nombre de la herramienta en el formato nombre-servidor/nombre-herramienta. Esto permite la lógica de validación para consultas de bases de datos, llamadas a API u otras operaciones externas.
Las solicitudes de características en GitHub indican un creciente interés en una integración más profunda de MCP, incluidos hooks que pueden inspeccionar notificaciones de servidores MCP y responder a eventos externos.
Consideraciones de seguridad
Los hooks se ejecutan con los mismos permisos que Claude Code. Esto crea implicaciones de seguridad para entornos multiusuario y configuraciones compartidas.
Sandbox de ejecución de comandos
Según el problema de GitHub #28044, los hooks HTTP se enrutan a través de un proxy sandbox que restringe el acceso a la red y filtra variables de entorno. Los hooks de comandos no tienen tales restricciones: se ejecutan con acceso completo al shell.
La documentación recomienda estas prácticas:
- Nunca almacenes credenciales en comandos de hooks
- Utiliza variables de entorno para datos sensibles
- Valida toda la entrada de las expansiones ${…}
- Implementa límites de tiempo de espera para servicios externos
- Usa hooks asíncronos para operaciones no críticas para evitar bloqueos en fallos
Aislamiento de la ejecución de hooks
Los hooks a nivel de usuario en ~/.claude/settings.json se aplican a todos los proyectos. Esto crea riesgos al trabajar en diferentes límites de confianza. Los hooks a nivel de proyecto anulan los hooks de usuario pero no pueden deshabilitarlos por completo.
El menú /hooks en Claude Code muestra todos los hooks activos para la sesión actual. Revisar esta lista antes de trabajar en proyectos sensibles ayuda a identificar posibles preocupaciones de seguridad.
Depuración y solución de problemas
Los fallos de los hooks no siempre se muestran claramente en la conversación de Claude. La documentación oficial proporciona varios enfoques de depuración.
Registros de ejecución de hooks
Claude Code registra la ejecución de hooks en la salida de depuración de la sesión. Según la guía de solución de problemas, habilitar el registro de depuración revela:
- Qué hooks coincidieron para cada evento
- La entrada JSON enviada a cada hook
- Salida stdout y stderr de los procesos de hook
- Códigos de salida y tiempo de ejecución
- Códigos y cuerpos de respuesta HTTP para hooks HTTP
Habilita el registro de depuración estableciendo CLAUDE_DEBUG=1 en el entorno antes de iniciar Claude Code.
Probar hooks de forma independiente
Los hooks de comandos se pueden probar fuera de Claude Code construyendo manualmente la entrada JSON:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Esto valida la lógica del hook sin activar operaciones reales de Claude. El código de salida y la salida stdout/stderr deben coincidir con el comportamiento esperado.
Fallos comunes de hooks
Las discusiones de la comunidad identifican estos problemas frecuentes:
- Errores de tiempo de espera: El tiempo de espera predeterminado de 10 minutos es demasiado corto para operaciones lentas; auméntalo con el campo timeout
- Fallos de expansión de ruta: Variables como ${file} no definidas para eventos que no incluyen contexto de archivo
- Errores de permiso: Los scripts de hooks carecen de permisos de ejecución; ejecuta chmod +x script.sh
- Errores de análisis JSON: Salida JSON mal formada de los hooks; valida con jq antes de devolverla
- Indisponibilidad de variables de entorno: Las variables no se propagan al proceso del hook; comprueba el entorno de Claude Code
Implicaciones de rendimiento de los hooks
Los hooks síncronos bloquean el flujo de trabajo de Claude hasta su finalización. El tiempo de espera predeterminado de 10 minutos evita bloqueos indefinidos, pero incluso los retrasos cortos se acumulan en múltiples operaciones.
Los profesionales informan que los hooks de validación simples tienen un impacto de rendimiento insignificante. Los hooks de formato de archivos causan un impacto de rendimiento notable pero aceptable. Las llamadas a API externas pueden crear fricciones en el flujo de trabajo. Las operaciones de cálculo intensivo se benefician de la ejecución asíncrona.
Lotes de hooks
Múltiples hooks pueden coincidir con el mismo evento. Según la documentación de referencia, los hooks se ejecutan secuencialmente en el orden de definición. Si algún hook bloquea la operación, los hooks restantes no se ejecutan.
Esto es importante para el rendimiento. Cinco hooks síncronos de 200 ms cada uno suman un segundo por evento. Combinar validaciones relacionadas en un solo hook reduce la sobrecarga.
Patrones avanzados
Más allá de la automatización básica, los hooks permiten una personalización sofisticada del flujo de trabajo.
Cadenas de hooks con estado
Los hooks pueden mantener el estado entre ejecuciones utilizando archivos o bases de datos. Un hook PostToolUse podría registrar operaciones exitosas que un hook PreToolUse valida posteriormente:
| #!/bin/bash # Registra las ediciones exitosas echo “${toolInput.path}” >> .claude/edit-history.txt |
Un hook PreToolUse complementario podría verificar este historial para evitar operaciones redundantes o aplicar restricciones de orden.
Activación condicional de hooks
Las variables de entorno controlan el comportamiento de los hooks en tiempo de ejecución. Establecer CLAUDE_SKIP_HOOKS=1 deshabilita los hooks para situaciones de emergencia.
Los propios hooks pueden verificar las banderas de entorno:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Aplica validación estricta exit 1 fi exit 0 |
Esto permite un comportamiento de modo de desarrollo frente a modo de producción sin cambios en la configuración.
Validación en varias etapas
Los hooks PreToolUse pueden implementar validación multinivel donde el código de salida 2 permite a Claude continuar con advertencias:
- Fallos graves (código 1): Bloquean operaciones peligrosas
- Advertencias leves (código 2): Alertan a Claude para que reconsidere
- Pasa con contexto (código 0 + JSON): Proporciona información adicional
Esto crea un espectro de validación más matizado que el binario permitir/denegar.
Integración con CI/CD
Según la documentación oficial de integración de plataformas, Claude Code se ejecuta en entornos CI/CD para revisión automática de código y triaje de problemas. Los hooks extienden esta automatización.
Los flujos de trabajo de GitHub Actions pueden definir hooks que aplican políticas de equipo durante sesiones automatizadas:
| – name: Ejecutar Claude Code con hooks estrictos env: STRICT_MODE: 1 run: | claude “Revisa esta PR y sugiere mejoras” |
La bandera STRICT_MODE activa la lógica de validación condicional en los scripts de hook. Esto garantiza que las sesiones automatizadas sigan reglas más rígidas que el desarrollo interactivo.
Generación de rastro de auditoría
Los hooks PostToolUse en entornos de CI crean registros de auditoría detallados de todas las operaciones de Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
El registro en segundo plano no afecta el rendimiento, pero proporciona un historial completo de operaciones para cumplimiento y depuración.
El menú /hooks
Claude Code proporciona un comando /hooks que muestra todos los hooks activos para la sesión actual. Según la documentación oficial, este menú muestra:
- Tipo de evento del hook
- Patrones de correspondencia
- Comando o punto final de URL
- Si el hook se ejecuta de forma asíncrona
- Fuente de configuración (proyecto, usuario o plugin)
Seleccionar un hook muestra su configuración completa y permite deshabilitarlo temporalmente para la sesión actual.
Deshabilitar o eliminar hooks
Los hooks se pueden deshabilitar sin eliminar la configuración agregando “enabled”: false a la definición del hook. Esto conserva la configuración mientras se evita la ejecución.
Para eliminar permanentemente un hook, borra su entrada del archivo settings.json apropiado. Los cambios surten efecto en el próximo reinicio de sesión o al ejecutar /reload.
Hooks en Skills y Agentes
Según la documentación oficial, los hooks definidos dentro de las configuraciones de skills o subagentes se aplican solo cuando se ejecuta esa skill o agente. Esto permite automatización especializada para flujos de trabajo específicos.
Un subagente de depuración podría incluir hooks que registran todas las llamadas a herramientas:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Estos hooks solo se activan durante las sesiones del agente depurador, no durante la operación normal de Claude Code.
Referenciar scripts por ruta
Los comandos de hooks admiten rutas relativas y absolutas. Las rutas relativas se resuelven desde la raíz del proyecto donde se ejecuta Claude Code.
Mejores prácticas de las discusiones de la comunidad:
- Almacenar scripts de hooks en el directorio .claude/hooks/
- Usar nombres descriptivos: validate-typescript.sh no hook1.sh
- Hacer que los scripts sean ejecutables: chmod +x .claude/hooks/*.sh
- Incluir línea shebang: #!/usr/bin/env bash o #!/usr/bin/env python3
- Agregar manejo de errores con set -e en scripts bash
Capacidades futuras de los hooks
Las solicitudes de características en GitHub revelan mejoras planificadas y solicitadas para los hooks:
- Hooks de scripts en línea: Definir la lógica del hook directamente en settings.json sin archivos externos
- Integración de herramientas MCP: Invocar herramientas de servidor MCP desde hooks en lugar de comandos de shell
- Colaboración multiagente: Hooks que coordinan entre instancias de Claude en diferentes máquinas
- Tipos mejorados: Definiciones de tipos de TypeScript para esquemas de entrada/salida de hooks
Según el problema de GitHub #4274, la solicitud de tipos de hooks integrados (herramienta MCP, script en línea, llamada API) tiene como objetivo simplificar la configuración y mejorar la experiencia del desarrollador.
Preguntas frecuentes
¿Pueden los hooks evitar que Claude ejecute comandos peligrosos?
Sí. Los hooks PreToolUse pueden bloquear cualquier ejecución de herramienta saliendo con el código 1. Esto incluye ediciones de archivos, ejecución de comandos y llamadas a herramientas MCP. El hook recibe la entrada completa de la herramienta y puede validarla contra cualquier criterio antes de permitir la operación.
¿Cómo depuro un hook que no funciona?
Habilita el registro de depuración con CLAUDE_DEBUG=1 antes de iniciar Claude Code. Consulta los registros de la sesión para obtener detalles de ejecución de hooks, incluidos qué hooks coincidieron, la entrada JSON enviada, la salida stdout/stderr y los códigos de salida. Prueba los hooks de forma independiente enviando JSON de muestra al script del hook.
¿Funcionan los hooks con todas las plataformas de Claude Code?
Los hooks funcionan en la CLI, la aplicación de escritorio y la extensión VS Code. Según la documentación oficial, los hooks se ejecutan dondequiera que Claude Code se ejecute con acceso al sistema de archivos. Claude basado en navegador y las aplicaciones móviles no admiten hooks debido a restricciones de sandboxing.
¿Pueden los hooks modificar las respuestas o el comportamiento de Claude?
Los hooks de prompts inyectan instrucciones que influyen en el comportamiento de Claude. Los hooks de agentes delegan el manejo de eventos a subagentes especializados. Sin embargo, los hooks no pueden modificar directamente el texto generado o el proceso de razonamiento de Claude; funcionan proporcionando contexto y bloqueando operaciones.
¿Cuál es la diferencia entre hooks asíncronos y síncronos?
Los hooks síncronos bloquean el flujo de trabajo de Claude hasta su finalización o tiempo de espera. Los hooks asíncronos se ejecutan en segundo plano sin bloquear. Los hooks síncronos pueden prevenir operaciones a través de códigos de salida. Los hooks asíncronos no pueden bloquear, ya que Claude continúa antes de que el hook se complete. Utiliza asíncronos para registro y notificaciones, síncronos para validación.
¿Cómo comparto hooks en un equipo?
Confirma el archivo .claude/settings.json en el control de versiones. Los hooks a nivel de proyecto se aplican a todos los miembros del equipo que clonen el repositorio. Para políticas en toda la organización, los equipos pueden mantener un archivo de configuración compartido a nivel de usuario que los miembros copian a ~/.claude/settings.json.
¿Pueden los hooks HTTP llamar a APIs internas detrás de firewalls?
Sí, si Claude Code se ejecuta en un entorno con acceso a la red a esas APIs. Los hooks HTTP realizan solicitudes POST estándar desde la máquina que ejecuta Claude Code. Los firewalls corporativos y las VPN se aplican normalmente. El proxy sandbox mencionado en la documentación controla la exposición de variables de entorno, no el enrutamiento de red.
¿Aumentan los hooks el uso de tokens de Claude Code?
Los hooks de prompts inyectan texto en el contexto de Claude, lo que consume tokens. Los hooks de comandos y HTTP no afectan directamente el uso de tokens, pero su salida (mensajes de error, sugerencias) se convierte en parte del contexto de la conversación. El código de salida 2 con mensajes explicativos agrega más contexto que el código de salida 1 con bloqueo simple.
Conclusión
Los hooks de Claude Code transforman el asistente de IA de una herramienta potente a una plataforma de desarrollo completamente automatizada. El sistema de eventos proporciona puntos de intercepción a lo largo del flujo de trabajo de Claude, desde la inicialización de la sesión hasta la compactación del contexto.
Los hooks de comandos manejan la validación y el formato local. Los hooks HTTP integran servicios y bases de datos externos. Los hooks de prompts modifican el comportamiento a través de la inyección de contexto. En conjunto, permiten patrones de automatización que aplican políticas de equipo, mantienen la calidad del código y se integran con la infraestructura de desarrollo existente.
El sistema de correspondencia filtra los hooks a herramientas y patrones de archivos específicos. Los códigos de salida y la salida JSON controlan el flujo de decisiones. La ejecución asíncrona evita bloqueos en operaciones lentas. El esquema de configuración completo admite todo, desde formato automático simple hasta validación compleja en varias etapas.
Comienza con hooks PostToolUse básicos para dar formato al código. Agrega validación PreToolUse a medida que surgen las políticas. Experimenta con hooks de prompts para la modificación del comportamiento. Crea integraciones HTTP para la aplicación en toda la empresa.
Consulta la documentación oficial de Claude Code para obtener la referencia completa de hooks y el esquema de configuración actualizado a medida que se lanzan nuevas capacidades.
