Hooks
Система хуків Claude Code — PreToolUse, PostToolUse та Notification для автоматизації робочих процесів
📎ОФІЦІЙНА ДОКУМЕНТАЦІЯ
Що таке Hooks?
Hooks — це механізм Claude Code, який дозволяє автоматично виконувати дії до або після використання інструментів. Hooks працюють як middleware: вони перехоплюють виклики інструментів та можуть модифікувати поведінку агента.
Hooks виконуються самим Claude Code harness, а не моделлю. Це означає, що вони працюють детерміновано та надійно, незалежно від "рішень" AI.
Типи Hooks
PreToolUse
Виконується перед тим, як інструмент буде викликано. Може:
- Заблокувати виклик інструменту
- Модифікувати параметри
- Додати логування
- Виконати перевірки
PostToolUse
Виконується після завершення роботи інструменту. Може:
- Обробити результат
- Запустити додаткові дії (наприклад, автоформатування після запису файлу)
- Зібрати статистику
Notification
Виконується при відправці нотифікації користувачу. Може:
- Надсилати повідомлення в Slack або інші месенджери
- Логувати в зовнішню систему
- Відтворювати звуковий сигнал
Конфігурація Hooks
Hooks налаштовуються у файлі settings.json (глобально або на рівні проєкту):
Глобальні hooks
Файл: ~/.claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "echo 'Editing file: $CLAUDE_TOOL_INPUT_FILE_PATH'"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $CLAUDE_TOOL_INPUT_FILE_PATH"
}
]
}
],
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "terminal-notifier -message '$CLAUDE_NOTIFICATION_MESSAGE'"
}
]
}
]
}
}
Проєктні hooks
Файл: .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npx eslint --fix $CLAUDE_TOOL_INPUT_FILE_PATH 2>/dev/null || true"
}
]
}
]
}
}
Змінні середовища в Hooks
Claude Code надає спеціальні змінні середовища для використання в командах hooks:
| Змінна | Опис |
|---|---|
$CLAUDE_TOOL_INPUT_FILE_PATH | Шлях до файлу, з яким працює інструмент |
$CLAUDE_TOOL_INPUT | Повний JSON-вхід інструменту |
$CLAUDE_TOOL_OUTPUT | Вивід інструменту (тільки PostToolUse) |
$CLAUDE_NOTIFICATION_MESSAGE | Текст нотифікації (тільки Notification) |
$CLAUDE_PROJECT_DIR | Коренева директорія проєкту |
Практичні приклади
Автоформатування після запису файлу
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $CLAUDE_TOOL_INPUT_FILE_PATH 2>/dev/null || true"
}
]
}
]
}
}
Перевірка TypeScript перед комітом
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(git commit*)",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npx tsc --noEmit"
}
]
}
]
}
}
Заборона видалення важливих файлів
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(rm *)",
"hooks": [
{
"type": "command",
"command": "echo '$CLAUDE_TOOL_INPUT' | grep -q 'package.json\\|tsconfig' && exit 1 || exit 0"
}
]
}
]
}
}
Hook-команди повинні завершуватись швидко. Довгі операції сповільнять роботу Claude Code. Якщо hook повертає ненульовий exit code у PreToolUse, виклик інструменту буде заблоковано.
Slack-нотифікація при завершенні задачі
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "curl -s -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL -H 'Content-type: application/json' -d '{\"text\": \"Claude Code: '$CLAUDE_NOTIFICATION_MESSAGE'\"}'"
}
]
}
]
}
}
Matcher синтаксис
Matcher визначає, для якого інструменту спрацює hook:
| Matcher | Опис |
|---|---|
"Edit" | Точний збіг — тільки інструмент Edit |
"Bash(*)" | Будь-яка Bash-команда |
"Bash(npm *)" | Bash-команди, що починаються з npm |
"Write" | Тільки інструмент Write |
| Без matcher | Спрацьовує для всіх інструментів |
Debugging Hooks
Для відлагодження hooks використовуйте verbose mode:
claude --verbose
Це покаже, які hooks спрацьовують та їх результати.
Починайте з простих hooks (наприклад, логування) і поступово додавайте складнішу логіку. Завжди тестуйте hooks перед додаванням у продакшн-конфігурацію.
Система навичок — ще один спосіб розширити можливості Claude Code
Ефективне використання hooks та інших функцій