Claude Code 钩子是在会话某个具名时点由应用执行的命令。本指南添加一个项目级SessionStart钩子，读取当前 Git 分支，在启动或恢复对话时提供一行简短上下文。它依据Anthropic 当前钩子参考文档，核查日期为 2026 年 10 月 19 日。BIG CHANGE 用 Node 直接检查了脚本及设置 JSON；我们没有运行 Claude Code 调用的钩子，也没有测试模型回答。
重大变化
- 变化是什么： 这个项目级
SessionStart钩子在 Claude Code 启动或恢复对话时提供一行 Git 分支信息。 - 为什么重要： 当前分支会在启动或恢复时进入会话上下文，不必每次手动粘贴。
- 需要注意： 上下文不能强制执行规则，也不保证模型回答。请在自己的可信项目中检查启动与恢复时的实际传递。
安装之前
使用你有权修改的 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 的数据使用文档说明服务的数据处理方式；同时遵守项目权限。
钩子命令使用你的用户权限运行。启用前检查已有的项目与用户钩子、组织政策和完整脚本。项目设置可能提交到版本库；.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 秒，输出缓冲区为 4,096 字节。空分支结果，例如分离 HEAD 时，转换为detached HEAD。项目路径缺失或 Git 失败会产生简短 stderr 诊断及退出码 1。
- 打开已有的
.claude/settings.json。将下面的hooks.SessionStart条目合并进其他设置和钩子组，保留已有条目。代码块展示审查包中的完整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
}
]
}
]
}
}匹配器覆盖新会话及恢复会话。Anthropic 还记录了clear、compact和fork作为SessionStart的来源；本例有意省略。字段args选择 exec 形式：Claude Code 调用node，将解析后的项目脚本路径作为一个参数，不经 shell 引号或解析。Windows 上的node.exe必须解析为真实可执行文件；.cmd垫片不适合 exec 形式。命令的五秒钩子超时，与脚本的 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是经过字符过滤及 80 字符限制的 Git 结果。分离 HEAD 时输出Current project branch: detached HEAD。直接检查只能证明脚本在该终端运行正常。准备检查中，普通分支结果与 Git 一致；路径缺失或无效时 stdout 为空，stderr 有诊断，退出为 1。我们在源码中检查了长名称限制和分离 HEAD 回退，但没有执行这些情形。
- 在可信项目中用交互式的新 Claude Code 进程运行
claude --debug-file STARTUP_PRIVATE_LOG，日志路径应是你控制的私密路径。接受工作区信任前，审查项目和用户钩子。在调试日志中查找SessionStart事件，来源为startup，并检查选中的脚本路径、退出状态和输出处理。询问 Claude 收到了什么分支上下文，禁止它使用工具或另行读取 Git。将回答和日志与直接结果比较。钩子 stdout 进入 Claude 上下文，并不承诺在界面中显示为一条消息。 - 退出会话。在另一进程中使用
claude --debug-file RESUME_PRIVATE_LOG --resume恢复，然后检查SessionStartresume事件，再次禁止工具和重读 Git，重复问题检查。两个日志均保持私密，可能含项目详情。非交互式-p或 SDK 运行不提供相同的工作区信任提示，且可能自动运行仓库钩子，因此本检查应使用交互流程。Anthropic 说文件监听通常会获取钩子设置更改，但新进程能让启动与恢复测试更明确。
若日常项目工作后来更改了分支，重复直接检查并启动新会话，确认输出行是否改变。不要仅为宣称本指南已测试而切换分支。
钩子不运行时
先看直接脚本结果，再检查 JSON 合并、SessionStart拼写、startup|resume匹配器、项目根目录、node和git的可用性、工作区信任及调试错误。缺少CLAUDE_PROJECT_DIR时，stderr 输出CLAUDE_PROJECT_DIR is unavailable。路径错误或 Git 失败时输出Could not read the project branch; check Git and project path。两种情况均退出 1，不打印上下文行。SessionStart失败是非阻塞诊断，不能充当动作关卡。Anthropic 记录了PreToolUse用于控制工具操作，但这是另一事件，需要独立审查设计。
脚本只运行本地 Git，没有网络请求或模型调用。Claude Code 启动、恢复和提问检查可能消耗账户、提供商或模型额度；Anthropic 费用指南给出当前条款。本指南不设固定价格，也未报告付费会话测试。
对话已经开始后的另一任务，可参阅我们的检查上下文并继续 Claude Code 会话指南，其涵盖上下文检查与继续任务，不配置本启动钩子。
来源与延伸阅读
- Anthropic，Claude Code 钩子参考——2026 年 10 月 19 日检查的当前主要规范。记录
SessionStart来源与匹配器、exec 形式的args、路径占位符、stdout 上下文、设置重载、信任、调试日志及非阻塞失败行为。这是文档，不是 BIG CHANGE 执行钩子的结果。 - Anthropic，用钩子自动执行操作——官方钩子设置与测试指南。上述脚本和配置是为本指南审查过的受限 BIG CHANGE 示例，不是抄录的供应商测试结果。
- Anthropic，Claude Code 设置——安装及环境要求。使用示例前检查平台当前说明。
- Anthropic，Claude Code 数据使用——发送分支信息前应审查的当前服务商数据处理条款；项目授权仍是另一项决定。
- Anthropic，有效管理费用——交互检查的当前账户及用量说明。本地 Git 脚本本身不调用网络或模型。
