Автоматизация рабочих процессов с помощью hooks

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Настройка вашего первого hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

Что вы можете автоматизировать

• Получайте уведомления, когда Claude требует ввода
• Автоматическое форматирование кода после редактирования
• Блокировка редактирования защищённых файлов
• Повторное внедрение контекста после компактирования
• Аудит изменений конфигурации
• Перезагрузка окружения при изменении каталога или файлов
• Автоматическое одобрение определённых запросов разрешений

​

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

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

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

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Автоматическое форматирование кода после редактирования

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

Блокировка редактирования защищённых файлов

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Повторное внедрение контекста после компактирования

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Аудит изменений конфигурации

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Перезагрузка окружения при изменении каталога или файлов

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Автоматическое одобрение определённых запросов разрешений

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Как работают hooks

• "type": "http": POST данные события на URL. См. HTTP hooks.
• "type": "mcp_tool": вызвать инструмент на уже подключённом MCP сервере. См. MCP tool hooks.
• "type": "prompt": однооборотная оценка LLM. См. Prompt-based hooks.
• "type": "agent": многооборотная проверка с доступом к инструментам. Agent hooks являются экспериментальными и могут измениться. См. Agent-based hooks.

​

Объединение результатов из нескольких hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

Чтение ввода и возврат вывода

​

Ввод hook

{
  "session_id": "abc123",          // уникальный ID для этого сеанса
  "cwd": "/Users/sarah/myproject", // рабочий каталог при срабатывании события
  "hook_event_name": "PreToolUse", // какое событие запустило этот hook
  "tool_name": "Bash",             // инструмент, который Claude собирается использовать
  "tool_input": {                  // аргументы, которые Claude передал инструменту
    "command": "npm test"          // для Bash это команда оболочки
  }
}

​

Вывод hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr становится обратной связью Claude
  exit 2 # exit 2 = блокировать действие
fi

exit 0  # exit 0 = позволить продолжить

• Exit 0: действие продолжается. Для hooks UserPromptSubmit, UserPromptExpansion и SessionStart всё, что вы пишете в stdout, добавляется в контекст Claude.
• Exit 2: действие блокируется. Напишите причину в stderr, и Claude получит её как обратную связь, чтобы он мог скорректировать. Некоторые события не могут быть заблокированы: для SessionStart, Setup, Notification и других, exit 2 показывает stderr пользователю и выполнение продолжается. См. exit code 2 behavior per event для полного списка.
• Любой другой код выхода: действие продолжается. Стенограмма показывает уведомление об ошибке <hook name> hook error, за которым следует первая строка stderr; полный stderr переходит в debug log.

​

Структурированный вывод JSON

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow": пропустить интерактивный запрос разрешения. Правила отказа и запроса, включая управляемые списки отказов предприятия, по-прежнему применяются
• "deny": отменить вызов инструмента и отправить причину Claude
• "ask": показать запрос разрешения пользователю как обычно

​

Фильтрация hooks с помощью matchers

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Фильтрация по имени инструмента и аргументам с помощью поля if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Настройка местоположения hook

​

Hooks на основе подсказок

• "ok": true: действие продолжается
• "ok": false: что происходит, зависит от события:
  • Stop и SubagentStop: значение reason передаётся обратно Claude, чтобы он продолжал работать
  • PreToolUse: вызов инструмента отклоняется и значение reason возвращается Claude как ошибка инструмента, чтобы он мог скорректировать и продолжить
  • PostToolUse, PostToolBatch, UserPromptSubmit и UserPromptExpansion: ход завершается и значение reason появляется в чате как строка предупреждения

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks на основе агентов

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Ограничения и устранение неполадок

​

Ограничения

• Command hooks взаимодействуют только через stdout, stderr и коды выхода. Они не могут запускать команды / или вызовы инструментов. Текст, возвращённый через additionalContext, внедряется как системное напоминание, которое Claude читает как простой текст. HTTP hooks взаимодействуют через тело ответа вместо этого.
• Время ожидания hook варьируется в зависимости от типа. Переопределите для каждого hook с помощью поля timeout в секундах.
  • command, http, mcp_tool: 10 минут. UserPromptSubmit снижает эти значения до 30 секунд.
  • prompt: 30 секунд.
  • agent: 60 секунд.
• Hooks PostToolUse не могут отменить действия, так как инструмент уже выполнен.
• Hooks PermissionRequest не срабатывают в неинтерактивном режиме (-p). Используйте hooks PreToolUse для автоматизированных решений разрешений.
• Hooks Stop срабатывают всякий раз, когда Claude завершает ответ, а не только при завершении задачи. Они не срабатывают при прерывании пользователем. Ошибки API срабатывают StopFailure вместо этого.
• Когда несколько hooks PreToolUse возвращают updatedInput для переписания аргументов инструмента, последний завершённый побеждает. Поскольку hooks запускаются параллельно, порядок недетерминирован. Избегайте наличия более одного hook, изменяющего ввод одного и того же инструмента.

​

Hooks и режимы разрешений

​

Hook не срабатывает

• Запустите /hooks и подтвердите, что hook появляется под правильным событием
• Проверьте, что шаблон matcher точно соответствует имени инструмента (matchers чувствительны к регистру)
• Убедитесь, что вы запускаете правильный тип события (например, PreToolUse срабатывает перед выполнением инструмента, PostToolUse срабатывает после)
• Если используете hooks PermissionRequest в неинтерактивном режиме (-p), переключитесь на PreToolUse вместо этого

​

Ошибка hook в выводе

• Ваш скрипт неожиданно вышел с ненулевым кодом. Протестируйте его вручную, передав образец JSON:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Проверьте код выхода
  
• Если вы видите “command not found”, используйте абсолютные пути или ${CLAUDE_PROJECT_DIR} для ссылки на скрипты. Чтобы полностью избежать экранирования оболочки, добавьте "args": [] для переключения на exec form, который порождает скрипт напрямую без оболочки
• Если вы видите “jq: command not found”, установите jq или используйте Python/Node.js для анализа JSON
• Если скрипт вообще не запускается, сделайте его исполняемым: chmod +x ./my-hook.sh

​

/hooks показывает, что hooks не настроены

• Редактирования файлов обычно подхватываются автоматически. Если они не появились через несколько секунд, наблюдатель файлов мог пропустить изменение: перезагрузите сеанс для принудительной перезагрузки.
• Убедитесь, что ваш JSON действителен (конечные запятые и комментарии не допускаются)
• Подтвердите, что файл параметров находится в правильном месте: .claude/settings.json для hooks проекта, ~/.claude/settings.json для глобальных hooks

​

Stop hook работает вечно

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Позволить Claude остановиться
fi
# ... остальная логика вашего hook

​

Ошибка валидации JSON

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# В ~/.zshrc или ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Методы отладки

​

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

• Справочник Hooks: полные схемы событий, формат вывода JSON, асинхронные hooks и MCP tool hooks
• Соображения безопасности: просмотрите перед развёртыванием hooks в общих или производственных средах
• Пример валидатора команд Bash: полная справочная реализация