世界は立ち止まらない。RSS
BIG CHANGE.
ワンタップでBIG CHANGE
ワンタップでBIG CHANGE

大局を見渡す余白を。

BIG CHANGE をホーム画面またはデスクトップに追加します。専用ウィンドウで開き、オンライン時には最新の記事が表示されます。

iPhoneとiPad
Safari で bigchange.ai を開きます。「共有」、「ホーム画面に追加」の順にタップします。「Web 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`はローカルに残ります。この例はプロジェクト設定ファイルで対象範囲を限定します。

## 2つのファイルを入れる

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`を、解決済みプロジェクトスクリプトパス1個の引数で呼びます。シェルの引用・解析は行いません。Windowsでは`node.exe`が本当の実行ファイルに解決される必要があり、`.cmd`シムはexec形式に使えません。コマンドの5秒のフック制限は、スクリプトの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はちょうど1行の`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`、選択スクリプトのパス、終了状態、出力処理を確認します。ツールや別のGit読み取りを禁止し、受け取ったブランチ文脈をClaudeに尋ねます。回答とログを直接結果に照合します。フックstdoutはClaudeの文脈に入り、画面上のメッセージとして表示される保証はありません。
5. そのセッションを終了し、別プロセスで`claude --debug-file RESUME_PRIVATE_LOG --resume`を使って再開します。`SessionStart` `resume`イベントを確認し、ツールやGit再読み取りなしで同じ質問をします。2つのログはプロジェクト情報を含み得るため非公開にします。非対話型の`-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) — 2026年10月19日の承認済みスナップショットと執筆時に照合した現行Anthropic一次マニュアル。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) — 対話型の起動・再開・質問テストの公式アカウント・使用ガイド。ローカルスクリプトはモデルやネットワークを呼びませんが、実セッションはプラン、プロバイダー、API枠を消費し得ます。固定価格や有料テストの主張はありません。
- [文脈を確認しClaude Codeセッションを継続する方法](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — 以前のBIG CHANGE記事414。文脈リンクと関係分類のみに使用します。既存会話の確認と継続を扱い、フック実装の証拠でも同じ出来事の直接の前篇でもありません。