Los hooks de Claude Code son comandos definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code — antes de una llamada a una herramienta, después de una edición, cuando se inicia una sesión, cuando Claude termina un turno — de modo que puedas validar, formatear, registrar o bloquear acciones sin tener que estar pendiente en todo momento. Son la diferencia entre un agente de codificación con IA que sugiere y uno que sigue tus reglas de forma determinista. Esta guía explica qué son los hooks, todos los eventos en los que pueden activarse, cómo configurarlos, cinco recetas prácticas que puedes copiar, la trampa del código de salida en la que todo el mundo cae, y cómo aprovechar toda la potencia de Claude Code sin ninguna instalación local.

¿Qué son los hooks de Claude Code?

Un hook es un manejador — un comando de shell, un endpoint HTTP, una llamada a una herramienta MCP, o incluso un prompt al modelo — que Claude Code ejecuta automáticamente cuando ocurre un evento concreto. El manejador recibe una entrada estructurada (por stdin en el caso de los hooks de tipo command, o como cuerpo POST en los hooks HTTP), puede inspeccionar lo que está sucediendo, tomar una acción y, opcionalmente, devolver una decisión que cambia lo que Claude hace a continuación.

Esa última parte es lo que hace que los hooks sean potentes y no simplemente cómodos. Un hook no es solo una notificación: puede bloquear una llamada a una herramienta, reescribir la entrada o salida de una herramienta, inyectar contexto adicional o detener a Claude por completo. En otras palabras, los hooks convierten a Claude Code de un asistente inteligente en uno programable que impone las guardas de tu equipo de forma determinista, no solo cuando el modelo recuerda aplicarlas.

Cuándo se activan los hooks: el ciclo de vida

Los hooks se adjuntan a eventos, y Claude Code expone muchos de ellos. Se agrupan por cadencia: algunos se activan una vez por sesión, otros una vez por turno, y otros en cada llamada a una herramienta.

Dónde se activan los hooks a lo largo de una sesión de Claude Code — desde SessionStart hasta SessionEnd.

Los eventos que más usarás:

• SessionStart / SessionEnd — una vez cuando comienza o termina una sesión. Ideales para cargar contexto (issues abiertas, información de la rama, variables de entorno) o para tareas de limpieza.
• UserPromptSubmit — se activa cuando envías un prompt, antes de que Claude lo procese. Puedes filtrar o ampliar el prompt.
• PreToolUse — antes de cualquier llamada a una herramienta. Aquí es donde bloqueas acciones peligrosas.
• PostToolUse (y PostToolUseFailure) — después de que una llamada a una herramienta tenga éxito (o falle). El lugar para el linting, el formateo y la verificación.
• Stop / StopFailure — cuando Claude termina de responder, o el turno finaliza con un error.
• Notification — cuando Claude Code emite una notificación (útil para alertas de escritorio).

Además de estos, Claude Code también activa hooks para subagentes (SubagentStart/SubagentStop), tareas (TaskCreated/TaskCompleted), compactación de contexto (PreCompact/PostCompact), cambios de directorio de trabajo (CwdChanged), cambios de archivos en disco (FileChanged), carga de instrucciones (InstructionsLoaded) y más. La amplitud es precisamente la cuestión: casi cualquier momento del bucle del agente es un lugar donde puedes adjuntar una política.

Los cinco tipos de manejadores de hooks

Un evento de hook puede activar cinco tipos diferentes de manejador, lo que hace que el sistema sea flexible:

1. command — ejecuta un comando de shell; lee la entrada por stdin, señala decisiones mediante el código de salida y la salida estándar.
2. http — envía el JSON del evento mediante POST a una URL y lee la respuesta JSON.
3. mcp_tool — llama a una herramienta en un servidor MCP conectado.
4. prompt — una evaluación del modelo de un solo turno que devuelve una decisión sí/no en JSON (útil para comprobaciones difusas).
5. agent — genera un subagente (experimental).

Para la mayoría de los equipos, los hooks de tipo command cubren el 90% del trabajo — un script de shell basta para hacer linting, bloquear o registrar.

Cómo configurar un hook

Los hooks residen en archivos de configuración (la documentación oficial de hooks de Claude Code es la referencia canónica), y dónde los coloques controla su alcance:

La estructura se anida en tres niveles: eliges un evento, añades un grupo de matcher, y luego defines los manejadores. Los matchers deciden a qué llamadas de herramientas se aplica un hook — "*" (u omitirlo) coincide con todo, un simple Edit|Write coincide exactamente con esas herramientas, y cualquier cosa más compleja se trata como una expresión regular. (Las herramientas MCP coinciden con el patrón mcp__<server>__<tool>.)

Aquí tienes un hook PostToolUse que ejecuta una comprobación de lint después de cada edición:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/path/to/lint-check.sh" }]
      }
    ]
  }
}

Cinco recetas prácticas de hooks

Estos son los patrones a los que recurren los equipos en primer lugar:

1. Hacer lint o formatear después de cada edición. Un hook PostToolUse asociado a Edit|Write que ejecuta tu formateador o linter, de modo que el código del agente siempre cumpla tus normas de estilo.
2. Bloquear comandos destructivos. Un hook PreToolUse asociado a Bash que inspecciona el comando y bloquea rm -rf y similares antes de que se ejecuten.
3. Notificaciones de escritorio. Un hook Notification que te avisa cuando Claude necesita atención o termina una tarea larga.
4. Registro de auditoría. Un hook PostToolUse (o dirigido a MCP) que registra cada llamada a una herramienta para cumplimiento normativo — qué se ejecutó, cuándo y con qué argumentos.
5. Cargar el contexto del proyecto al iniciar. Un hook SessionStart que recupera issues abiertas, la rama actual o variables de entorno, de modo que el agente comience cada sesión ya orientado.

Cinco recetas de hooks habituales y los eventos a los que se adjuntan.

La trampa del código de salida

Este es el detalle en el que todo el mundo se equivoca, así que interiorízalo bien: en los hooks de tipo command, solo el código de salida 2 bloquea. La salida 0 significa éxito (y la salida estándar se analiza en busca de cualquier decisión JSON). La salida 2 es un error bloqueante — su stderr se devuelve a Claude. Cualquier otro código, incluido el 1, es un error no bloqueante — Claude continúa.

Así que si escribes un hook para "bloquear esto" y usas exit 1, no bloqueará — la acción se ejecutará igualmente. Para imponer realmente una política desde un hook de tipo command, usa exit 2. (Los hooks de tipo command también pueden devolver un control más rico como JSON en la salida estándar — permissionDecision: "deny" para PreToolUse, updatedInput para reescribir argumentos, additionalContext para inyectar información, y continue: false para detener a Claude por completo.)

Un ejemplo trabajado: bloquear rm -rf

Construyamos de principio a fin la guarda contra comandos destructivos, porque muestra todas las piezas en movimiento. Primero, la configuración — un hook PreToolUse asociado a Bash:

{ "hooks": { "PreToolUse": [{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh" }] }] } }

Luego el script, guard.sh. Claude Code envía el evento como JSON por stdin, incluida la entrada de la herramienta; el script lo lee, comprueba el comando y decide:

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
  echo "Blocked: destructive command refused by policy." >&2
  exit 2     # exit 2 blocks — exit 1 would NOT
fi
exit 0

La línea decisiva es exit 2. Devuelve 0 y el comando se ejecuta; devuelve 1 y — de forma contraintuitiva — aun así se ejecuta como un error no bloqueante; solo exit 2 bloquea y devuelve tu mensaje de stderr a Claude para que entienda el motivo. Haz el script ejecutable, confírmalo en .claude/hooks/, y a partir de ahí cada llamada a Bash pasará por tu guarda — para todo tu equipo, ya que el settings.json del proyecto es compartible. Para una garantía absoluta en lugar de una red de mejor esfuerzo, combínalo con las reglas de permisos de Claude Code; como red de seguridad determinista y bajo control de versiones, este hook ya cumple su función.

Cuándo los hooks no son la respuesta

Los hooks sirven para políticas deterministas y repetibles — "siempre hacer lint después de una edición", "nunca ejecutar rm -rf". Son la herramienta equivocada para cosas que requieren criterio (usa el modelo o un hook de tipo prompt para decisiones difusas) y para garantías de seguridad estrictas (usa el sistema de permisos, ya que los filtros if de los command hooks fallan de forma abierta). Tampoco abuses de los hooks: cada hook de tipo command ejecuta un proceso con un tiempo límite, y una maraña de hooks lentos añade latencia a cada llamada a una herramienta. Mantenlos rápidos, pocos y centrados en las reglas que realmente importan.

Notas de seguridad que conviene conocer

Algunas realidades que la documentación deja explícitas:

• El filtro if falla de forma abierta. Si usas el campo if para acotar un hook a una regla de permisos y el comando no se puede analizar, el hook se ejecuta de todos modos. Para una aplicación estricta de permitir/denegar, usa el sistema de permisos de Claude Code, no los hooks.
• Los hooks se ejecutan sin una terminal de control — no pueden mostrar prompts en /dev/tty. Usa systemMessage o la salida restringida terminalSequence para mensajes dirigidos al usuario.
• La salida estándar debe estar limpia. Solo el objeto de decisión JSON debe aparecer en stdout; una salida perdida de un perfil de shell puede romper el análisis.
• Trata el contexto inyectado con cuidado. additionalContext debería redactarse como afirmaciones factuales, no como órdenes imperativas, para llevarse bien con las defensas contra inyección de prompts.

Los hooks son ingeniería de harness en miniatura

Dando un paso atrás, los hooks son un ejemplo concreto de una idea más amplia: el modelo no es todo el agente — el sistema que lo rodea también cuenta. Los hooks forman parte del harness que hace que un agente de codificación sea fiable, junto con el bucle, las herramientas, la memoria y el sandbox. (Profundizamos en ese modelo mental en harness engineering.) Cuando escribes un bloqueo PreToolUse o un linter PostToolUse, estás haciendo ingeniería de harness — dando forma al comportamiento del agente de manera determinista en lugar de confiar en que el modelo se comporte bien.

Ese enfoque también te indica cuándo merece la pena el esfuerzo de usar hooks: cualquier regla que de otro modo tendrías que recordarle al agente cada vez es candidata a convertirse en un hook.

Aprovechar toda la potencia de Claude Code sin instalación local

Los hooks residen en la CLI de Claude Code, lo que significa que necesitas tenerla instalada y configurada para usarlos — un obstáculo para cualquiera que no esté familiarizado con una terminal, e imposible para compañeros de equipo que no sean desarrolladores. Si quieres las capacidades de agente de Claude Code sin gestionar una instalación local, puedes ejecutar Claude Code en tu navegador en Happycapy: ejecuta Claude Code en un sandbox en la nube gestionado donde el harness — el bucle, las herramientas, la memoria y el aislamiento a los que se conectan los hooks — ya está configurado por ti. Describes una tarea y ves al agente trabajar en un escritorio visual, sin necesidad de terminal.

Piénsalo así: los hooks permiten a los usuarios avanzados ajustar a mano el harness de Claude Code; Happycapy le da a todo el mundo un harness gestionado desde el primer momento. Si has querido poner a trabajar a Claude Code pero la configuración de la CLI te ha detenido, empieza gratis en happycapy.ai y ejecuta una tarea real en tu navegador hoy mismo.

Preguntas frecuentes

P: ¿Qué son los hooks de Claude Code?

Son manejadores definidos por el usuario — comandos de shell, endpoints HTTP, llamadas a herramientas MCP, o prompts al modelo — que Claude Code ejecuta automáticamente en eventos del ciclo de vida como antes de una llamada a una herramienta (PreToolUse), después de una edición (PostToolUse), o al iniciar una sesión. Pueden validar, formatear, registrar, bloquear o reescribir acciones.

P: ¿Qué eventos de hook admite Claude Code?

Muchos — incluidos SessionStart/SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse (y PostToolUseFailure), Stop/StopFailure, Notification, eventos de subagentes y de tareas, y eventos de compactación. Se activan una vez por sesión, una vez por turno, o en cada llamada a una herramienta.

P: ¿Cómo hago que un hook bloquee una llamada a una herramienta?

En los hooks de tipo command, termina con el código 2 — solo el código 2 bloquea (el 1 no lo hace). Para PreToolUse, también puedes devolver JSON con permissionDecision: "deny". Para una aplicación estricta, prefiere el sistema de permisos de Claude Code, ya que el filtro if del hook falla de forma abierta.

P: ¿Dónde configuro los hooks de Claude Code?

En archivos de configuración: ~/.claude/settings.json (todos los proyectos), .claude/settings.json (un proyecto, compartible), o .claude/settings.local.json (solo local). Eliges un evento, añades un matcher y defines los manejadores.

P: ¿Puedo usar los hooks de Claude Code sin instalar la CLI?

Los hooks en sí requieren la CLI de Claude Code. Si tu objetivo es usar Claude Code sin instalación local, ejecútalo en un sandbox de navegador gestionado como Happycapy, que proporciona el agente y su harness listos para usar — ideal cuando no quieres instalar y configurar la CLI tú mismo.

P: ¿Cuál es un buen primer hook para añadir?

Un linter PostToolUse asociado a Edit|Write — ejecuta tu formateador después de cada cambio de código, de modo que la salida del agente siempre cumpla tus normas de estilo. Es de bajo riesgo e inmediatamente útil.

Guías relacionadas

• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?