Hook в Claude Code — команда, которую приложение запускает в определённый момент сеанса. Это руководство добавляет один проектный SessionStart hook, который читает текущую ветку Git и передаёт короткую строку контекста при запуске или возобновлении разговора. В основе — актуальный справочник Anthropic по hook, проверенный 19 октября 2026 года. BIG CHANGE проверил скрипт напрямую через Node и проверил JSON настроек; мы не запускали hook в Claude Code и не тестировали ответ модели.
Главная перемена
- Что изменилось: Этот проектный
SessionStarthook передаёт короткую строку с веткой Git, когда Claude Code запускает или возобновляет разговор. - Почему это важно: Текущая ветка попадает в контекст сеанса при запуске или возобновлении без ручной вставки каждый раз.
- На что обратить внимание: Контекст не обеспечивает соблюдение правила и не гарантирует ответ модели. Проверьте фактическую передачу при запуске и возобновлении в собственном доверенном проекте.
Перед установкой
Используйте проект Git, который вам разрешено изменять. Claude Code, Node.js и Git должны быть доступны в одном терминале; также нужно разрешение изменять проектный файл .claude/settings.json. Проверьте node --version, git --version и claude --version. На компьютере подготовки были Claude Code 2.1.301 и Node 24.19.0; эти наблюдаемые версии не являются минимальными требованиями.
Проверьте название ветки перед отправкой модели. Оно может содержать имя клиента, номер обращения или название инцидента. Фильтрация символов и сокращение строки не убирают этот смысл. Устанавливайте пример только при разрешении использовать название ветки в контексте модели. Иначе измените скрипт, чтобы он выводил разрешённый статус без чувствительных данных, и проверьте изменение перед установкой. Документация Anthropic об использовании данных объясняет обработку данных сервисом; учитывайте и разрешения своего проекта.
Команды hook выполняются с вашими пользовательскими правами. Перед включением изучите существующие проектные и пользовательские hook, политику организации и весь скрипт. Проектные настройки могут попасть в репозиторий; .claude/settings.local.json остаётся локальным. Пример использует файл проектных настроек, чтобы конфигурация действовала в пределах этого проекта.
Установите два файла
- Создайте
.claude/hooks/внутри проекта. Сохраните весь блок как.claude/hooks/session-context.cjs:
'use strict';
const { execFileSync } = require('node:child_process');
const project = process.env.CLAUDE_PROJECT_DIR;
if (!project) {
process.stderr.write('CLAUDE_PROJECT_DIR is unavailable\n');
process.exit(1);
}
try {
const raw = execFileSync('git', ['-C', project, 'branch', '--show-current'], {
encoding: 'utf8',
timeout: 1500,
maxBuffer: 4096,
stdio: ['ignore', 'pipe', 'pipe'],
}).trim();
const branch = raw ? raw.replace(/[^A-Za-z0-9._/-]/g, '_').slice(0, 80) : 'detached HEAD';
process.stdout.write(`Current project branch: ${branch}\n`);
} catch {
process.stderr.write('Could not read the project branch; check Git and project path\n');
process.exit(1);
}Для дочернего процесса Git установлены тайм-аут 1,5 секунды и буфер вывода 4096 байт. Пустой результат ветки, например при detached HEAD, заменяется на detached HEAD. Отсутствующий путь проекта или ошибка Git дают короткое сообщение в stderr и код завершения 1.
- Откройте существующий файл
.claude/settings.json. Объедините записьhooks.SessionStartниже с другими настройками и группами hook, сохранив имеющиеся записи. Блок показывает полныйsettings.example.jsonиз проверенного пакета. Если в файле уже есть записиSessionStart, добавьте эту группу в их массив вместо замены массива.
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume",
"hooks": [
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
"timeout": 5
}
]
}
]
}
}Matcher охватывает новый и возобновлённый сеанс. Anthropic также описывает clear, compact и fork как источники SessionStart ; пример намеренно их исключает. Поле args выбирает форму exec: Claude Code вызывает node с вычисленным путём проектного скрипта в качестве одного аргумента, без кавычек и разбора командной оболочкой. В Windows node.exe должен разрешаться в исполняемый файл; прослойка .cmd не подходит для формы exec. Пятисекундный тайм-аут hook-команды отделён от 1,5-секундного тайм-аута Git в скрипте.
Проверьте скрипт, затем Claude Code
- Прежде чем открывать Claude Code, запустите скрипт в терминале проекта и сравните вывод с Git. В PowerShell:
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-currentВ Bash:
CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-currentОжидайте ровно одну строку stdout скрипта, Current project branch: BRANCH, где BRANCH — результат Git после фильтрации символов и ограничения до 80 символов. При detached HEAD выводится Current project branch: detached HEAD. Прямая проверка подтверждает только работу локального скрипта в этом терминале. В нашей подготовительной проверке обычная ветка совпала с результатом Git; отсутствующие и неверные пути проекта дали пустой stdout, диагностику в stderr и код 1. Ограничение длинного имени и запасной вариант detached HEAD мы изучили в исходном коде, но эти случаи не выполняли.
- Запустите новый интерактивный процесс Claude Code в доверенном проекте с
claude --debug-file STARTUP_PRIVATE_LOG, используя подконтрольный вам приватный путь. Перед подтверждением доверия рабочему пространству изучите проектные и пользовательские hook. Найдите в отладочном журнале событиеSessionStartс источникомstartup, выбранным путём скрипта, кодом завершения и обработкой вывода. Спросите Claude, какой контекст ветки он получил, не разрешая инструменты или самостоятельное чтение Git. Сравните ответ и отладочную запись с прямым результатом. Stdout hook поступает в контекст Claude; отображение отдельным сообщением в интерфейсе не обещано. - Выйдите из сеанса. Возобновите его в отдельном процессе с
claude --debug-file RESUME_PRIVATE_LOG --resume, затем проверьте событиеSessionStartresumeи повторите проверку запросом без инструментов или повторного чтения Git. Оба отладочных журнала храните приватно: они могут раскрывать детали проекта. Неинтерактивный запуск-pили SDK не показывает того же запроса доверия рабочему пространству и может автоматически выполнить hook репозитория, поэтому используйте интерактивный процесс. Anthropic сообщает, что наблюдатель файлов обычно подхватывает изменения настроек hook, но новый процесс даёт более ясную проверку запуска и возобновления.
Если обычная работа позднее изменит ветку, повторите прямую проверку и новый сеанс, чтобы увидеть изменение строки. Не переключайте ветки только ради утверждения, что руководство протестировано.
Если не запускается
Начните с прямого результата скрипта, затем проверьте объединение JSON, написание SessionStart , matcher startup|resume , путь корня проекта, доступность node и git, доверие рабочему пространству и ошибки отладки. При отсутствии CLAUDE_PROJECT_DIR выводится CLAUDE_PROJECT_DIR is unavailable в stderr. Неверный путь проекта или ошибка Git выводят Could not read the project branch; check Git and project path. Оба случая завершаются с кодом 1 без строки контекста. Ошибка SessionStart носит диагностический характер и не блокирует работу; она не может служить условием допуска действия. Anthropic описывает PreToolUse для управления действием инструмента; это другое событие, требующее отдельно проверенного решения.
Скрипт запускает только локальный Git и не делает сетевых запросов или вызовов модели. Запуск Claude Code, возобновление и проверочные запросы могут расходовать лимиты аккаунта, провайдера или модели; руководство Anthropic по расходам содержит текущие условия. Здесь не устанавливается фиксированная цена и не заявлен платный тест сеанса.
Для отдельной задачи после начала разговора наше руководство по просмотру контекста и продолжению сеанса Claude Code описывает просмотр контекста и продолжение. Оно не настраивает этот hook запуска.
Источники и дополнительное чтение
- Anthropic, справочник hook Claude Code — Актуальная первичная спецификация проверена 19 октября 2026 года. Описывает
SessionStartисточники и matcher, форму execargs, подстановки пути, контекст stdout, перезагрузку настроек, доверие, журналы отладки и неблокирующие ошибки. Это документация, а не запуск hook компанией BIG CHANGE. - Anthropic, автоматизация действий через hook — Официальное руководство по настройке и тестированию hook. Приведённые скрипт и настройки — ограниченный пример BIG CHANGE, проверенный для этой статьи, а не скопированный результат теста поставщика.
- Anthropic, настройка Claude Code — Требования к установке и окружению. Перед использованием примера проверьте актуальные инструкции для платформы.
- Anthropic, использование данных в Claude Code — Текущие условия провайдера по обработке данных для проверки перед передачей сведений о ветке в контекст модели; разрешение проекта остаётся отдельным решением.
- Anthropic, эффективное управление расходами — Текущие рекомендации по аккаунту и использованию для интерактивных проверок. Сам локальный скрипт Git не обращается к модели или сети.
