Le venís diciendo a Claude Code que corra tus tests después de cada cambio. Lo pusiste en el CLAUDE.md. Lo repetiste en los prompts. Y a veces lo hace. Y a veces no.
Eso es exactamente el problema que resuelven los hooks.
Los hooks convierten tus recomendaciones en cumplimiento garantizado. No “Claude, por favor corré el linter” — sino una regla que se dispara automáticamente, siempre, sin importar lo que Claude decida. Eso es una categoría diferente de control.
¿Qué son los Hooks, exactamente?
Los hooks son comandos de shell (o prompts, o agentes) definidos por vos que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code. Anthropic los introdujo a mediados de 2025 y desde entonces son uno de los features más poderosos y menos usados de la herramienta.
La diferencia clave con CLAUDE.md:
- CLAUDE.md / prompts: guías que Claude debería seguir. No deterministas.
- Hooks: comandos que van a ejecutarse, siempre, sin excepciones.
Si alguna vez viste a Claude saltarse un paso que le pediste explícitamente, los hooks son la solución.
Los Eventos del Lifecycle
Claude Code expone múltiples puntos donde los hooks pueden dispararse. Los más importantes:
| Evento | Cuándo se ejecuta |
|---|---|
PreToolUse |
Antes de que Claude ejecute cualquier herramienta — puede bloquear la acción |
PostToolUse |
Después de que una herramienta completa exitosamente |
Stop |
Cuando Claude termina su respuesta |
Notification |
Cuando Claude necesita tu atención (idle, pedido de permiso, etc.) |
SessionStart |
Al inicio de una nueva sesión |
UserPromptSubmit |
Cuando enviás un prompt, antes de que Claude lo procese |
TaskCompleted |
Cuando una tarea se marca como completada (nuevo en 2026) |
El crítico es PreToolUse. Es el único hook que puede bloquear una acción. Si tu hook retorna una señal de rechazo, Claude no puede continuar. Todo lo demás es reactivo. PreToolUse es preventivo.
Tres Tipos de Handlers
Claude Code soporta tres tipos de handlers, cada uno adecuado para distintas necesidades:
1. Command hooks — Ejecutan un comando de shell, reciben pass/fail de vuelta
json
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"handler": {
"type": "command",
"command": "npx prettier --write $FILEPATH"
}
}]
}
}
2. Prompt hooks — Usan un modelo Claude para evaluar condiciones semánticamente (para decisiones que necesitan criterio, no solo pattern matching)
3. Agent hooks — Invocan un agente Claude completo con acceso a herramientas para análisis profundo
Empezá con command hooks. Son los más predecibles y más fáciles de debuggear. Subí a prompt o agent hooks cuando necesitás razonamiento semántico.
Primeros pasos: el menú /hooks
La forma más rápida de configurar tu primer hook es a través del menú interactivo — sin editar JSON:
bash
# Dentro de Claude Code
/hooks
Vas a ver todos los eventos disponibles. Seleccioná uno, configurá un matcher (usá * para todo, o reducilo a una herramienta específica), e ingresá un comando de shell. El menú pregunta dónde guardar — elegí User settings para aplicar a todos tus proyectos, o Project settings para el repo actual.
4 Hooks Prácticos para Agregar Hoy
1. Auto-format en cada edición de archivo
Cada vez que Claude edita o escribe un archivo, tu formatter corre automáticamente:
json
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write|MultiEdit",
"handler": {
"type": "command",
"command": ".claude/hooks/auto-format.sh"
}
}]
}
}
bash
# .claude/hooks/auto-format.sh
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
EXT="${FILE##*.}"
case "$EXT" in
js|ts|tsx|json) npx prettier --write "$FILE" ;;
py) black --quiet "$FILE" ;;
go) gofmt -w "$FILE" ;;
esac
exit 0
2. Firewall de seguridad — bloquea comandos peligrosos
Usá PreToolUse para interceptar y denegar comandos de shell que coincidan con patrones peligrosos:
json
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"handler": {
"type": "command",
"command": ".claude/hooks/security-guard.sh"
}
}]
}
}
bash
# .claude/hooks/security-guard.sh
COMMAND=$(cat | jq -r '.tool_input.command // empty')
DANGEROUS=('rm\s+-rf\s+/' 'curl.*\|\s*bash' 'mkfs\.' 'chmod\s+-R\s+777\s+/')
for pattern in "${DANGEROUS[@]}"; do
if echo "$COMMAND" | grep -qE "$pattern"; then
jq -n --arg r "Bloqueado: patrón peligroso detectado" \
'{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'
exit 0
fi
done
exit 0
3. Notificación de escritorio cuando Claude necesita input
Nunca más te quedés mirando el terminal esperando:
bash
# macOS
osascript -e 'display notification "Claude Code necesita tu atención" with title "Claude Code"'
Configuralo como hook Notification en el menú /hooks con matcher *.
4. Requerí que los tests pasen antes de cualquier PR
Bloqueá a Claude de crear un pull request hasta que los tests estén en verde:
bash
# .claude/hooks/require-tests-for-pr.sh
if npm test -- --reporter=dot; then
exit 0
else
echo "Los tests están fallando. Arreglalos antes de crear un PR." >&2
exit 2
fi
Configuralo como hook PreToolUse con matcher mcp__github__create_pull_request.
Equipos y Enterprise: Hooks como Capa de Guardarraíles
Acá es donde los hooks se vuelven genuinamente importantes a escala.
Cuando guardás los hooks en .claude/settings.json en la raíz del proyecto y lo commiteás al repositorio, cada desarrollador del equipo hereda las mismas reglas automáticamente. Sin onboarding, sin documentación que recordar, sin “me olvidé de correr el linter.”
Para equipos enterprise, esto significa:
- Cumplimiento de seguridad: Bloqueá modificaciones en directorios protegidos. Impedí que se escriban credenciales en archivos. Denegá patrones de shell asociados a errores comunes.
- Audit logging: Cada comando Bash que corre Claude queda logueado con timestamps — crítico para compliance y revisión post-incidente.
- Quality gates: Ningún PR se crea si los tests no pasan. Ningún commit pasa si el lint falla.
- HTTP hooks: En vez de correr scripts locales, podés apuntar los hooks a un endpoint del equipo que aplica políticas de la organización — un solo lugar para actualizar reglas que se propagan a todas las sesiones de todos los desarrolladores.
json
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"handler": {
"type": "http",
"url": "https://tu-servidor-equipo/hooks/security-check",
"timeout": 30,
"headers": { "Authorization": "Bearer $TEAM_TOKEN" }
}
}]
}
}
La diferencia entre un equipo que usa Claude Code con hooks y uno sin ellos: uno tiene estándares deterministas, el otro tiene intenciones.
Dónde Viven los Hooks
| Archivo | Alcance |
|---|---|
~/.claude/settings.json |
Todos tus proyectos, solo en tu máquina |
.claude/settings.json |
Este proyecto — commitealo para compartir con el equipo |
.claude/settings.local.json |
Este proyecto, solo en tu máquina (no lo commitees) |
Aprendé Más: El Curso Oficial Gratuito de Anthropic
Si querés ir más allá de los hooks y entender la arquitectura completa de Claude Code — manejo de contexto, tool chaining, integración MCP, conceptos del SDK — Anthropic tiene un curso oficial gratuito llamado Claude Code in Action, disponible en su plataforma Skilljar en anthropic.skilljar.com/claude-code-in-action.
Es gratuito, toma pocas horas, cubre los hooks explícitamente, y al finalizar otorga un certificado oficial de Anthropic que podés agregar a tu perfil de LinkedIn. Para desarrolladores que quieren demostrar conocimiento profesional de Claude Code, es la única credencial oficial disponible en este momento.
También está disponible en Coursera si preferís ese ecosistema.
El Modelo Mental para Llevarte
Los hooks responden una sola pregunta: ¿qué debería pasar siempre, sin importar lo que Claude decida?
Tu formatter debería correr siempre. Tus verificaciones de seguridad deberían bloquear siempre. Los tests deberían pasar siempre antes de que salga un PR.
Esas cosas van en hooks. Todo lo demás va en CLAUDE.md.
Esa combinación — cumplimiento determinista para lo no-negociable, guías para todo lo demás — es cómo construís un workflow de Claude Code en el que realmente podés confiar a escala.
¿Ya estás usando hooks en tus proyectos? ¿Cuál es el hook que más impacto tuvo en tu flujo? Contanos en los comentarios.