世界從未停止變化。RSS
BIG CHANGE.
BIG CHANGE，輕觸即達
BIG CHANGE，輕觸即達

拉開視野。

將 BIG CHANGE 加入主畫面或桌面。它會在自己的視窗中開啟，並在您上線時顯示最新報導。

iPhone 與 iPad
在 Safari 中開啟 bigchange.ai。點一下「分享」，再點一下「加入主畫面」。如果顯示「以網頁 App 開啟」，請將其開啟，再點一下「加入」。
Android
在 Chrome 中開啟 bigchange.ai。開啟瀏覽器選單，選擇「安裝應用程式」或「加入主畫面」。
桌面裝置
在 Chrome 或 Edge 中，使用網址列中的安裝圖示或瀏覽器的應用程式選單。在 Mac 上的 Safari 中，選擇「檔案」→「加入 Dock」。

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，只作為內部上下文連結與關係分類。它說明檢查現有對話及繼續任務，不是本鉤子實作的證據，也不是同一日期事件的直接前篇。