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

Для справочной документации по хукам см. Справочник по хукам.

Примеры случаев использования хуков включают:

  • Уведомления: Настройте способ получения уведомлений, когда Claude Code ожидает ваш ввод или разрешение на выполнение чего-либо.
  • Автоматическое форматирование: Запускайте prettier для .ts файлов, gofmt для .go файлов и т.д. после каждого редактирования файла.
  • Логирование: Отслеживайте и подсчитывайте все выполненные команды для соответствия требованиям или отладки.
  • Обратная связь: Предоставляйте автоматизированную обратную связь, когда Claude Code создает код, который не соответствует соглашениям вашей кодовой базы.
  • Пользовательские разрешения: Блокируйте изменения в производственных файлах или чувствительных каталогах.

Кодируя эти правила как хуки, а не как инструкции в промптах, вы превращаете предложения в код уровня приложения, который выполняется каждый раз, когда ожидается его запуск.

Вы должны учитывать последствия хуков для безопасности при их добавлении, поскольку хуки запускаются автоматически во время цикла агента с учетными данными вашей текущей среды. Например, вредоносный код хуков может похитить ваши данные. Всегда проверяйте реализацию ваших хуков перед их регистрацией.

Для полного ознакомления с лучшими практиками безопасности см. Соображения безопасности в справочной документации по хукам.

​
Обзор событий хуков

Claude Code предоставляет несколько событий хуков, которые запускаются в разных точках рабочего процесса:

  • PreToolUse: Запускается перед вызовами инструментов (может их блокировать)
  • PostToolUse: Запускается после завершения вызовов инструментов
  • Notification: Запускается, когда Claude Code отправляет уведомления
  • Stop: Запускается, когда Claude Code завершает ответ
  • Subagent Stop: Запускается, когда завершаются задачи подагента

Каждое событие получает разные данные и может контролировать поведение Claude разными способами.

​
Быстрый старт

В этом быстром старте вы добавите хук, который логирует команды оболочки, которые выполняет Claude Code.

​
Предварительные требования

Установите jq для обработки JSON в командной строке.

​
Шаг 1: Откройте конфигурацию хуков

Выполните слэш-команду /hooks и выберите событие хука PreToolUse.

Хуки PreToolUse запускаются перед вызовами инструментов и могут их блокировать, предоставляя Claude обратную связь о том, что делать по-другому.

​
Шаг 2: Добавьте сопоставитель

Выберите + Add new matcher…, чтобы запускать ваш хук только для вызовов инструмента Bash.

Введите Bash для сопоставителя.

Вы можете использовать * для сопоставления всех инструментов.

​
Шаг 3: Добавьте хук

Выберите + Add new hook… и введите эту команду:

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​
Шаг 4: Сохраните вашу конфигурацию

Для места хранения выберите User settings, поскольку вы логируете в ваш домашний каталог. Этот хук будет применяться ко всем проектам, а не только к вашему текущему проекту.

Затем нажмите Esc, пока не вернетесь к REPL. Ваш хук теперь зарегистрирован!

​
Шаг 5: Проверьте ваш хук

Снова выполните /hooks или проверьте ~/.claude/settings.json, чтобы увидеть вашу конфигурацию:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​
Шаг 6: Протестируйте ваш хук

Попросите Claude выполнить простую команду, например ls, и проверьте ваш файл логов:

cat ~/.claude/bash-command-log.txt

Вы должны увидеть записи вроде:

ls - Lists files and directories

​
Больше примеров

Для полного примера реализации см. пример валидатора команд bash в нашей публичной кодовой базе.

​
Хук форматирования кода

Автоматически форматируйте файлы TypeScript после редактирования:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

​
Хук пользовательских уведомлений

Получайте уведомления на рабочем столе, когда Claude нужен ввод:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Awaiting your input'"
          }
        ]
      }
    ]
  }
}

​
Хук защиты файлов

Блокируйте редактирование чувствительных файлов:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

​
Узнать больше

  • Для справочной документации по хукам см. Справочник по хукам.
  • Для всеобъемлющих лучших практик безопасности и руководящих принципов безопасности см. Соображения безопасности в справочной документации по хукам.
  • Для шагов по устранению неполадок и техник отладки см. Отладка в справочной документации по хукам.