Что такое хуки Claude Code?
Хуки Claude Code — это команды оболочки, которые автоматически выполняются в определённые моменты жизненного цикла агента, например перед запуском инструмента или в конце хода. Поскольку они срабатывают каждый раз и не зависят от модели, это надёжный способ обеспечивать правила и добавлять проверки.
События
Хуки описываются в файлах settings.json и привязываются к событию. Для событий инструментов matcher позволяет выбирать конкретные инструменты, например Bash или Edit.
- PreToolUse: перед запуском инструмента; может заблокировать вызов.
- PostToolUse: после завершения инструмента, например чтобы отформатировать изменённый файл.
- UserPromptSubmit: до того, как ваше сообщение дойдёт до модели.
- Stop: когда агент завершает ход.
- SessionStart: когда начинается сессия, удобно для добавления контекста.
- Notification: когда Claude Code отправляет уведомление.
Как это работает
Команда хука получает данные о событии, такие как имя инструмента и его ввод, в виде JSON на стандартный ввод. Код завершения подсказывает Claude Code, что делать: 0 значит продолжать, а 2 блокирует действие и передаёт сообщение об ошибке модели. Для более тонкого управления хук может вернуть решение и причину в виде JSON.
Для чего их используют
Хуки превращают в правило всё, что модель может забыть.
- Блокировка опасных команд или чтения файлов вроде .env.
- Запуск форматтера или линтера после каждой правки.
- Переписывание команд, чтобы их вывод был короче.
- Отправка уведомления или запуск тестов в конце хода.
На что обратить внимание
Хуки выполняются с правами вашего пользователя и без вопросов, поэтому не добавляйте чужой хук, не прочитав его. Медленный хук замедляет каждый вызов инструмента, так что делайте их быстрыми. Текст, который возвращает хук, может попасть в контекст модели, поэтому держите его коротким.
Хуки в AgentVera
AgentVera реализует несколько своих функций как хуки в агентах Claude Code. Профиль Lean context, напротив, не загружает пользовательские хуки.
- Smart tools: четыре хука, которые блокируют повторное чтение файлов, сужают полный запуск тестов до затронутых тестов, сообщают о новых ошибках типов сразу после правки и делят результат команды между агентами. Все включены по умолчанию.
- RTK: команды Bash в Claude Code через хук переписываются в версии с более коротким выводом (git status → rtk git status).
- У Codex нет хуков, поэтому RTK работает там через инструкции, а smart tools работают только в локальных агентах Claude Code.
FAQ
Где настраиваются хуки Claude Code?
В файлах settings.json: ~/.claude/settings.json для вашего пользователя, .claude/settings.json для проекта и .claude/settings.local.json только для вашего компьютера. Управлять ими можно и командой /hooks.
Как хук блокирует команду?
Если хук PreToolUse завершается с кодом 2, вызов инструмента блокируется, а вывод ошибки хука передаётся модели как причина.
Безопасны ли хуки?
Хуки — это команды оболочки, выполняемые с вашими правами, так что они безопасны настолько, насколько безопасно их содержимое. Читайте хуки проекта, пришедшие с репозиторием, прежде чем запускать их.
Чем хук отличается от навыка (skill)?
Хук — команда, которая выполняется каждый раз при наступлении события; модель не решает. Навык — набор инструкций и файлов, который модель загружает, когда считает его уместным.