SessionStart 훅으로 초기화 자동화

SessionStart 훅은 Claude Code에서 새 세션이 시작되거나 기존 세션이 재개될 때 자동으로 실행되는 훅입니다. 개발을 시작할 때마다 npm install을 돌리고 Docker를 띄우는 준비 작업을 훅에 맡기면 바로 코딩에 집중할 수 있습니다. Hooks 설정 방법에서 만든 ~/Desktop/hooks-test 디렉터리를 그대로 이어서 씁니다.

핵심 요약

• SessionStart 훅은 세션 시작·재개 시에 자동 실행됩니다.
• npm install이나 Docker 기동 같은 환경 셋업 자동화에 가장 잘 맞습니다.
• 조건 분기를 셸 스크립트로 구현하면 필요할 때만 실행하는 유연한 초기화가 가능합니다.
• 여러 초기화를 한꺼번에 실행할 수 있지만, 순서를 보증하려면 &&로 연결해야 합니다.
• $CLAUDE_ENV_FILE로 환경 변수를 세션 내내 유지할 수 있습니다.

SessionStart 훅은 언제 실행되나

개발을 시작할 때는 의존 패키지 설치, 환경 변수 읽기, 개발 서버 기동 등 준비가 필요합니다. SessionStart 훅은 이 작업을 세션이 열릴 때 자동으로 실행해 줍니다.

SessionStart에는 matcher 필드가 있어 startup·resume·clear·compact·fork 중 하나를 지정하면 세션 시작 이유에 따라 실행을 좁힐 수 있습니다. 매번 실행하고 싶다면 matcher를 생략하면 됩니다. 더 세밀한 조건이 필요하면 셸 스크립트 안에서 분기하세요. 훅 전체의 종류는 훅 개요에 정리돼 있습니다.

간단한 예로 동작 확인하기

SessionStart 훅은 설정 파일의 hooks 섹션 아래 "SessionStart" 키에 적습니다. 세션 시작 시 로그 파일에 한 줄을 써넣는 예로 동작을 확인합니다. matcher를 생략했으므로 어떤 시작 이유에서든 실행됩니다.

1. 테스트용 디렉터리로 이동합니다(없으면 만듭니다).

mkdir -p ~/Desktop/hooks-test/.claude
cd ~/Desktop/hooks-test

1. .claude/settings.json에 아래 설정을 추가합니다. 세션 시작 시각이 붙은 메시지를 session-start.log에 남깁니다.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"세션 시작: $(date)\" >> ~/Desktop/hooks-test/session-start.log"
          }
        ]
      }
    ]
  }
}

1. 같은 디렉터리에서 claude를 실행하고 로그를 확인합니다.

cat ~/Desktop/hooks-test/session-start.log
# 세션 시작: Mon 29 Dec 2025 11:04:33 KST

여러 초기화를 순서대로 실행하려면

실제 프로젝트에서는 초기화가 여러 단계입니다. 이때 hooks 배열에 명령을 나눠 나열하면 병렬로 실행되어 순서가 보증되지 않습니다. 어떤 핸들러가 실패(0이 아닌 종료)해도 다른 핸들러에는 영향이 없으므로, 의존 관계가 있는 처리를 나눠 쓰면 의도치 않은 순서로 실행됩니다.

순서가 중요한 처리는 하나의 command 안에서 &&로 연결합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm install && docker-compose up -d && npm run db:migrate"
          }
        ]
      }
    ]
  }
}

&&로 연결했으므로 의존 패키지 설치, Docker 컨테이너 백그라운드 기동, 데이터베이스 마이그레이션이 앞 처리가 성공한 경우에만 차례로 실행됩니다.

실전: node_modules 가 없을 때만 npm install

Node.js 프로젝트에서는 command에 npm install만 적어도 세션 시작 시 의존 패키지가 자동으로 설치됩니다. 특히 Claude Code on the Web 같은 클라우드 환경에서는 세션마다 환경이 리셋되는 경우가 있어 유용합니다.

다만 매번 npm install을 돌리는 것은 낭비입니다. node_modules가 이미 있으면 건너뛰도록 조건 분기를 넣은 스크립트를 만들어 봅니다.

1. 검증용으로 ~/Desktop/hooks-test에 패키지를 하나 설치해 package.json과 node_modules를 만듭니다.

cd ~/Desktop/hooks-test
npm install lodash   # 적당한 라이브러리 설치

1. .claude/hooks/install-node-modules.sh를 만듭니다. 각 분기에서 무엇을 했는지 로그에 남겨 두면 나중에 cat으로 실행 결과를 확인할 수 있습니다.

#!/bin/bash
# .claude/hooks/install-node-modules.sh
# node_modules가 존재하지 않는 경우에만 npm install을 실행
LOG_FILE=~/Desktop/hooks-test/session-start.log

if [ ! -d "node_modules" ]; then
    echo "$(date): node_modules를 찾을 수 없습니다. npm install을 실행합니다..." >> "$LOG_FILE"
    npm install >> "$LOG_FILE" 2>&1
else
    echo "$(date): node_modules는 이미 존재합니다. 건너뜁니다." >> "$LOG_FILE"
fi

npm install >> "$LOG_FILE" 2>&1의 2>&1은 표준 에러 출력도 로그에 남기는 지정입니다. npm install에서 에러가 났을 때 원인을 로그에서 추적할 수 있습니다.

1. 실행 권한을 부여하고 .claude/settings.json에서 이 스크립트를 호출합니다.

chmod +x .claude/hooks/install-node-modules.sh

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/Desktop/hooks-test/.claude/hooks/install-node-modules.sh"
          }
        ]
      }
    ]
  }
}

1. node_modules가 있는 상태에서 claude를 실행하면 건너뛴 기록이 남습니다. 이어서 Claude Code를 종료하고 rm -rf node_modules로 지운 뒤 다시 실행하면 이번에는 npm install이 실행됩니다.

cat ~/Desktop/hooks-test/session-start.log
# Mon 29 Dec 2025 11:04:33 KST: node_modules는 이미 존재합니다. 건너뜁니다.
# Mon 29 Dec 2025 11:05:12 KST: node_modules를 찾을 수 없습니다. npm install을 실행합니다...
# added 1 package, and audited 2 packages in 1s
# found 0 vulnerabilities

npm install은 package.json이 있어야 동작합니다. 없으면 에러가 나지만 원인은 session-start.log에 기록되니, 잘 안 될 때는 로그부터 확인하세요.

환경 변수를 세션 내내 유지하기 — $CLAUDE_ENV_FILE

자작 스크립트가 환경 변수에 따라 분기한다면, 그 변수를 세션 중 유지해 두어야 Claude Code가 스크립트를 실행할 때 참조할 수 있습니다. 이를 위해 SessionStart 훅에는 특별한 변수 $CLAUDE_ENV_FILE이 준비돼 있습니다. SessionStart·Setup·CwdChanged·FileChanged 네 이벤트에서 쓸 수 있으며, 이 변수가 가리키는 파일에 써넣은 환경 변수는 그 세션 내내 유효합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'NODE_ENV=development' >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

확인은 Claude Code 안에서 !를 붙여 임의의 명령을 실행하면 됩니다.

! echo $NODE_ENV
  ⎿  development

훅에서 쓸 수 있는 환경 변수 전체는 Hooks 환경 변수에서 다룹니다.

초기화가 오래 걸리면 timeout 을 조정

초기화에 시간이 걸리면 timeout 옵션(초 단위)으로 제한 시간을 늘립니다. 기본 타임아웃은 600초(10분)이며, 아래는 5분으로 설정한 예입니다. Docker 기동이나 마이그레이션처럼 오래 걸리는 처리는 넉넉히 잡아 두세요.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm install",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

사용할 때 주의할 점

• 실행 시간: 초기화가 길면 세션 시작 때마다 대기 시간이 생깁니다. 정말 매번 필요한 처리만 등록하고, 오래 걸리는 처리는 timeout을 적절히 설정합니다.
• 에러 핸들링: 훅이 실패해도 세션은 시작됩니다. 편리하지만 실패를 알아차리기 어렵다는 뜻이기도 하므로, 중요한 처리는 스크립트 안에 에러 처리를 넣어 둡니다.
• 보안: 훅은 자동 실행되므로 신뢰할 수 있는 명령만 등록합니다. 프로젝트 settings.json을 팀과 공유한다면 코드 리뷰 대상에 포함하는 것이 좋습니다.

훅이 실패했을 때 원인 찾기

의도한 초기화가 안 됐다면 먼저 스크립트를 터미널에서 직접 실행해 봅니다(~/Desktop/hooks-test/.claude/hooks/install-node-modules.sh). 또 앞서처럼 2>&1로 에러 출력까지 로그에 남겨 두면 훅을 거쳐 실행됐을 때의 거동도 추적할 수 있습니다. 예를 들어 package.json이 없는 디렉터리에서 npm install이 실행되면 아래 같은 에러가 로그에 기록됩니다.

cat ~/Desktop/hooks-test/session-start.log
# Mon 29 Dec 2025 11:10:21 KST: node_modules를 찾을 수 없습니다. npm install을 실행합니다...
# npm error code ENOENT
# npm error syscall open
# npm error path ~/Desktop/hooks-test/package.json
# npm error errno -2
# npm error enoent Could not read package.json: Error: ENOENT: no such file or directory

종료 코드에 따른 동작과 에러 핸들링은 종료 코드로 제어에서 이어집니다.

정리

• SessionStart 훅은 세션 시작·재개 시 자동 실행되며, matcher로 시작 이유를 좁힐 수 있습니다.
• 여러 명령을 한꺼번에 실행할 수 있지만 순서를 보증하려면 &&로 연결합니다.
• 환경 변수 영속화에는 $CLAUDE_ENV_FILE을 씁니다.
• timeout 설정으로 장시간 처리에도 대응할 수 있고, 로그를 남겨 두면 실패 원인을 찾기 쉽습니다.
• 다음은 응답이 끝날 때 알림이나 로그를 남기는 Stop 훅입니다.