Claude Code hook은 앱이 세션의 특정 시점에 실행하는 명령입니다. 이 안내서는 프로젝트 범위의 SessionStart hook 하나를 추가합니다. 현재 Git 브랜치를 읽어 대화를 시작하거나 재개할 때 짧은 컨텍스트 한 줄을 전달합니다. 근거는 Anthropic의 최신 hook 참조 문서이며 2026년 10월 19일 확인했습니다. BIG CHANGE는 Node로 스크립트를 직접 확인하고 설정 JSON을 검사했습니다. Claude Code hook 실행이나 모델 응답 테스트는 하지 않았습니다.
핵심 변화
- 달라진 점: 이 프로젝트의
SessionStarthook은 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 데이터 사용 문서 는 서비스의 데이터 처리 방식을 설명합니다. 프로젝트의 권한도 함께 적용하세요.
Hook 명령은 자신의 사용자 권한으로 실행됩니다. 활성화 전에 기존 프로젝트 및 사용자 hook, 조직 정책, 전체 스크립트를 검토하세요. 프로젝트 설정은 저장소에 커밋될 수 있지만 .claude/settings.local.json 파일은 로컬에 남습니다. 이 예제는 해당 프로젝트에만 적용되도록 프로젝트 설정 파일을 사용합니다.
두 파일 설치하기
- 프로젝트 안에
.claude/hooks/를 만드세요. 아래 블록 전체를.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);
}Git 하위 프로세스는 제한 시간 1.5초, 출력 버퍼 4,096바이트를 사용합니다. detached HEAD처럼 브랜치 결과가 비어 있으면 detached HEAD가 됩니다. 프로젝트 경로가 없거나 Git이 실패하면 짧은 stderr 진단과 종료 코드 1을 반환합니다.
- 기존
.claude/settings.json파일을 여세요. 아래hooks.SessionStart항목을 다른 설정과 hook 그룹에 병합하고 기존 항목은 보존하세요. 블록은 검토된 패킷의 전체settings.example.json를 보여 줍니다. 파일에 이미SessionStart항목이 있으면 배열을 교체하지 말고 해당 배열에 이 그룹을 추가하세요.
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume",
"hooks": [
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
"timeout": 5
}
]
}
]
}
}Matcher는 새 세션과 재개된 세션을 포함합니다. Anthropic은 clear, compact , fork 도 SessionStart 소스로 문서화하지만 이 예제에서는 의도적으로 제외합니다. args 필드는 exec 형식을 선택합니다. Claude Code는 node 를 호출하면서 해석된 프로젝트 스크립트 경로를 하나의 인수로 넘깁니다. 셸 따옴표 처리나 파싱을 거치지 않습니다. Windows에서 node.exe 는 실행 파일로 확인되어야 합니다. .cmd shim은 exec 형식에 적합하지 않습니다. 명령의 hook 제한 시간 5초는 스크립트의 Git 제한 시간 1.5초와 별개입니다.
스크립트 확인 후 Claude Code 확인하기
- Claude Code를 열기 전에 프로젝트 터미널에서 스크립트를 실행하고 출력을 Git과 비교하세요. PowerShell에서는:
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-currentBash에서는:
CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-current스크립트 stdout에는 정확히 한 줄인 Current project branch: BRANCH가 나와야 합니다. 여기서 BRANCH 는 스크립트의 문자 필터와 80자 제한을 적용한 Git 결과입니다. Detached HEAD는 Current project branch: detached HEAD를 출력합니다. 직접 확인은 이 터미널에서 로컬 스크립트가 작동한다는 것만 입증합니다. 준비 확인에서 일반 브랜치 결과는 Git과 일치했습니다. 누락되거나 잘못된 프로젝트 경로는 빈 stdout, stderr 진단, 종료 1을 냈습니다. 긴 이름 제한과 detached HEAD 대체값은 소스에서 검토했으나 해당 경우를 실행하지는 않았습니다.
- 신뢰하는 프로젝트에서 새로운 대화형 Claude Code 프로세스를
claude --debug-file STARTUP_PRIVATE_LOG와 함께 시작하고 직접 관리하는 비공개 경로를 사용하세요. 작업 공간 신뢰를 승인하기 전에 프로젝트 및 사용자 hook을 검토하세요. 디버그 로그에서SessionStart이벤트와 소스startup, 선택된 스크립트 경로, 종료 상태, 출력 처리를 확인하세요. 도구 사용이나 독립적인 Git 읽기를 허용하지 말고 Claude에게 받은 브랜치 컨텍스트를 물어보세요. 답변과 디버그 기록을 직접 실행 결과와 비교하세요. Hook stdout은 Claude 컨텍스트에 들어가며 화면 UI에 메시지로 표시된다는 보장은 없습니다. - 해당 세션을 종료하세요. 별도 프로세스에서
claude --debug-file RESUME_PRIVATE_LOG --resume로 재개한 뒤SessionStartresume이벤트를 확인하고 도구나 Git 재조회 없이 질문 확인을 반복하세요. 두 디버그 로그에는 프로젝트 세부사항이 노출될 수 있으므로 비공개로 보관하세요. 비대화형-p또는 SDK 실행에는 같은 작업 공간 신뢰 요청이 없으며 저장소 hook이 자동 실행될 수 있으므로 이 확인에는 대화형 흐름을 사용하세요. Anthropic에 따르면 설정 파일 감시기가 보통 hook 설정 변경을 반영하지만 새 프로세스를 사용하면 시작과 재개를 더 명확히 테스트할 수 있습니다.
이후 정상적인 프로젝트 작업으로 브랜치가 바뀌면 직접 확인과 새 세션을 반복하여 한 줄이 바뀌는지 확인하세요. 이 안내서를 테스트했다고 주장하려고 일부러 브랜치를 바꾸지 마세요.
실행되지 않을 때
직접 스크립트 결과부터 확인한 다음 JSON 병합, SessionStart 철자, startup|resume matcher, 프로젝트 루트 경로, node 및 git 사용 가능 여부, 작업 공간 신뢰, 디버그 오류를 확인하세요. CLAUDE_PROJECT_DIR 가 없으면 CLAUDE_PROJECT_DIR is unavailable 를 stderr에 출력합니다. 프로젝트 경로 오류 또는 Git 실패 시 Could not read the project branch; check Git and project path를 출력합니다. 두 경우 모두 종료 1이며 컨텍스트 줄은 출력하지 않습니다. SessionStart 실패는 진단용이며 차단하지 않습니다. 동작 실행을 막는 관문으로 사용할 수 없습니다. Anthropic은 도구 동작 제어용으로 PreToolUse 를 문서화합니다. 이는 다른 이벤트이며 별도로 검토한 설계가 필요합니다.
스크립트는 로컬 Git만 실행하며 네트워크 요청이나 모델 호출은 하지 않습니다. Claude Code 시작, 재개, 질문 확인은 계정·제공업체·모델 사용 한도를 소비할 수 있습니다. Anthropic 비용 안내 에서 최신 조건을 확인하세요. 이 안내서는 고정 가격을 제시하거나 유료 세션 테스트를 보고하지 않습니다.
대화가 진행 중인 상황에서 하는 별도 작업은 Claude Code 세션 컨텍스트 검사 및 계속하기 안내 에서 설명합니다. 그 안내는 이 시작 hook을 설정하지 않습니다.
출처 및 추가 자료
- Anthropic, Claude Code hook 참조 — 2026년 10월 19일 확인한 최신 1차 명세입니다.
SessionStart소스와 matcher, exec 형식args, 경로 자리표시자, stdout 컨텍스트, 설정 재로딩, 신뢰, 디버그 로그, 비차단 실패 동작을 설명합니다. 문서 근거이며 BIG CHANGE의 hook 실행이 아닙니다. - Anthropic, hook으로 동작 자동화하기 — hook 설정과 테스트에 관한 공식 안내입니다. 위의 정확한 스크립트와 설정은 이 안내서를 위해 검토한 범위가 제한된 BIG CHANGE 예제이며 공급업체 테스트 결과를 복사한 것이 아닙니다.
- Anthropic, Claude Code 설정 — 설치 및 환경 요구사항입니다. 예제를 사용하기 전에 최신 플랫폼 지침을 확인하세요.
- Anthropic, Claude Code 데이터 사용 — 브랜치 정보를 모델 컨텍스트에 보내기 전에 검토할 제공업체의 최신 데이터 처리 조건입니다. 프로젝트 권한 승인은 별도 결정입니다.
- Anthropic, 효과적인 비용 관리 — 대화형 확인을 위한 최신 계정 및 사용 안내입니다. 로컬 Git 스크립트 자체는 모델이나 네트워크에 요청하지 않습니다.
