Claude Code 기본 알림: 터미널 벨과 preferredNotifChannel

01빠른 해결법

Claude가 작업을 마쳐도 아무 소리가 안 난다면 ~/.claude/settings.json에 다음을 추가하세요:

{
  "preferredNotifChannel": "terminal_bell"
}

그런 다음 터미널이 벨에 반응하도록 설정돼 있는지 확인하세요. 소리 재생, Dock 아이콘 튕기기, 탭 깜빡임, 알림 표시 같은 것들이요. 이 설정은 Claude Code가 아니라 터미널에 있어요. Mac, Windows, Linux의 대부분 터미널은 환경설정에 "bell"이나 "alert" 항목이 있어요.

02preferredNotifChannel 값 전체

이 설정은 어느 설정 파일에나 넣을 수 있어요. 사용자(~/.claude/settings.json), 프로젝트(.claude/settings.json), 로컬(.claude/settings.local.json) 모두 가능해요. 이전 버전에서는 ~/.claude.json에 저장했는데, 거기 남아 있는 값도 Claude Code가 여전히 읽어요.

03기본 알림이 울리는 시점

Anthropic 문서에 따르면 기본 알림은 Notification hook과 같은 타이밍에 울려요. 터미널 세션에서는:

• 권한 prompt: 키 입력 없이 prompt가 약 6초 동안 대기한 뒤에 울려요. 키를 누를 때마다 대기 시간이 다시 시작돼요.
• 작업 완료: Claude가 멈추고 약 60초 뒤에 울려요. 그동안 입력이 없고 실행 중인 백그라운드 에이전트도 없을 때만요.

즉, 기본 "완료" 알림은 일부러 즉시 울리지 않아요. 화면을 보고 있을 때 알리는 게 아니라 자리를 비웠을 때 알려주도록 설계됐거든요. 턴이 끝나는 즉시 알림을 받고 싶다면 대신 Stop hook을 사용하세요(Stop hook 가이드 참고).

04터미널별 설정

iTerm2 (macOS)

iTerm2는 기본적으로 데스크톱 알림을 받지만, iTerm2에서 허용해야 표시돼요:

1. Settings > Profiles > Terminal을 여세요.
2. Notification Center Alerts를 체크하세요.
3. Filter Alerts를 클릭하고 Send escape sequence-generated alerts를 켜세요.

System Settings > Notifications에서 iTerm2의 알림이 허용돼 있는지도 확인하세요.

Apple Terminal (macOS)

Apple Terminal은 데스크톱 알림을 받지 않아요. "auto"일 때 Claude Code는 맨 앞 창 프로필에서 Audible bell이 꺼져 있을 때만 무음 벨을 보내요. 이 벨은 프로필의 Visual bell이나 Dock 튕기기 옵션이 켜져 있으면 창 깜빡임으로, Terminal이 백그라운드에 있을 때는 Dock 튕기기로 표시돼요.

한 가지 주의할 점이 있어요. Claude Code를 처음 실행할 때 나오는 터미널 설정 prompt를 수락했다면 /terminal-setup이 실행되면서 Apple Terminal 프로필의 소리 벨이 꺼졌을 거예요. 소리를 들으려면 "terminal_bell"로 설정하고 Settings > Profiles > Advanced에서 Audible bell을 다시 켜세요.

Ghostty와 Kitty (macOS 및 Linux)

둘 다 별도 설정 없이 데스크톱 알림을 받고, 운영체제 알림 센터로 전달해줘요.

그 밖의 터미널

Windows Terminal, GNOME Terminal, Konsole, Alacritty, WezTerm, Warp, IDE 터미널은 기본적으로 아무 알림도 받지 못해요. "terminal_bell"을 설정하고 터미널 자체의 벨 처리를 켜거나, hook을 사용하세요. IDE 터미널은 따로 주의할 점이 있는데, VS Code, Cursor, JetBrains 가이드에서 다뤄요.

05SSH 환경과 tmux 안에서

데스크톱 알림은 내 컴퓨터의 터미널이 해석하는 이스케이프 시퀀스라서, Claude Code를 SSH로 원격 서버에서 실행해도 알림이 도착해요. Ghostty와 Kitty는 별도 설정 없이 전달해요. iTerm2는 위의 알림 설정이 필요해요.

tmux 안에서는 passthrough를 허용하지 않으면 시퀀스가 무시돼요. ~/.tmux.conf에 다음을 추가하고 tmux source-file ~/.tmux.conf를 실행하세요:

set -g allow-passthrough on

분리된(detached) 세션은 별개의 문제예요. 연결된 터미널이 없으면 알림을 표시할 곳이 없거든요. tmux 가이드와 SSH 환경 알림을 참고하세요.

06기본 알림과 hook 함께 쓰기

Notification hook은 기본 알림을 대체하지 않고 함께 실행돼요. Anthropic 문서에도 "notifications_disabled" 상태에서도 hook이 실행된다고 명시되어 있어요. 이 설정은 Claude Code가 알림을 보내는 방식만 바꿀 뿐, hook 실행 여부에는 영향을 주지 않아요. 그래서 역할을 깔끔하게 나눌 수 있어요:

• 자리에 있을 때 받을 알림은 "auto"나 "terminal_bell"로 두세요.
• 시스템 사운드, 알림을 받지 못하는 터미널에서의 데스크톱 알림, ntfy를 이용한 휴대폰 push 같은 나머지는 hook으로 추가하세요.
• hook에서 이미 데스크톱 알림을 띄운다면, 알림이 두 번 뜨지 않도록 "notifications_disabled"로 설정하세요.

예를 들어, 다음 설정은 어떤 터미널에서든 Claude가 확인을 필요로 할 때 macOS에서 소리를 재생해요:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

Linux와 Windows용 설정은 Linux 가이드와 Windows 가이드에 있어요.

07기본 옵션의 한계

• 컴퓨터 앞에서만 알 수 있어요. 벨이나 알림은 화면 속 터미널에서 나와요. 잠깐 부엌에 가면 놓치게 돼요.
• 터미널에 따라 달라요. 많이 쓰는 터미널 상당수는 설정을 바꾸기 전까지 아무 알림도 받지 못해요.
• 알림에 바로 응답할 수 없어요. Claude가 기다리고 있다는 것만 알려줄 뿐, 결국 키보드 앞으로 돌아와야 해요.

휴대폰으로 push를 받는 공식 방법은 Anthropic의 Remote Control과 Claude 모바일 앱이에요. 비교 가이드에서 다른 옵션과 함께 다뤄요.

08Claude Code Notifier의 역할

주로 자리에서 작업한다면 기본 알림과 "terminal_bell"만으로 충분할 수 있어요. Claude Code Notifier는 자리를 비웠을 때를 위한 도구예요. 커맨드라인 도구인 ccn이 Claude Code hook으로 실행되기 때문에, 벨 설정과 상관없이 Mac, Windows, Linux의 어떤 터미널에서든 동작해요. 단독으로 쓰면 Claude가 작업을 마치거나, 권한이 필요하거나, 질문할 때 데스크톱 알림을 띄워요. 휴대폰을 페어링하면 휴대폰에서 권한을 허용하거나 거부하고, Claude의 질문에 답하고, 다음 지시를 보낼 수 있어요. 최근 30초 안에 입력한 적이 있다면 휴대폰으로는 아무것도 보내지 않아요. ccn 페이지를 참고하세요.

09FAQ