Система хуков

Настройка поведения Claude Code через хуки — автоформатирование, перехват опасных команд, уведомления и многое другое

Система хуков¶

Хуки позволяют встраивать пользовательскую логику в ключевые точки жизненного цикла Claude Code — например, автоматическое форматирование кода, перехват опасных команд, отправку уведомлений и т. д.

Основные понятия¶

Каждый хук состоит из трёх частей:

• Событие: момент срабатывания (например, PreToolUse — перед выполнением инструмента)

• Фильтр (matcher): необязательный фильтр по имени инструмента (например, только Bash или Write)

• Обработчик: shell-команда, промпт или субагент

Основные события¶

Настройка¶

Добавьте хуки в .claude/settings.json (уровень проекта) или ~/.claude/settings.json (уровень пользователя):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}

Практические примеры¶

1. Автоформатирование после сохранения файла¶

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}

2. Перехват опасных shell-команд¶

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo $TOOL_INPUT | grep -qE 'rm -rf|sudo|git push --force' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

exit 2 блокирует выполнение инструмента, exit 0 разрешает продолжение.

3. Защита конфиденциальных файлов от чтения¶

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "echo $TOOL_INPUT | grep -qE '\\.env|credentials|secret' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

4. Отправка уведомления по завершении задачи¶

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"$NOTIFICATION_MESSAGE\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Механизм ввода/вывода¶

• Скрипт хука получает JSON-данные через stdin (содержат session_id, tool_name, tool_input)

• Переменные окружения: $FILEPATH, $TOOL_INPUT, $NOTIFICATION_MESSAGE и другие

• Exit code для PreToolUse: 0 = разрешить, 2 = заблокировать

Советы по отладке¶

• Нажмите Ctrl+O для включения verbose-режима — вы увидите stdout/stderr хуков

• Перед подключением хука протестируйте скрипт вручную в терминале

Примечания¶

• Скрипты хуков не должны выполняться слишком долго, иначе они заблокируют взаимодействие с Claude Code

• Хуки уровня проекта имеют приоритет над хуками уровня пользователя

• В Enterprise-версии можно принудительно задать хуки безопасности для всей организации через managed-settings.json

Следующие шаги¶

• Смотрите Навыки (Skills) для более продвинутых способов расширения

• Смотрите MCP-серверы для интеграции внешних инструментов

• Смотрите Советы по CLI для приёмов работы с командной строкой