世界从未停止变化。RSS
BIG CHANGE.
BIG CHANGE，一触即达
BIG CHANGE，一触即达

纵览全局。

将 BIG CHANGE 添加到主屏幕或桌面。它会在独立窗口中打开，并在您在线时显示最新报道。

iPhone 和 iPad
在 Safari 中打开 bigchange.ai。轻点“共享”，然后轻点“添加到主屏幕”。如果显示“作为网页 App 打开”，请将其开启，然后轻点“添加”。
Android
在 Chrome 中打开 bigchange.ai。打开浏览器菜单，选择“安装应用”或“添加到主屏幕”。
桌面设备
在 Chrome 或 Edge 中，使用地址栏中的安装图标或浏览器的应用菜单。在 Mac 上的 Safari 中，选择“文件”→“添加到程序坞”。

Markdown 版本

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

# 为 Claude Code 会话启动添加受限的项目上下文钩子

> 安装一个小型项目 SessionStart 钩子，将当前 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.

Claude Code 钩子是在会话某个具名时点由应用执行的命令。本指南添加一个项目级`SessionStart`钩子，读取当前 Git 分支，在启动或恢复对话时提供一行简短上下文。它依据[Anthropic 当前钩子参考文档](https://code.claude.com/docs/en/hooks)，核查日期为 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 的数据使用文档](https://code.claude.com/docs/en/data-usage)说明服务的数据处理方式；同时遵守项目权限。

钩子命令使用你的用户权限运行。启用前检查已有的项目与用户钩子、组织政策和完整脚本。项目设置可能提交到版本库；`.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 秒，输出缓冲区为 4,096 字节。空分支结果，例如分离 HEAD 时，转换为`detached HEAD`。项目路径缺失或 Git 失败会产生简短 stderr 诊断及退出码 1。

2. 打开已有的`.claude/settings.json`。将下面的`hooks.SessionStart`条目合并进其他设置和钩子组，保留已有条目。代码块展示审查包中的完整`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
          }
        ]
      }
    ]
  }
}
```

匹配器覆盖新会话及恢复会话。Anthropic 还记录了`clear`、`compact`和`fork`作为`SessionStart`的来源；本例有意省略。字段`args`选择 exec 形式：Claude Code 调用`node`，将解析后的项目脚本路径作为一个参数，不经 shell 引号或解析。Windows 上的`node.exe`必须解析为真实可执行文件；`.cmd`垫片不适合 exec 形式。命令的五秒钩子超时，与脚本的 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`是经过字符过滤及 80 字符限制的 Git 结果。分离 HEAD 时输出`Current project branch: detached HEAD`。直接检查只能证明脚本在该终端运行正常。准备检查中，普通分支结果与 Git 一致；路径缺失或无效时 stdout 为空，stderr 有诊断，退出为 1。我们在源码中检查了长名称限制和分离 HEAD 回退，但没有执行这些情形。

4. 在可信项目中用**交互式**的新 Claude Code 进程运行`claude --debug-file STARTUP_PRIVATE_LOG`，日志路径应是你控制的私密路径。接受工作区信任前，审查项目和用户钩子。在调试日志中查找`SessionStart`事件，来源为`startup`，并检查选中的脚本路径、退出状态和输出处理。询问 Claude 收到了什么分支上下文，禁止它使用工具或另行读取 Git。将回答和日志与直接结果比较。钩子 stdout 进入 Claude 上下文，并不承诺在界面中显示为一条消息。
5. 退出会话。在另一进程中使用`claude --debug-file RESUME_PRIVATE_LOG --resume`恢复，然后检查`SessionStart` `resume`事件，再次禁止工具和重读 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 费用指南](https://code.claude.com/docs/en/costs)给出当前条款。本指南不设固定价格，也未报告付费会话测试。

对话已经开始后的另一任务，可参阅我们的[检查上下文并继续 Claude Code 会话指南](https://bigchange.ai/blog/claude-code-session-context-continue-guide)，其涵盖上下文检查与继续任务，不配置本启动钩子。

## 来源与延伸阅读

- [Anthropic，Claude Code 钩子参考](https://code.claude.com/docs/en/hooks)——2026 年 10 月 19 日检查的当前主要规范。记录`SessionStart`来源与匹配器、exec 形式的`args`、路径占位符、stdout 上下文、设置重载、信任、调试日志及非阻塞失败行为。这是文档，不是 BIG CHANGE 执行钩子的结果。
- [Anthropic，用钩子自动执行操作](https://code.claude.com/docs/en/hooks-guide)——官方钩子设置与测试指南。上述脚本和配置是为本指南审查过的受限 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

- [Claude Code 钩子参考](https://code.claude.com/docs/en/hooks) — 当前 Anthropic 主要手册，与获准的 2026 年 10 月 19 日快照及写作时版本核对。支持 SessionStart 的 startup/resume 来源与匹配规则、exec 形式 command 和 args、项目根占位符、纯 stdout 上下文、设置监听、工作区信任、调试文件检查、Windows 真实可执行文件要求及非阻塞 SessionStart 错误。它描述产品行为；BIG CHANGE 未执行 Claude 调用的钩子。未给出固定手册修订日期。
- [用钩子自动执行操作](https://code.claude.com/docs/en/hooks-guide) — Anthropic 官方设置及测试指南。它支持读者的钩子配置与诊断流程，不表示 BIG CHANGE 在 Claude Code 内运行了示例。文章的受限 Node 脚本和设置来自单独审查的本地实现包。
- [Claude Code 高级设置](https://code.claude.com/docs/en/setup) — 用于检查本地环境的官方安装参考。准备阶段只观察到 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，仅用于上下文内部链接和关系分类。它讲已有对话的检查与继续任务，不是本钩子实现的证据，也不是同一事件的直接日期前篇。