Add a bounded project context hook to Claude Code session start

A Claude Code hook is a command the app runs at a named point in a session. This guide adds one project-scoped SessionStart hook that reads the current Git branch and supplies a short line of context when you start or resume a conversation. It follows Anthropic's current hook reference, checked October 19, 2026. BIG CHANGE checked the script directly with Node and checked the settings JSON; we did not run a Claude Code hook or test a model response.

The big change

• What changed: This project SessionStart hook supplies a short Git branch line when Claude Code starts or resumes a conversation.
• Why it matters: The current branch reaches session context at startup or resume without a manual paste each time.
• What to watch: Context does not enforce a rule or guarantee a model answer. Check actual startup and resume delivery in your own trusted project.

Before you install it

Use a Git project you are authorized to change. You need Claude Code, Node.js and Git available in the same terminal, plus permission to edit the project's .claude/settings.json. Check node --version, git --version and claude --version. The preparation host had Claude Code 2.1.301 and Node 24.19.0; those observed versions are not minimum requirements.

Review the branch name before sending it to a model. A branch can contain a client, ticket or incident name. Filtering characters and shortening the string do not remove that meaning. Install this example only when your branch name is approved for model context. Otherwise change the script to emit an approved non-sensitive status and review that change before installation. Anthropic's data-usage documentation explains the service's data handling; apply your own project permissions as well.

Hook commands run with your user permissions. Inspect existing project and user hooks, organization policy, and the complete script before enabling them. Project settings may be committed; .claude/settings.local.json stays local. This example uses the project settings file so the configuration is scoped to that project.

Install the two files

1. Create .claude/hooks/ inside the project. Save this entire block as .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);
}

The Git child process has a 1.5-second timeout and a 4,096-byte output buffer. An empty branch result, as on detached HEAD, becomes detached HEAD. A missing project path or Git failure produces a short stderr diagnostic and exit code 1.

2. Open your existing .claude/settings.json. Merge the hooks.SessionStart entry below with the other settings and hook groups; preserve existing entries. The block shows the complete settings.example.json from the reviewed packet. If your file already has SessionStart entries, add this group to its array rather than replacing the array.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}

The matcher covers a new session and a resumed session. Anthropic also documents clear, compact and fork as SessionStart sources; this example deliberately omits them. The args field selects exec form: Claude Code invokes node with the resolved project script path as one argument, without shell quoting or parsing. On Windows, node.exe must resolve as an executable; a .cmd shim is unsuitable for exec form. The command's five-second hook timeout is separate from the script's 1.5-second Git timeout.

Check the script, then check Claude Code

3. Before opening Claude Code, run the script in the project terminal and compare its output with Git. In PowerShell:

$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current

In Bash:

CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-current

Expect exactly one script stdout line, Current project branch: BRANCH, where BRANCH is the Git result after the script's character filter and 80-character limit. Detached HEAD prints Current project branch: detached HEAD. The direct check establishes only that the local script works in this terminal. In our preparation check, its ordinary branch result matched Git; missing and invalid project paths produced empty stdout, a diagnostic on stderr and exit 1. We inspected the long-name bound and detached-HEAD fallback in source but did not run those cases.

4. Start a fresh interactive Claude Code process in the trusted project with claude --debug-file STARTUP_PRIVATE_LOG, using a private path you control. Review the project and user hooks before accepting workspace trust. Inspect the debug log for a SessionStart event with source startup, the selected script path, its exit status and output handling. Ask Claude what branch context it received without letting it use a tool or read Git independently. Compare the answer and debug record with the direct result. Hook stdout enters Claude's context; it is not promised as a message in the visible UI.
5. Exit that session. Resume it in a separate process with claude --debug-file RESUME_PRIVATE_LOG --resume, then check the SessionStart resume event and repeat the prompt check without a tool or Git reread. Keep both debug logs private; they can expose project details. A non-interactive -p or SDK run does not give the same workspace-trust prompt and can run repository hooks automatically, so use the interactive flow for this check. Anthropic says edits to hook settings are normally picked up by its file watcher, but a fresh process gives a clearer startup and resume test.

If normal project work later changes the branch, repeat the direct check and a fresh session to see whether the line changes. Do not change branches solely to claim this guide was tested.

If it does not run

Start with the direct script result, then check the JSON merge, SessionStart spelling, startup|resume matcher, project-root path, availability of node and git, workspace trust and debug errors. Missing CLAUDE_PROJECT_DIR prints CLAUDE_PROJECT_DIR is unavailable to stderr. A bad project path or Git failure prints Could not read the project branch; check Git and project path. Both exit 1 and print no context line. A SessionStart failure is diagnostic and nonblocking; it cannot serve as an action gate. Anthropic documents PreToolUse for controlling a tool action, which is a different event and requires its own reviewed design.

The script only runs local Git and makes no network request or model call. Claude Code startup, resume and prompt checks can consume your account, provider or model allowance; Anthropic's costs guide has current terms. This guide assigns no fixed price and reports no paid session test.

For a separate task after a conversation is underway, our guide to inspecting context and continuing a Claude Code session covers context inspection and continuation. It does not configure this startup hook.

Sources & further reading

• Anthropic, Claude Code hooks reference — Current primary specification checked October 19, 2026. Documents SessionStart sources and matchers, exec-form args, path placeholders, stdout context, settings reload, trust, debug logs and nonblocking failure behavior. This is documentation, not a BIG CHANGE hook execution.
• Anthropic, Automate actions with hooks — Official walkthrough for hook setup and testing. The exact script and settings above are a bounded BIG CHANGE example reviewed for this guide; they are not a copied vendor test result.
• Anthropic, Claude Code setup — Installation and environment requirements. Check current platform instructions before using the example.
• Anthropic, Claude Code data usage — Current provider data-handling terms to review before sending branch information into model context; your project authorization remains a separate decision.
• Anthropic, Manage costs effectively — Current account and usage guidance for the interactive checks. The local Git script itself makes no model or network request.