Версия Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# Добавьте ограниченный проектный hook для контекста при запуске сеанса Claude Code

> Установите небольшой проектный SessionStart hook, добавляющий текущую ветку Git в контекст Claude Code. Проверьте прямой вывод, запуск, возобновление и поведение при ошибке.

By BIG CHANGE Editorial

Published: 2026-10-20T00:22:54.831Z
Updated: 2026-10-20T00:22:54.831Z
Canonical: https://bigchange.ai/blog/claude-code-session-start-branch-context-hook-guide

![Conceptual charcoal illustration of an unbranded desktop monitor with one short orange stroke above two soft charcoal strokes; a keyboard rests in front.](https://bigchange.ai/api/media/file/claude-code-session-start-context-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no actual Claude Code interface, hook execution or model result is depicted.

Hook в Claude Code — команда, которую приложение запускает в определённый момент сеанса. Это руководство добавляет один проектный `SessionStart` hook, который читает текущую ветку Git и передаёт короткую строку контекста при запуске или возобновлении разговора. В основе — [актуальный справочник Anthropic по hook](https://code.claude.com/docs/en/hooks), проверенный 19 октября 2026 года. BIG CHANGE проверил скрипт напрямую через Node и проверил JSON настроек; мы не запускали hook в Claude Code и не тестировали ответ модели.

## Главная перемена

- **Что изменилось:** Этот проектный `SessionStart` hook передаёт короткую строку с веткой 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 об использовании данных](https://code.claude.com/docs/en/data-usage) объясняет обработку данных сервисом; учитывайте и разрешения своего проекта.

Команды hook выполняются с вашими пользовательскими правами. Перед включением изучите существующие проектные и пользовательские hook, политику организации и весь скрипт. Проектные настройки могут попасть в репозиторий; `.claude/settings.local.json` остаётся локальным. Пример использует файл проектных настроек, чтобы конфигурация действовала в пределах этого проекта.

## Установите два файла

1. Создайте `.claude/hooks/` внутри проекта. Сохраните весь блок как `.claude/hooks/session-context.cjs`:

```javascript
'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.

2. Откройте существующий файл `.claude/settings.json`. Объедините запись `hooks.SessionStart` ниже с другими настройками и группами hook, сохранив имеющиеся записи. Блок показывает полный `settings.example.json` из проверенного пакета. Если в файле уже есть записи `SessionStart` , добавьте эту группу в их массив вместо замены массива.

```json
{
  "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

3. Прежде чем открывать Claude Code, запустите скрипт в терминале проекта и сравните вывод с Git. В PowerShell:

```powershell
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current
```

В Bash:

```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 мы изучили в исходном коде, но эти случаи не выполняли.

4. Запустите новый **интерактивный** процесс Claude Code в доверенном проекте с `claude --debug-file STARTUP_PRIVATE_LOG`, используя подконтрольный вам приватный путь. Перед подтверждением доверия рабочему пространству изучите проектные и пользовательские hook. Найдите в отладочном журнале событие `SessionStart` с источником `startup`, выбранным путём скрипта, кодом завершения и обработкой вывода. Спросите Claude, какой контекст ветки он получил, не разрешая инструменты или самостоятельное чтение Git. Сравните ответ и отладочную запись с прямым результатом. Stdout hook поступает в контекст Claude; отображение отдельным сообщением в интерфейсе не обещано.
5. Выйдите из сеанса. Возобновите его в отдельном процессе с `claude --debug-file RESUME_PRIVATE_LOG --resume`, затем проверьте событие `SessionStart` `resume` и повторите проверку запросом без инструментов или повторного чтения 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 по расходам](https://code.claude.com/docs/en/costs) содержит текущие условия. Здесь не устанавливается фиксированная цена и не заявлен платный тест сеанса.

Для отдельной задачи после начала разговора наше [руководство по просмотру контекста и продолжению сеанса Claude Code](https://bigchange.ai/blog/claude-code-session-context-continue-guide) описывает просмотр контекста и продолжение. Оно не настраивает этот hook запуска.

## Источники и дополнительное чтение

- [Anthropic, справочник hook Claude Code](https://code.claude.com/docs/en/hooks) — Актуальная первичная спецификация проверена 19 октября 2026 года. Описывает `SessionStart` источники и matcher, форму exec `args`, подстановки пути, контекст stdout, перезагрузку настроек, доверие, журналы отладки и неблокирующие ошибки. Это документация, а не запуск hook компанией BIG CHANGE.
- [Anthropic, автоматизация действий через hook](https://code.claude.com/docs/en/hooks-guide) — Официальное руководство по настройке и тестированию hook. Приведённые скрипт и настройки — ограниченный пример BIG CHANGE, проверенный для этой статьи, а не скопированный результат теста поставщика.
- [Anthropic, настройка Claude Code](https://code.claude.com/docs/en/setup) — Требования к установке и окружению. Перед использованием примера проверьте актуальные инструкции для платформы.
- [Anthropic, использование данных в Claude Code](https://code.claude.com/docs/en/data-usage) — Текущие условия провайдера по обработке данных для проверки перед передачей сведений о ветке в контекст модели; разрешение проекта остаётся отдельным решением.
- [Anthropic, эффективное управление расходами](https://code.claude.com/docs/en/costs) — Текущие рекомендации по аккаунту и использованию для интерактивных проверок. Сам локальный скрипт Git не обращается к модели или сети.

## Sources

- [Справочник hook Claude Code](https://code.claude.com/docs/en/hooks) — Актуальный первичный справочник Anthropic проверен по одобренному снимку от 19 октября 2026 года и повторно при написании. Устанавливает источники SessionStart startup/resume и семантику matcher, форму exec command и args, подстановку корня проекта, обычный контекст stdout, наблюдатель настроек, доверие рабочему пространству, просмотр debug-file, правило настоящего исполняемого файла Windows и неблокирующие ошибки SessionStart. Описывает поведение продукта; BIG CHANGE не выполнял hook, вызванный Claude. Фиксированная дата редакции справочника не указана.
- [Автоматизация действий через hook](https://code.claude.com/docs/en/hooks-guide) — Официальное руководство Anthropic по настройке и тестированию. Подтверждает процедуру конфигурации и диагностики для читателя, а не утверждение, что BIG CHANGE запускал пример внутри Claude Code. Точные ограниченные скрипт Node и настройки статьи взяты из отдельно проверенного локального пакета реализации.
- [Расширенная настройка Claude Code](https://code.claude.com/docs/en/setup) — Официальный справочник установки и окружения для проверки локальной настройки Claude Code. При подготовке наблюдалась только версия 2.1.301; источник не делает её минимальным требованием.
- [Использование данных в Claude Code](https://code.claude.com/docs/en/data-usage) — Официальные условия обработки данных зависят от аккаунта. Статья предлагает изучить их перед передачей сведений о ветке Git в контекст модели; фильтрация и сокращение не предотвращают раскрытие конфиденциальных данных клиента или инцидента в названии ветки. Общая гарантия приватности не подразумевается.
- [Эффективное управление расходами](https://code.claude.com/docs/en/costs) — Официальные рекомендации по аккаунту и использованию модели для интерактивных проверок запуска и возобновления. Локальный скрипт сам не обращается к модели или сети, а реальные сеансы Claude могут расходовать лимиты плана, провайдера или API. Фиксированная цена или платный тест не заявляются.
- [Как просмотреть контекст и продолжить сеанс Claude Code](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — Предыдущая статья BIG CHANGE 414 используется только для контекстной внутренней ссылки и классификации связи. Она описывает просмотр существующего разговора и продолжение задачи; это не доказательство реализации hook и не прямой предшественник того же события.