Código tuyo que se ejecuta automáticamente en momentos exactos del ciclo de vida de Claude Code. Es la única forma de convertir una regla en una garantía: formatear siempre, bloquear siempre, avisar siempre.
HOOKS · 1
Qué es un hook, en simple
En simpleUn hook es una regla del tipo "cuando pase X, ejecuta Y". Como un sensor de movimiento que prende la luz: no depende de que alguien se acuerde. Claude puede olvidar una instrucción de tu CLAUDE.md; un hook se ejecuta siempre, porque lo corre Claude Code, no el modelo.
CLAUDE.md dice…
"Corre prettier después de editar"
Sugerencia. El modelo decide si lo hace. Puede olvidarlo tras compactar.
Garantía. Corre después de cada Edit o Write, sin excepción.
Qué puedes hacer con hooks
BloquearImpedir comandos peligrosos o ediciones a .env, incluso en modo bypass.
AutomatizarFormatear, correr linters o tests después de cada cambio.
Inyectar contextoAgregar la rama actual, el sprint o recordatorios al prompt o tras compactar.
NotificarAviso de escritorio o Slack cuando Claude espera tu respuesta.
AprobarResponder automáticamente prompts de permiso que siempre aceptas.
AuditarRegistrar cada comando o cambio de configuración para cumplimiento.
Cinco tipos de handlerUn hook puede ser un comando de shell (command, el más común), un POST a una URL (http), una llamada a una herramienta MCP (mcp_tool), una evaluación de un LLM (prompt) o un subagente con herramientas (agent, experimental).
HOOKS · 2
El ciclo de vida, animado
Los eventos se disparan en un orden predecible. Reproduce una sesión típica y mira cuándo se enciende cada uno. Toca cualquier evento para ver qué puede hacer ahí.
Una sesión, evento por evento
Presiona Reproducir o avanza evento por evento con Siguiente.
ClavePreToolUse corre antes de cualquier chequeo de modo de permiso, en todos los modos. Si devuelve deny, bloquea incluso con --dangerously-skip-permissions. Al revés no: un hook que devuelve allow no salta las reglas deny de settings.
HOOKS · 3
Anatomía de la configuración
Los hooks viven en archivos de settings bajo la clave hooks, con tres niveles anidados. Toca cada nivel para ver qué parte del JSON es.
Las ediciones a settings se recargan solas; no necesitas reiniciar. /hooks muestra un navegador de solo lectura con todo lo configurado y su origen.
Si varios hooks coinciden con un evento, todos corren en paralelo. Un deny de uno no detiene a los otros (sus efectos secundarios igual ocurren).
Para decisiones de permiso en PreToolUse gana la más restrictiva: deny > defer > ask > allow. El additionalContext de todos se combina.
"disableAllHooks": true apaga los hooks de un archivo (no los managed). Una organización puede forzar allowManagedHooksOnly.
HOOKS · 4
Catálogo completo de eventos
Hay más de 30 eventos. Filtra por categoría o por los que pueden bloquear, y toca uno para ver su ficha.
Eventos de hooks
HOOKS · 5
Matchers y el campo if
Sin matcher, el hook corre en cada ocurrencia del evento. El matcher filtra según un campo que depende del evento: el nombre de la herramienta en eventos de herramientas, el origen en SessionStart, el tipo en Notification, etc.
Escribes
Se interpreta como
Ejemplo
"*", "" u omitido
Coincide con todo
""
Solo letras, dígitos, _, -, separados por | o ,
Lista exacta de nombres
Edit|Write = Edit, Write
Cualquier otro carácter
Expresión regular JavaScript, sin anclar
mcp__memory__.*
Probador de matchers
Filtra también por argumentos con if
El matcher solo ve el nombre de la herramienta. Para filtrar por qué hace, agrega if al handler con sintaxis de reglas de permiso. Así el proceso ni siquiera se lanza si no coincide:
Ojo con BashClaude también puede modificar archivos con comandos de shell (sed -i, mv). Si tu hook debe ver todo cambio (auditoría, cumplimiento), agrega un hook Stop que revise el árbol con git status --porcelain una vez por turno. Los matchers distinguen mayúsculas.
HOOKS · 6
Entrada: el JSON que recibe tu hook
Cuando un evento se dispara, Claude Code le pasa a tu comando un JSON por stdin. Un hook HTTP lo recibe como body del POST. Todos los eventos comparten estos campos:
Campo
Contenido
session_id
ID de la sesión
transcript_path
Ruta al JSON de la conversación (se escribe de forma asíncrona; puede ir atrasado)
cwd
Directorio de trabajo cuando se disparó
permission_mode
default, plan, acceptEdits, auto, dontAsk o bypassPermissions
hook_event_name
El evento que lo disparó
effort
Objeto con level (low … max)
prompt_id, scratchpad_dir
UUID del prompt en proceso y carpeta temporal de la sesión
agent_id, agent_type
Solo si corre dentro de un subagente o con --agent
Cada evento agrega lo suyo. Elige uno para ver un ejemplo de stdin realista:
Ejemplos de stdin
Leerlo en tu script
bash · con jq
#!/bin/bash
INPUT=$(cat) # todo el JSON de stdin
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
Tu hook le responde a Claude Code de dos formas. Elige una por hook:
Forma simple: exit code0 = sin objeción · 2 = bloquear (el motivo va a stderr) · otro = error no bloqueante, la acción sigue.
Forma estructurada: JSONSales con 0 e imprimes un objeto JSON en stdout. Permite permitir, denegar, preguntar, reescribir la entrada o agregar contexto.
Simulador: ¿qué pasa si mi hook responde…?
Campos JSON universales
Campo
Efecto
continue: false
Detiene a Claude por completo después del hook (más fuerte que bloquear una acción).
stopReason
Mensaje que ve el usuario cuando continue es false.
systemMessage
Aviso que se muestra al usuario.
hookSpecificOutput.additionalContext
Texto que Claude lee como recordatorio del sistema. Debe ir dentro de hookSpecificOutput: arriba se ignora en silencio.
hookSpecificOutput.updatedInput
En PreToolUse: reescribe los argumentos de la herramienta antes de ejecutarla.
El texto plano de stdout (o additionalContext) entra al contexto de Claude
El error más comúnTu perfil de shell (~/.bashrc, ~/.zshrc) imprime algo como "Shell ready". Esa línea se antepone a tu JSON, ya no empieza con { y Claude Code lo ignora sin avisar. Envuelve esos echo en if [[ $- == *i* ]] o usa la forma exec con "args": [].
HOOKS · 8
Los cinco tipos de handler
Opciones comunes a todos
Campo
Para qué
timeout
Segundos. Por defecto: 600 en command/http/mcp_tool (30 en UserPromptSubmit y cambios de modelo), 30 en prompt, 60 en agent. Los SessionEnd comparten un presupuesto de 1,5 s.
if
Filtro con sintaxis de reglas de permiso (solo eventos de herramientas).
statusMessage
Texto que se muestra mientras corre.
async: true
(command) Corre en segundo plano sin bloquear. asyncRewake despierta a Claude cuando termina.
args: []
(command) Forma exec: lanza el ejecutable sin shell. Evita problemas de comillas y rutas con espacios.
onFailure: "block"
(command, http) Si el hook falla o expira, bloquea la acción en vez de dejarla pasar. Úsalo en guardrails críticos.
once: true
(solo en frontmatter de skills) Corre una vez por sesión.
Variables disponibles en los comandos: $CLAUDE_PROJECT_DIR (raíz del proyecto, úsala para rutas a scripts), ${CLAUDE_PLUGIN_ROOT} y ${CLAUDE_PLUGIN_DATA} en plugins, y $CLAUDE_ENV_FILE en SessionStart, CwdChanged y FileChanged para persistir variables de entorno en los siguientes comandos Bash.
HOOKS · 9
Recetario: 10 hooks listos para copiar
Las recetas más útiles de la documentación oficial, comentadas. Elige una.
Recetas
HOOKS · 10
Constructor de hooks
Arma tu hook eligiendo opciones; el JSON se genera solo y te dice dónde pegarlo.
Generador
AtajoTambién puedes describirlo en lenguaje natural con /update-config agrega un hook que… y Claude edita el settings correcto.
Ctrl+O abre el transcript: ahí ves bloqueos y avisos hook error. El éxito no muestra nada.
Para ver stdout, stderr y exit codes completos: claude --debug-file /tmp/claude.log y tail -f en otra terminal, o /debug a mitad de sesión.
Un hook Stop que bloquea 8 veces seguidas sin que Claude use herramientas es ignorado. Revisa stop_hook_active en la entrada y sal con 0 si es true.
SeguridadLos hooks de comando corren con tus permisos de usuario, sin sandbox. Revisa cualquier hook que venga en un repo clonado o un plugin antes de confiar en la carpeta. Usa rutas absolutas o $CLAUDE_PROJECT_DIR, cita variables ("$VAR"), valida la entrada y no imprimas secretos.
QUIZ
Quiz · Hooks
Siguiente: Skills
Empaqueta conocimiento y flujos que Claude carga cuando los necesita.