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保留在本機。本例使用專案設定檔，將組態限定於該專案。

安裝兩個檔案

  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。

  1. 開啟現有的.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

  1. 開啟 Claude Code 前，在專案終端機執行腳本並與 Git 比較輸出。PowerShell：
PowerShell
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current

Bash：

Terminal
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 備援，但未執行那些情況。

  1. 在可信專案中啟動新的互動式Claude Code 程序，使用claude --debug-file STARTUP_PRIVATE_LOG，並指定自己控制的私密路徑。接受工作區信任前，先審查專案與使用者鉤子。在偵錯紀錄查找SessionStart事件，來源為startup，並檢查選定腳本路徑、結束狀態及輸出處理。詢問 Claude 收到什麼分支上下文，但不允許工具或另讀 Git。將回答及紀錄與直接結果比較。鉤子 stdout 進入 Claude 上下文，並不保證以介面訊息顯示。
  2. 退出該工作階段。在另一程序使用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 費用指南提供目前條款。本指南不指定固定價格，也未報告付費工作階段測試。

對話開始後的另一任務，可參考我們的檢查上下文並繼續 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 腳本本身不呼叫模型或網路。