기준으로 공식 문서를 확인해 적었어요.
클로드 코드(Claude Code)가 작업을 마쳤거나 내 입력을 기다릴 때 알림을 받는 방법은 세 가지예요. 터미널의 기본 알림이나 벨을 켜는 것, ~/.claude/settings.json에 Notification 훅 한 줄을 넣어 macOS 알림이나 Windows 대화상자를 띄우는 것, 그리고 세션 상태를 화면에 보여 주는 데스크톱 앱을 쓰는 것이에요. 클로드코드 세션이 하나라면 훅 한 줄로 충분하고, 여러 개라면 어느 세션이 기다리는지 보여 주는 쪽이 편해요.
클로드 코드는 기본으로 어떤 알림을 보내나요?
클로드 코드는 작업을 마치거나 권한 요청에서 멈췄는데 내가 터미널을 보고 있지 않은 것 같으면 알림을 보내요. 다만 터미널마다 달라요(공식 문서, 2026년 11월 기준).
- Ghostty, Kitty, iTerm2: 데스크톱 알림이 와요. iTerm2는 알림 설정을 켜 둬야 보여요.
- Apple 터미널: 소리가 나지 않아요.
- 그 밖의 터미널: 기본으로는 아무것도 오지 않아요.
어느 터미널에서든 벨 문자를 보내게 하려면 ~/.claude/settings.json에 이 설정을 넣어요. 벨을 소리로 낼지는 쓰는 터미널의 설정이에요.
{
"preferredNotifChannel": "terminal_bell"
}
훅으로 작업 완료와 입력 대기 알림을 받으려면 어떻게 하나요?
~/.claude/settings.json에 Notification 훅을 넣으면 클로드 코드가 입력이나 승인을 기다릴 때 내가 정한 명령이 실행돼요. 공식 문서의 예시 그대로예요.
macOS (알림 센터에 알림을 띄워요)
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Windows (PowerShell로 대화상자를 띄워요)
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
}
]
}
]
}
}
알아 둘 점이 있어요.
matcher를 비우면 모든 알림에 실행돼요.permission_prompt로 두면 승인 요청이 약 6초 동안 답을 기다렸을 때,idle_prompt로 두면 응답을 마친 뒤 약 60초 동안 입력이 없을 때만 실행돼요.- macOS의
osascript알림은 스크립트 편집기 앱을 거쳐요. 알림이 안 보이면 터미널에서osascript -e 'display notification "test"'를 한 번 실행한 뒤, 시스템 설정 > 알림에서 스크립트 편집기의 알림을 허용하세요. - Windows 예시는 화면 구석의 알림이 아니라 대화상자라서 터미널 창 뒤에 열릴 수 있어요. WSL 안에서 쓴다면
powershell.exe가 PATH에 있어야 해요.
응답이 끝나는 순간마다 바로 알고 싶다면 Stop 이벤트에 같은 모양으로 넣어요. macOS에서 소리를 내는 예예요.
{
"hooks": {
"Stop": [
{
"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
}
]
}
}
훅은 기본 알림을 대신하지 않고 함께 실행돼요. 훅을 프로젝트 하나에만 쓰려면 그 프로젝트의 .claude/settings.json에 넣어요. 자세한 내용은 훅 가이드에 있어요.
코덱스와 제미나이 CLI도 알림을 받을 수 있나요?
네, 둘 다 자기 설정이 있어요(2026년 11월 기준).
- 코덱스(Codex):
~/.codex/config.toml의tui.notifications가 터미널 화면의 알림을 켜고,agent-turn-complete나approval-requested같은 이벤트로 좁힐 수 있어요.tui.notification_method는auto,osc9,bel가운데 하나예요. 바깥 프로그램을 실행하려면notify = ["python3", "/path/to/notify.py"]처럼 적는데, 지금 지원하는 이벤트는agent-turn-complete하나예요(Codex 설정 문서). - 제미나이 CLI(Gemini CLI): 설정의
general.enableNotifications(기본은 꺼짐)를 켜면 입력이 필요한 프롬프트와 세션 완료를 터미널 알림으로 알려 줘요.general.notificationMethod는auto,osc9,osc777,bell가운데 하나예요(Gemini CLI 설정 문서).
세 가지 방법 가운데 어떤 것이 맞나요?
| 방법 | Windows | macOS | 알려 주는 것 | 하지 않는 것 |
|---|---|---|---|---|
| 터미널 기본 알림·벨 | 기본 알림 없음, 벨은 설정으로 | Ghostty·Kitty·iTerm2는 데스크톱 알림 | 작업 완료, 권한 대기 | 그 밖의 터미널에서는 벨 설정이나 훅이 필요 |
| Notification·Stop 훅 | PowerShell 대화상자 | 알림 센터 알림, 소리 | 승인 대기, 입력 대기, 응답 끝 | 위 예시는 어느 세션인지 말해 주지 않음 |
| Devalley(데스크톱 앱) | 화면 아래를 걷는 주민 | 걷는 주민, 노치 | 세션마다 작업 중·나를 기다림·완료, 어느 프로젝트인지 | 소리와 시스템 알림, 휴대폰 알림 |
세션 하나를 돌리며 자리를 비운다면 훅 한 줄이면 충분해요. 소리나 알림 센터가 필요하면 훅이 맞아요.
여러 세션을 돌린다면 "누가" 기다리는지가 문제예요. Devalley는 세션마다 픽셀 주민 한 명이 화면 아래를 걸어 다니다가, 질문이나 승인 요청이 생기면 화면 가운데로 달려와 「?」나 「허락해 주세요」 말풍선을 띄우고 답할 때까지 뛰어요. 한 차례 일을 마치면 「완료!」 하고 기뻐해요. 주민 발밑에 이름과 프로젝트가 있어서 어느 세션인지 바로 보이고, Mac에서는 화면 위 노치 옆에도 나와요. 클로드 코드뿐 아니라 코덱스, 제미나이 CLI 세션도 주민이 돼요. Windows와 macOS에서 무료예요.
Devalley가 하지 않는 것도 분명해요. 에이전트의 상태를 소리나 운영체제의 알림 센터, 휴대폰으로 알리지는 않아요. 화면을 보고 있지 않을 때를 위해서는 위의 훅이나 기본 알림을 함께 쓰는 편이 좋아요.
자주 묻는 질문
클로드코드 알림 받기 설정은 어느 파일에 넣나요?
모든 프로젝트에 쓰려면 ~/.claude/settings.json, 프로젝트 하나에만 쓰려면 그 프로젝트의 .claude/settings.json에 넣어요.
윈도우에서 클로드 코드 작업 완료 알림을 받을 수 있나요?
네. 공식 문서의 PowerShell 예시를 Notification 훅에 넣으면 대화상자가 떠요. 화면 구석 알림이 아니라 대화상자여서 터미널 창 뒤에 열릴 수 있어요.
macOS에서 훅을 넣었는데 알림이 안 보이면 어떻게 하나요?
osascript 알림은 스크립트 편집기 앱을 거쳐요. 터미널에서 osascript -e 'display notification "test"'를 한 번 실행한 뒤 시스템 설정 > 알림에서 스크립트 편집기의 알림을 허용하세요.
코덱스 완료 알림은 어떻게 설정하나요?
~/.codex/config.toml의 tui.notifications를 켜거나, notify에 실행할 프로그램을 적어요. notify가 지금 지원하는 이벤트는 agent-turn-complete예요.
여러 세션 가운데 어느 세션이 기다리는지도 알 수 있나요?
공식 문서의 훅 예시는 같은 문구만 띄워요. 세션을 구분해 보려면 클로드 코드의 에이전트 뷰(claude agents)나, 세션마다 이름과 프로젝트가 붙은 주민으로 보여 주는 Devalley 같은 앱을 써요.