Hooks 환경 변수 — CLAUDE_PROJECT_DIR·CLAUDE_ENV_FILE

Hooks 환경 변수는 Claude Code가 훅 스크립트에 프로젝트와 세션 정보를 넘겨주는 통로입니다. 스크립트 안에서 $CLAUDE_PROJECT_DIR 같은 변수를 읽기만 하면 되므로, 프로젝트 고유의 처리를 경로 하드코딩 없이 유연하게 구현할 수 있습니다.

종료 코드로 훅을 제어하는 방법까지 익혔다면, 이제 스크립트가 "어디서, 어떤 상태로" 실행되는지를 알려 주는 환경 변수를 다룰 차례입니다.

핵심 요약

• CLAUDE_PROJECT_DIR로 프로젝트 루트 디렉터리(절대 경로)를 얻을 수 있습니다.
• CLAUDE_ENV_FILE로 세션 중의 환경 변수를 영속화할 수 있습니다.
• CLAUDE_ENV_FILE은 SessionStart·Setup·CwdChanged·FileChanged 네 훅에서만 이용 가능합니다.

실습용 디렉터리

Hooks 설정 방법에서 만든 ~/Desktop/hooks-test 디렉터리를 그대로 사용합니다. 아직 없다면 아래 명령으로 만들어 주세요.

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

Hooks에서 쓸 수 있는 환경 변수는 무엇인가

환경 변수란 프로그램에 정보를 넘기기 위한 장치입니다. Claude Code의 Hooks에서는 스크립트 안에서 특정 환경 변수를 참조해 프로젝트나 파일에 관한 정보를 가져올 수 있습니다. Hooks 자체의 기본 구조는 훅(Hooks)으로 동작 강제하기를 참고하세요.

먼저 간단한 예로 확인하기

환경 변수가 실제로 어떻게 넘어오는지 PostToolUse 훅으로 확인해 봅니다. ~/Desktop/hooks-test/.claude/settings.json에 아래 설정을 추가합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"프로젝트 디렉터리: $CLAUDE_PROJECT_DIR\""
          }
        ]
      }
    ]
  }
}

~/Desktop/hooks-test에서 Claude Code를 실행하고 "ls를 실행해줘"라고 요청해 보세요. PostToolUse는 도구가 실행된 뒤에 발화하므로, Bash나 Read 같은 도구 실행이 한 번은 일어나야 합니다.

cd ~/Desktop/hooks-test
claude

도구 실행 후 아래처럼 표시되면 성공입니다.

> ls를 실행해줘
...

⏺ Bash(ls -la)
  ⎿  total 16
  ⎿  PostToolUse:Bash hook succeeded: 프로젝트 디렉터리: ~/Desktop/hooks-test

$CLAUDE_PROJECT_DIR에 현재 프로젝트 디렉터리가 자동으로 설정되어 있는 것을 확인할 수 있습니다.

CLAUDE_PROJECT_DIR — 프로젝트 루트는 어떻게 얻나

CLAUDE_PROJECT_DIR은 현재 작업 중인 프로젝트의 루트 디렉터리를 나타내는 환경 변수입니다. 이 변수가 중요한 이유는, 스크립트 안에서 프로젝트 루트를 기준으로 한 경로를 안전하게 다룰 수 있기 때문입니다.

#!/bin/bash
# CLAUDE_PROJECT_DIR 활용 예

# 프로젝트 루트를 취득
project_root="$CLAUDE_PROJECT_DIR"

# 프로젝트 고유의 설정 파일을 참조
if [[ -f "$project_root/.prettierrc" ]]; then
    echo "Prettier 설정이 발견됐습니다"
fi

# 프로젝트 내의 로그 파일에 기록
echo "$(date): 훅 실행" >> "$project_root/.claude/hooks.log"

이렇게 해 두면 Claude Code가 어느 디렉터리에서 실행됐는지에 관계없이 프로젝트 루트를 기준으로 처리할 수 있습니다. 훅 스크립트를 별도 sh 파일로 빼는 요령은 Hooks 설정 방법에서 다룹니다.

CLAUDE_ENV_FILE — 세션 중 환경 변수를 어떻게 영속화하나

CLAUDE_ENV_FILE은 SessionStart·Setup·CwdChanged·FileChanged 네 가지 훅에서 이용할 수 있는 특수한 환경 변수입니다. 이 변수에는 환경 변수를 영속화하기 위한 파일 경로가 들어 있으며, 그 파일에 export KEY=VALUE 형식으로 써넣으면 세션 중에 환경 변수가 설정됩니다.

#!/bin/bash
# SessionStart 훅에서의 활용 예

env_file="$CLAUDE_ENV_FILE"

# 환경 변수를 영속화
echo "export PROJECT_TYPE=nodejs" >> "$env_file"
echo "export DEBUG_MODE=true" >> "$env_file"

예를 들어 프로젝트 종류를 세션 시작 시 자동 판정해 두고, 이후 다른 훅 스크립트에서 $PROJECT_TYPE을 읽어 분기하는 식으로 활용할 수 있습니다. 세션마다 반복되는 판정을 한 번으로 끝내는 셈입니다.

다만 CLAUDE_ENV_FILE은 위 네 종류의 훅에서만 값이 설정된다는 점에 주의하세요. PostToolUse 같은 훅에서 이 변수를 읽어도 비어 있습니다. SessionStart 훅의 실전 활용은 SessionStart 훅을 참고하세요.

정리

• CLAUDE_PROJECT_DIR은 모든 훅에서 쓸 수 있으며 프로젝트 루트의 절대 경로를 담고 있습니다.
• CLAUDE_ENV_FILE은 SessionStart·Setup·CwdChanged·FileChanged에서만 쓸 수 있으며, export KEY=VALUE를 써넣어 세션 중 환경 변수를 영속화합니다.
• 먼저 $CLAUDE_PROJECT_DIR 동작 확인부터 시작하고, 필요해지면 $CLAUDE_ENV_FILE을 활용하세요.
• 훅의 발화 조건을 더 정밀하게 좁히는 방법은 Hooks 매처에서 이어집니다.