Los hooks son uno de los features menos conocidos de Claude Code y uno de los más poderosos. Te permiten ejecutar comandos de shell automáticamente antes o después de que Claude use cualquier herramienta. Guardarraíles sin fricción.

Qué son los hooks y para qué sirven

Un hook es un comando shell que Claude Code ejecuta en respuesta a eventos del agente. Eventos disponibles:

  • PreToolUse — antes de que Claude use una herramienta
  • PostToolUse — después de que Claude use una herramienta
  • Notification — cuando Claude quiere notificarte algo
  • Stop — cuando Claude termina una tarea

Casos de uso reales: ejecutar el linter después de cada edición, hacer un snapshot de git antes de cambios destructivos, bloquear ediciones en archivos protegidos, enviar notificaciones a Slack cuando el agente termina.

Configurar hooks en settings.json

Los hooks se configuran en ~/.claude/settings.json (global) o .claude/settings.json (proyecto):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npx eslint --fix $CLAUDE_FILE_PATHS 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

El matcher es una regex que coincide con el nombre de la herramienta. Write|Edit captura ambas herramientas de edición.

Variables de entorno disponibles

Claude Code expone variables útiles en cada hook:

  • $CLAUDE_PROJECT_DIR — directorio raíz del proyecto
  • $CLAUDE_FILE_PATHS — archivos afectados por la herramienta (separados por espacio)
  • $CLAUDE_TOOL_NAME — nombre de la herramienta que se ejecutó
  • $CLAUDE_SESSION_ID — ID de la sesión actual

Bloquear archivos protegidos

Puedes usar el exit code para bloquear acciones. Si el hook retorna exit code 2, Claude Code cancela la acción y muestra el stderr como mensaje de error:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_FILE_PATHS\" | grep -q 'production.env\\|\\.secrets'; then echo 'Archivo protegido: edición bloqueada' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

Hook para auto-commit tras cada tarea

Un pattern útil: hacer commit automático cuando Claude termina, para tener un historial granular de cada cambio del agente:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && git diff --quiet || git add -A && git commit -m 'chore: claude agent checkpoint'"
          }
        ]
      }
    ]
  }
}

Los hooks convierten a Claude Code en un agente auditable y controlado. Con unos pocos comandos shell defines exactamente qué puede y no puede hacer en tu proyecto.