Claude Code ahora admite hooks

 (docs.anthropic.com)
20 puntos por GN⁺ 2025-07-02 | 4 comentarios | Compartir por WhatsApp
  • Se introdujo la función de hooks personalizados en Claude Code. Permite controlar el comportamiento de la app de forma más precisa y repetible, sin depender de las decisiones del LLM
  • Hace posible diversas automatizaciones como personalización de notificaciones, formateo automático de código y seguimiento de logs de comandos
  • Funciona antes/después de ejecutar comandos, al generarse notificaciones y al completarse una respuesta, y puede administrarse a nivel de proyecto, usuario o empresa mediante archivos de configuración
  • Mediante la estructura del archivo de configuración y el sistema de matchers, se puede ejecutar solo un hook específico en el momento de una llamada a herramienta determinada
  • La entrada se envía en formato JSON y la salida controla resultados y retroalimentación mediante exit code o JSON
  • Los hooks ejecutan automáticamente comandos de shell con todos los permisos del usuario, por lo que se requiere precaución en materia de seguridad y protección

Introducción

  • Los hooks de Claude Code son comandos de shell personalizados que se ejecutan automáticamente en cada etapa del ciclo de vida de ejecución del código
  • Esto permite una automatización consistente en cada ejecución, en lugar de depender de que el LLM lo haga de forma opcional

  • Principales casos de uso

    • Notificaciones: ofrecer notificaciones personalizadas al usuario cuando se espera entrada
    • Formateo automático: ejecutar automáticamente prettier o gofmt después de editar archivos
    • Logging: registrar y agregar los comandos ejecutados para seguimiento o depuración
    • Retroalimentación: ofrecer feedback automático cuando se genera código que no cumple con las reglas del codebase
    • Permisos personalizados: bloquear cambios en directorios sensibles o archivos de producción
  • Como funcionan mediante código del sistema y no por prompts, se ejecutan de forma determinística cada vez → aumenta la confiabilidad de la automatización
  • Los hooks ejecutan directamente comandos de shell con todos los permisos del usuario, por lo que es necesario validar su seguridad.

Ejemplo de configuración

  • Ejemplo: registrar un hook para que Claude deje un log cada vez que vaya a ejecutar un comando Bash
    1. Entrar al menú de configuración de hooks con el comando /hooks y seleccionar el evento PreToolUse
    2. Agregar el matcher Bash (aplica solo a comandos Bash)
    3. Registrar y guardar el comando del hook (si se elige la ubicación User settings, se aplica a todos los proyectos)
    4. Se puede verificar la configuración con /hooks o revisar directamente el archivo en ~/.claude/settings.json

Estructura de configuración

  • Los hooks se agrupan según el matcher y cada matcher puede tener varios hooks en forma de arreglo
    • Ejemplo: cadena única (coincidencia exacta), expresión regular, o vacío para aplicar a todos los eventos
  • Tipos de archivos de configuración
    • ~/.claude/settings.json: configuración global del usuario
    • .claude/settings.json: configuración del proyecto
    • .claude/settings.local.json: configuración local (no compartida)
    • configuración de políticas empresariales

Principales eventos de hooks

  • PreToolUse: se ejecuta antes de invocar una herramienta y, si es necesario, puede bloquear la ejecución (matchers principales: Bash, Write, Edit, Grep, etc.)
  • PostToolUse: se ejecuta justo después de usar una herramienta, con soporte para los mismos matchers
  • Notification: se ejecuta al enviarse una notificación
  • Stop: se ejecuta al finalizar la respuesta

Ejemplos de matchers

  • Task: tarea del agente
  • Bash: comando de shell
  • Glob: coincidencia de patrón de archivo
  • Grep: búsqueda de contenido
  • Read: lectura de archivo
  • Edit, MultiEdit: modificación de archivo
  • Write: escritura de archivo
  • WebFetch, WebSearch: tareas web

Formato de entrada y salida

  • Entrada: se entrega JSON por stdin (incluye información de sesión y datos por evento)
    • Ejemplo: en PreToolUse incluye tool_input, y en PostToolUse se agrega tool_response
  • Salida:
    • exit code 0: ejecución normal; stdout se muestra al usuario
    • exit code 2: bloqueo; stderr se envía a Claude como feedback (en PreToolUse bloquea la ejecución de la herramienta)
    • Otros códigos: error; solo stderr se muestra al usuario
    • Control avanzado: si stdout devuelve JSON, se puede controlar el flujo detalladamente con valores como "continue": false o "decision": "block"

Integración con herramientas MCP

  • También admite herramientas basadas en Model Context Protocol (MCP), y permite apuntarlas de forma selectiva mediante un patrón especial de nombres (mcp____)

Recomendaciones de seguridad

  • Como los hooks conllevan el riesgo de ejecutar comandos arbitrarios del sistema, son indispensables reglas de seguridad como validación de entradas, verificación de rutas, exclusión de archivos sensibles y uso de rutas absolutas
  • Los cambios de configuración no se reflejan de inmediato; se usa una instantánea al iniciar la sesión y se muestra una advertencia si hay cambios externos

Entorno de ejecución y depuración

  • Cada hook tiene un límite máximo de 60 segundos, ejecución en paralelo y funcionamiento en el directorio de trabajo y entorno actuales
  • Se puede depurar verificando la configuración en /hooks, probando comandos directamente y revisando exit codes y salidas
  • El proceso de ejecución y sus resultados pueden verse en el modo transcript (Ctrl-R)

Lecturas relacionadas

4 comentarios

 
shakespeare 2025-07-02

Por favor, hagan una versión para Windows 😭
 
nalbam 2025-07-06

Usen WSL
 
slowmo 2025-07-08

Quizá sea por las especificaciones modestas de mi PC, pero en WSL de Windows algunas tareas con Claude Code (por ejemplo, compilar proyectos o ejecutar un servidor web local) son demasiado lentas.
Existe la opción de ejecutar solo esas tareas manualmente fuera de WSL, pero como es molesto y tiene limitaciones, desde que salió Gemini CLI en Windows he estado usando principalmente Gemini CLI en lugar de Claude Code.
 
GN⁺ 2025-07-02
Comentarios de Hacker News

  • Me frustraba la costumbre de Claude Code Opus 4 de no agregar un retorno de carro al final de los archivos.
    Como había que reiniciar claude para probar hooks nuevos, me resultó mucho más eficiente usar un script que pudiera seguir editando dentro de la sesión.
    Ese script aplica un formateador a archivos C y scripts de shell, y en los demás solo corrige los saltos de línea finales faltantes.
    A una IA como Claude se le da mal dividir bien los problemas y a veces intenta hacer las cosas de formas raras, así que terminé corrigiéndolo varias veces, como en el ejemplo del hook de arriba: guardar el archivo JSON en disco, extraer solo la ruta y volver a guardarla, y luego pasar esa ruta a save-hook.sh.
    Logré lo que quería en 10 minutos, pero perdí más tiempo por pedirle pasos grandes de una sola vez.

  • Se habla de que la IA va a reemplazar a los desarrolladores, pero sigue siendo trabajo de las personas configurar hooks como estos y proponer funciones nuevas.
    Este tipo de trabajo relacionado con tooling va a seguir existiendo al menos hasta que la IA evolucione al punto de idear esto por sí sola y aplicárselo a otras IA.

    • Si usamos una analogía de carpintería, siento que estamos en el punto de transición entre las herramientas manuales y las eléctricas.
      Quien entiende los fundamentos puede usar bien las herramientas, pero ahora estamos en una etapa donde, en vez de hacer algo delicadamente a mano, lo hacemos rápido con una sierra de mesa: es más eficiente, pero también puede ser más peligroso.

    • Es parecido a cuando se decía que las máquinas agrícolas como la cosechadora combinada iban a reemplazar los empleos en el campo.
      ¿De verdad tiene sentido pensar que toda esa gente simplemente se va a convertir en operadora de máquinas?
      La idea es que, ya sea con herramientas de automatización, en agricultura o con IA, el valor no está solo en una transición simple.

    • Como en la famosa historia de "la Tierra sobre el lomo de tortugas", después de la aparición de la IA se puede entrar en un bucle infinito de "entonces, ¿quién administra esa IA?".
      Ya hay casos donde se le pide a Claude Code que actualice por sí mismo CLAUDE.md, así que tampoco es completamente imposible hacer que modifique hasta sus propios hooks.
      Pero es interesante cómo, al estilo Jurassic Park, es fácil olvidar la pregunta de "si deberíamos hacerlo".

    • Son ciertas tanto la idea de que la IA va a reducir empleos de desarrollo como la pregunta de quién va a configurar los hooks.
      Se enfatiza que el avance tecnológico no se reduce simplemente a si aumenta o disminuye la cantidad de empleos, sino que elimina algunos y al mismo tiempo crea otros nuevos.

    • En realidad, para la mayoría de la gente este tipo de trabajo no es desarrollo, sino mantenimiento, DevOps y cosas por el estilo.
      Incluso en productos SaaS hay mucho trabajo más relacionado con operación que con código, y eso es bastante distinto del desarrollo más puro que suele imaginar la gente en HN.

  • Esta función me entusiasma muchísimo.
    Los hooks parecen que van a jugar un papel importante en la ingeniería de contexto del agente y en la verificación del rendimiento en tiempo de ejecución.
    También se puede extender a muchos casos, como compliance empresarial o monitoreo de comportamiento.
    También impresiona que Anthropic lo haya soportado directamente a partir de una sugerencia en GitHub Issues.
    Enlace al issue relacionado

    • En mi caso, de hecho uso una extensión de VS Code llamada cline.bot en lugar de Claude Code.
      Creo que esta función va a convertirse en una jugada clave que todos los agentes de programación terminarán adoptando.

  • Lo que me gusta de esta función es que permite escribir reglas complejas de control de ejecución de comandos directamente, sin tener que rodearlas con CLAUDE.md.
    Por ejemplo,
    docker compose exec django python manage.py test
    se puede permitir, mientras que
    docker compose exec django python manage.py makemigrations
    se puede bloquear.

    • Eso ya se puede implementar más o menos desde .Claude/settings.json.

  • Creo que habría sido aún mejor si esta función operara como un servidor MCP en sí mismo.
    Se podría imaginar un esquema donde los hooks se definan como herramientas MCP con nombres preacordados, y el agente descubra automáticamente esos hooks sin conocer la implementación interna, para reutilizar el servidor MCP o incluso reaprovecharlo con otros agentes.

  • Claude Code se olvida con frecuencia de las instrucciones del archivo CLAUDE.md y de los puntos importantes del codebase, así que hay que recordárselo a cada rato.
    Tengo curiosidad por ver si esta actualización puede arreglar ese problema.

    • Por ejemplo: "¡No uses early return en funciones void! ¡En CLAUDE.md dice que ese patrón está prohibido!"
      Claude lee CLAUDE.md y responde: "22 segundos, 2.6k tokens..."
      "¡Tienes razón!"

  • Comparto algunos hooks de ejemplo.
    Artículo con ejemplos de creación de hooks y automatización de flujo de trabajo
    Me alegra que Claude Code ya tenga soporte de linting y type checking después de modificar código, al nivel de Cursor.

  • Ojalá Cursor también tenga algo así.
    Por ahora lo estoy resolviendo más o menos combinando varias reglas como solución temporal.

    • Como alguien que no usa Cursor, todavía me pregunto si sigue habiendo una razón para usarlo.

  • Creo que esta función cierra una gran brecha que existía hasta ahora.
    Como Claude Code genera commits de una manera que hace que la mayoría de los Git hooks normales no funcionen, yo había estado usando el truco de indicarle por CLAUDE.md que automatizara el formato del código con Qlty CLI, pero Claude no lograba hacerlo de forma consistente y eso era frustrante.
    Con este cambio se pueden obtener resultados mucho más determinantes.
    Aunque por ahora los eventos que admiten hooks son limitados, tengo ganas de ver si más adelante también será fácil enganchar eventos de Git commit y push.
    GitHub de Qlty CLI

    • Como referencia, Claude maneja Java extremadamente bien.
      Capta con precisión mi guía de estilo y hasta mis preferencias de indentación, al punto de dejar el código Java perfectamente adaptado y sin necesidad de reformatearlo.
      Incluso ajusta muy bien el JavaDoc, lo cual me sorprendió.
      Supongo que debe haber entrenado con una cantidad enorme de código Java empresarial.

    • Me da curiosidad por qué los Git hooks normales no funcionan bien en Claude Code.

    • Husky y lint-staged sí funcionaron bien, pero los pre-commit hooks no funcionaron.

  • Según mi entendimiento, aunque sea limitado, esta función no consume contexto y, a diferencia de MCP donde Claude decide cuándo ejecutar algo, aquí se trata de una estructura de automatización en la que el usuario especifica directamente qué acción automática se aplica a cada uso de herramienta.