[Claude Code] terminal-notifier로 작업 완료 알림 받기

목차
개요
왜 알림이 필요한가?
terminal-notifier 설치
- 설치 확인
- 기본 사용법
Claude Code Hooks란?
- settings.json 파일 위치
- Hook의 구조
Stop Hook — 작업 완료 알림
Notification Hook — 입력 대기 알림
전체 설정
설정 확인
macOS 알림 권한 설정
완료

개요

Claude Code에 작업을 시켜놓고 다른 일을 하다 보면, 작업이 끝났는지 수시로 터미널을 확인하게 됩니다. Claude Code의 Hooks 기능과 macOS의 terminal-notifier를 연동하면, 작업이 완료되거나 입력이 필요할 때 데스크톱 알림을 자동으로 받을 수 있습니다.

이번 포스트에서는 terminal-notifier 설치부터 Claude Code Hooks 설정까지 단계별로 정리합니다.

Claude Code의 설치 방법과 기본 사용법은 Claude Code 기초 지식과 기본 사용법을 참고해 주세요.

왜 알림이 필요한가?

Claude Code로 코드 작성, 리팩토링, 테스트 작성 등의 작업을 맡기면 완료까지 수십 초에서 수 분이 걸릴 수 있습니다. 이 시간 동안 다른 작업을 하다가도 알림을 받으면 즉시 돌아올 수 있어, 대기 시간 없이 효율적으로 작업을 이어갈 수 있습니다.

특히 다음과 같은 상황에서 유용합니다.

Claude가 코드를 작성하는 동안 다른 문서 작업을 하고 있을 때
긴 리팩토링 작업을 맡겨놓고 브라우저에서 다른 일을 하고 있을 때
Claude가 권한 확인을 요청하는데 터미널을 보고 있지 않을 때

terminal-notifier 설치

terminal-notifier는 macOS에서 커맨드라인으로 데스크톱 알림을 보낼 수 있는 도구입니다. Homebrew로 간단히 설치할 수 있습니다.

brew install terminal-notifier

설치 확인

설치가 완료되면 아래 명령어로 확인합니다.

terminal-notifier -title '테스트' -message '알림이 정상 작동합니다' -sound default

macOS 화면 우측 상단에 알림이 표시되면 정상적으로 설치된 것입니다.

기본 사용법

terminal-notifier의 주요 옵션은 다음과 같습니다.

옵션	설명	예시
`-title`	알림 제목	`-title 'Claude Code'`
`-subtitle`	알림 부제	`-subtitle '작업 완료'`
`-message`	알림 본문	`-message '요청하신 작업이 완료되었습니다'`
`-sound`	알림 소리	`-sound default`
`-group`	알림 그룹 ID (같은 그룹은 대체됨)	`-group 'claude-code'`
`-open`	알림 클릭 시 열 URL	`-open 'https://...'`
`-appIcon`	알림 아이콘 이미지	`-appIcon '/path/to/icon.png'`

-group 옵션을 사용하면 같은 그룹의 이전 알림이 새 알림으로 대체되어, 알림 센터가 Claude 알림으로 도배되는 것을 방지할 수 있습니다.

Claude Code Hooks란?

Hooks는 Claude Code에서 특정 이벤트가 발생할 때 자동으로 실행되는 명령어입니다. settings.json에 설정하며, 다양한 이벤트에 셸 명령어를 연결할 수 있습니다.

알림에 활용할 수 있는 주요 Hook 이벤트는 다음과 같습니다.

이벤트	발생 시점	활용
Stop	Claude 응답 완료 시	작업 완료 알림
Notification	사용자 입력이 필요할 때	권한 요청, 입력 대기 알림

settings.json 파일 위치

Claude Code의 설정 파일은 용도에 따라 여러 위치에 존재합니다.

범위	파일 경로	적용 대상
사용자(글로벌)	`~/.claude/settings.json`	모든 프로젝트에 적용
프로젝트	`.claude/settings.json`	해당 프로젝트 내 모든 협업자
로컬	`.claude/settings.local.json`	본인만, 해당 프로젝트에서만

알림 설정은 개인 환경에 따라 다르므로 사용자(글로벌) 설정(~/.claude/settings.json)에 추가하는 것을 권장합니다.

Hook의 구조

Hook은 다음과 같은 구조로 설정합니다.

{
  "hooks": {
    "이벤트명": [
      {
        "matcher": "매칭 패턴",
        "hooks": [
          {
            "type": "command",
            "command": "실행할 셸 명령어"
          }
        ]
      }
    ]
  }
}

이벤트명: Hook이 실행될 이벤트 (Stop, Notification 등)
matcher: Hook이 실행될 조건을 필터링하는 패턴입니다. "*"으로 설정하면 모든 경우에 실행됩니다.
type: 실행 타입입니다. "command"는 셸 명령어를 실행합니다.
command: 실행할 셸 명령어입니다.

Stop Hook — 작업 완료 알림

Claude가 응답을 완료(작업이 끝남)했을 때 알림을 보내는 설정입니다.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle '작업 완료' -message '요청하신 작업이 완료되었습니다' -sound default -group 'claude-code'"
          }
        ]
      }
    ]
  }
}

이 설정을 적용하면 Claude에게 어떤 작업을 맡기든, 작업이 끝나는 순간 macOS 데스크톱 알림이 표시됩니다.

각 옵션 설명:

-title 'Claude Code': 알림 상단에 Claude Code라는 제목이 표시됩니다.
-subtitle '작업 완료': 제목 아래에 작업 완료라는 부제가 표시됩니다.
-message '요청하신 작업이 완료되었습니다': 알림 본문 메시지입니다.
-sound default: macOS 기본 알림 소리가 재생됩니다. 다른 작업에 집중하고 있어도 소리로 인지할 수 있습니다.
-group 'claude-code': 같은 그룹 ID의 알림을 하나로 묶습니다. 연속으로 여러 작업을 시키더라도 알림이 쌓이지 않고 최신 알림으로 대체됩니다.

Notification Hook — 입력 대기 알림

Claude가 사용자의 입력을 기다리고 있을 때(권한 요청, 질문 등) 알림을 보내는 설정입니다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle '입력 대기중' -message '권한 요청 또는 입력 대기 중입니다' -sound default -group 'claude-code'"
          }
        ]
      }
    ]
  }
}

Claude Code의 기본 모드(Edit 모드)에서는 파일 수정, 명령어 실행 등에 사용자의 권한 승인이 필요합니다. 이때 Notification Hook이 없으면 Claude가 권한 확인을 요청하며 멈춰있는 것을 모르고 계속 기다리게 될 수 있습니다.

이 설정을 적용하면 Claude가 입력을 기다리는 순간 바로 알림이 오므로, 빠르게 돌아와 승인하고 작업을 이어갈 수 있습니다.

전체 설정

Stop Hook과 Notification Hook을 합친 전체 ~/.claude/settings.json 설정입니다.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle '작업 완료' -message '요청하신 작업이 완료되었습니다' -sound default -group 'claude-code'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle '입력 대기중' -message '권한 요청 또는 입력 대기 중입니다' -sound default -group 'claude-code'"
          }
        ]
      }
    ]
  }
}