Personalización de usuarios avanzados de Claude Code: cómo configurar hooks

Incluso un flujo de trabajo de Claude Code fluido acumula puntos de fricción con el tiempo. Cada vez que Claude escribe un archivo, Prettier tiene que ejecutarse manualmente. Cada vez que ejecuta npm test, aparece el mismo mensaje de permiso. Cada sesión comienza pegando el mismo contexto de proyecto predefinido en el primer mensaje.

¿Las buenas noticias? Los hooks eliminan estos puntos de fricción. Actúan como interruptores que puedes configurar para que se activen antes o después de ciertas acciones, lo que te permite inyectar lógica, scripts y comandos personalizados directamente en las operaciones de Claude. 

Este artículo cubre la configuración avanzada para desarrolladores que ya estén familiarizados con los conceptos básicos de Claude Code. Al final de este artículo, entenderás los ocho tipos de hooks, cuándo usar cada uno, cómo configurarlos y cómo depurarlos cuando las cosas salen mal.

Entremos en harina.

¿Qué es un hook?

Un hook es un comando de shell personalizado que creas para ejecutarse automáticamente cuando se produce un evento específico en tu sesión de Claude Code, como cuando Claude está a punto de escribir un archivo o cuando envías un prompt. Puedes designar hooks para una amplia gama de propósitos: interceptar acciones antes de que se ejecuten, inyectar contexto de agente, automatizar aprobaciones o bloquear operaciones antes de que se realicen.

Los hooks se configuran en tus archivos de configuración utilizando una estructura JSON con nombres de eventos, matchers (para filtrar qué herramientas activan el hook) y los comandos que se deben ejecutar. Se ejecutan en tu entorno local con tus permisos de usuario, recibiendo información sobre el evento activador a través de stdin y comunicándose a través de códigos de salida y stdout. Esto te ofrece un control preciso sobre el comportamiento de Claude Code sin modificar la herramienta en sí.

¿Por qué usar hooks en Claude Code?

Los hooks resuelven tres categorías de problemas.

Primero, eliminan los pasos manuales repetitivos. En lugar de ejecutar tu formateador después de cada cambio de archivo, un hook PostToolUse lo gestiona automáticamente. En lugar de aprobar npm test por enésima vez, un hook PermissionRequest lo aprueba automáticamente.

En segundo lugar, los hooks aplican reglas específicas del proyecto automáticamente. Puedes bloquear comandos peligrosos antes de que se ejecuten, validar rutas de archivos antes de las escrituras o garantizar que se sigan las convenciones de nomenclatura. Estas barreras de protección se ejecutan cada vez, no solo cuando te acuerdas de revisar.

En tercer lugar, los hooks inyectan contexto dinámico sin esfuerzo manual. Un hook de SessionStart puede proporcionar a Claude tu Estado actual de git y tu lista de TODO. Un hook de UserPromptSubmit puede añadir tus prioridades de sprint a cada solicitud. Claude se mantiene al día sin que tengas que repetirte.

Tipos de hooks de Claude Code y cuándo usarlos

Claude Code proporciona ocho eventos de hook que cubren todo el ciclo de vida de una sesión, desde el inicio, pasando por la ejecución de la herramienta, hasta la finalización. Cada uno se activa en un momento específico, lo que te brinda un control preciso sobre cuándo se ejecuta la automatización. Elegir el hook adecuado depende de lo que quieras conseguir.

Hooks de un vistazo

PreToolUse

Este es el hook más utilizado, se dispara después de que Claude elija una herramienta para usar, pero antes de que la herramienta se ejecute realmente. Tu script puede inspeccionar la acción planificada y aprobarla, bloquearla, solicitar confirmación del usuario o modificar los parámetros, utilizando un matcher para filtrar qué herramientas activan ese hook.

Este ejemplo de hook PreToolUse evalúa las escrituras de archivos antes de ejecutarlas. Claude revisa la acción planificada según los criterios especificados y puede aprobar, bloquear o señalar preocupaciones según la lógica del prompt.

Cuándo usar PreToolUse:

• Bloquear comandos peligrosos de Bash como rm -rf o force pushes
• Aprobar automáticamente operaciones seguras y repetitivas para reducir la fatiga por prompts
• Validar rutas de archivos antes de las escrituras para evitar sobrescrituras accidentales
• Modificar entradas de herramientas para inyectar valores predeterminados específicos del proyecto

PermissionRequest

Este hook se activa cuando Claude normalmente mostraría un cuadro de diálogo de permisos. Este gancho intercepta el momento antes de que veas un prompt de confirmación, dejando que tu script decida si permitir, denegar o seguir preguntando al usuario.

Este ejemplo aprueba automáticamente cualquier comando de Bash que empiece por npm test. El patrón de coincidencia puede incluir argumentos para un control más preciso.

Cuándo usar PermissionRequest:

• Aprobar automáticamente comandos de prueba que ejecutas docenas de veces por sesión
• Bloquear el acceso de escritura a archivos de configuración de producción
• Permitir operaciones de lectura en directorios específicos sin solicitudes de confirmación
• Denegar cualquier comando que coincida con un patrón peligroso

PostToolUse

Se activa inmediatamente después de que una herramienta se ejecute con éxito. Tu script recibe información sobre lo que sucedió, incluido el resultado de la herramienta, utilizando matchers para filtrar qué herramientas lo activan.

Este ejemplo de PostToolUse ejecuta Prettier en cualquier archivo que Claude escriba o edite. La sintaxis de canalización en el matcher significa que se activa tanto para las herramientas de escritura como para las de edición.

Cuándo usar PostToolUse:

• Ejecutar Prettier, Black o gofmt después de cada escritura de archivo para aplicar el formato
• Registrar todas las modificaciones de archivos en un registro de auditoría
• Activar linters y mostrar advertencias después de los cambios de código
• Enviar notificaciones cuando se completen ciertas operaciones

PreCompact

Se activa antes de que Claude compacte el contexto de la conversación para liberar espacio. La compactación resume partes antiguas de la conversación, lo que significa que algunos detalles se pierden. Este hook te da la oportunidad de preservar información antes de que eso ocurra.

Este ejemplo de PreCompact realiza una copia de seguridad de la transcripción antes de la compactación automática. El matcher puede ser "auto" o "manual" para que puedas distinguir entre compactación automática y eventos de compactación activados por el usuario.

Cuándo usar PreCompact:

• Hacer una copia de seguridad de la transcripción completa en un archivo antes de resumirla
• Extraer y guardar decisiones importantes o fragmentos de código
• Registrar hitos de las sesiones para revisarlos posteriormente

SessionStart

Se dispara cuando Claude Code comienza una nueva sesión o reanuda una existente. Todo lo que tu script produzca se añade al contexto de la conversación, por lo que Claude comienza con esa información ya cargada.

Cada sesión comienza con Claude conociendo tu estado actual de git y tu lista de TODO. Stdout se convierte automáticamente en contexto.

Cuándo usar SessionStart:

• Alimentar a Claude con tu rama actual de git y los commits recientes
• Cargar el contenido de tu lista TODO o del sprint backlog
• Inyectar detalles de configuración específicos del entorno

Detener

Se activa cuando Claude termina de responder y normalmente esperaría a tu siguiente entrada. Tu script puede inspeccionar lo que Claude produjo y decidir si la tarea está realmente completa.

El script puede devolver JSON con "continue": true para hacer que Claude siga trabajando, lo que es útil para flujos de trabajo de varios pasos:

Cuándo usar Stop:

• Forzar a Claude a continuar hasta que todos los elementos de una lista de verificación estén completados
• Verificar que las pruebas pasen antes de considerar completa una tarea
• Activar la generación de resumen al final de una sesión
• Verificar que el código generado compile antes de detenerse

SubagentStop

Este hook se activa cada vez que un subagente creado a través de la herramienta Task finaliza. Funciona de la misma manera que Stop, pero se activa específicamente cuando un subagente completa su acción (en lugar de cuando lo hace el agente principal). La configuración de SubagentStop refleja la estructura del hook Stop:

Cuándo usar SubagentStop:

• Validar que el resultado del subagente cumpla los criterios de calidad
• Desencadenar acciones de seguimiento según los resultados de los subagentes
• Registrar la actividad de subagentes para depurar o auditar

UserPromptSubmit

Se dispara cuando envías un prompt, antes de que Claude lo procese. Todo lo que tu script envíe a través de stdout se añade al contexto de Claude junto con tu prompt, lo que hace que UserPromptSubmit sea útil para inyectar dinámicamente información que Claude debería considerar.

En este ejemplo, cada vez que envías un prompt, Claude recibe el contenido de tu archivo de contexto de sprint. Esto permite que Claude tenga información actualizada sobre las prioridades actuales sin que tengas que volver a expresarlas.

Cuándo usar UserPromptSubmit:

• Inyectar el contexto actual del sprint o las prioridades del proyecto con cada prompt
• Validar prompts antes de que lleguen a Claude
• Bloquear ciertos tipos de solicitudes según el contenido
• Añadir contexto dinámico, como registros de errores recientes o resultados de pruebas

Configuración y ubicaciones de archivos

Los hooks se encuentran en archivos de configuración JSON en tres niveles. Los hooks de nivel de proyecto van en .claude/settings.json dentro de tu repositorio, lo que hace que se puedan compartir con tu equipo. Los hooks de nivel de usuario van en ~/.claude/settings.json y se aplican a todos tus proyectos. Los hooks de proyectos locales van en .claude/settings.local.json para una configuración personal que no desees hacer commit.

La configuración de nivel de proyecto tiene prioridad sobre la configuración de nivel de usuario. También hay configuraciones de políticas gestionadas por la empresa disponibles para el control de la organización. Para obtener información completa, consulta la información de configuración de Claude Code.

Consejo útil: este es el mismo archivo donde puedes configurar permisos granulares para las acciones de Claude, a nivel de proyecto, usuario o local. Por ejemplo, puedes permitir explícitamente a Claude que lea todos los archivos de un directorio para que no tengas que aprobarlo cada vez, o bloquear cualquier modificación de archivos confidenciales.

Sintaxis de matcher

Los matchers son la forma de filtrar qué herramientas pueden activar tu hook. Solo se aplican a los hooks de PreToolUse, PostToolUse y PermissionRequest.

La coincidencia simple de cadenas funciona exactamente como cabría esperar: "Write" solo coincide con la herramienta Write.

Por ejemplo:

La sintaxis de pipe te permite hacer coincidir múltiples herramientas: "Write|Edit" se activa para cualquiera de los casos, mientras que los comodines coinciden con todo: "*" o una cadena vacía coincide con todas las herramientas.

Nota: los matchers distinguen entre mayúsculas y minúsculas, por lo que "bash" no coincidirá con la herramienta Bash.

Para un control más preciso, los patrones de argumentos como "Bash(npm test*)" pueden coincidir con argumentos de comando específicos. Los patrones de herramientas MCP siguen el formato "mcp__memory__.*" para herramientas de Model Context Protocol.

Entrada, salida y respuestas estructuradas

Lo que reciben los hooks

Todos los hooks reciben JSON a través de stdin que contiene información de la sesión y datos específicos de eventos. Los campos comunes incluyen: session_id, transcript_path, cwd, permission_mode y hook_event_name.

Además, los hooks relacionados con herramientas también reciben tool_name y tool_input. Estos datos permiten que tus scripts tomen decisiones informadas sobre cómo responder.

Cómo responden los hooks

Los códigos de salida determinan el resultado básico. El código de salida 0 significa éxito y stdout se procesa para JSON o se añade al contexto. El código de salida 2 significa un error de bloqueo: stderr se convierte en el mensaje de error y la acción se impide.

Otros códigos de salida indican errores sin bloqueo, con stderr mostrado en modo detallado.

Además de los códigos de salida, los hooks pueden devolver JSON estructurado para un mayor control. Los campos incluyen: decision (approve, block, allow o deny), reason (explicación mostrada a Claude), continue (para los hooks de Stop para forzar la continuación) y updatedInput (para modificar parámetros de la herramienta antes de la ejecución).

Entorno y ejecución

Los hooks tienen acceso a variables de entorno, incluyendo: CLAUDE_PROJECT_DIR para la ruta raíz del proyecto, CLAUDE_CODE_REMOTE, que es true para entornos web, y CLAUDE_ENV_FILE para los hooks de SessionStart para persistir variables. Las variables de entorno estándar de tu shell también son accesibles.

También hay que tener en cuenta: los hooks tienen un tiempo de espera por defecto de 60 segundos, configurable por hook. Cuando varios hooks coinciden con un evento, se ejecutan en paralelo. Los comandos idénticos se deduplican automáticamente.

Consideraciones de seguridad

Los hooks ejecutan comandos de shell arbitrarios con tus permisos de usuario. Claude Code incluye una salvaguarda: las modificaciones directas a archivos de configuración de hooks requieren revisión en el menú /hooks antes de que surtan efecto. Esto evita que código malicioso añada silenciosamente hooks a tu configuración.

Sin embargo, si configuras y apruebas los hooks, estos se ejecutarán con tus niveles de permiso.

Consejo profesional: antes de ejecutar cualquier comando en un entorno, ten en cuenta los riesgos. Si vas a ejecutar comandos con hooks, considera buenas prácticas como: validar y sanear entradas de stdin, entrecomillar variables de shell para evitar inyecciones, usar rutas absolutas para scripts y evitar procesar archivos sensibles como .env o credenciales.

Depurar y probar

Claude Code registra todo en archivos de transcripción, lo que proporciona visibilidad de las llamadas y respuestas de herramientas sin necesidad de ninguna configuración. Cada hook recibe un campo transcript_path que apunta a un archivo JSONL que contiene el historial completo de la sesión. Puedes usar un hook de SessionStart para registrar dónde se encuentra cada transcripción:

Luego usa tail en esa transcripción para ver a Claude trabajar en tiempo real: tail -f /path/to/transcript.jsonl | jq .

Depuración específica de hooks

Para la depuración específica de hooks, añade registros a tus scripts de hook. Los archivos de transcripción mostrarán lo que hizo Claude, pero no por qué tu hook realizó la acción para aprobar o bloquear algo.

Con un poco de esfuerzo adicional, puedes añadir un pequeño script de bash que envolverá tus herramientas y registrará la información adicional. Por ejemplo, log-wrapper.sh:

Este pequeño script wrapper captura stdin en una variable, registra la marca de tiempo y el nombre de la herramienta y luego canaliza la entrada a tu herramienta real.

Una vez que tengas escrito log-wrapper.sh, lo antepondrías a la llamada a la herramienta en el hook:

Consejo profesional: para obtener más consejos de depuración, consulta la documentación de depuración de Claude Code.

Crear tus propios hooks

Empieza con un simple hook que resuelva un punto de fricción real en tu flujo de trabajo. El hook de formato PostToolUse es una buena primera opción, ya que el feedback es inmediato y visible. Una vez que eso funcione, amplía según lo que aprendas.

Para obtener documentación de referencia completa, incluidos todos los campos disponibles y patrones avanzados, consulta la documentación oficial de hooks.

Los hooks te permiten dar forma a Claude Code para que se adapte a tu flujo de trabajo, en lugar de adaptar tu flujo de trabajo a la herramienta. Cuando inviertes en configurar los hooks, cada sesión da sus frutos.

Empieza a usar hooks para personalizar tus flujos de trabajo de Claude Code hoy mismo.