[Clacky](https://clacky.app/ko/)/가이드

# Claude Code나 Codex가 끝나면 알림 받는 방법

2026년 10월 22일 업데이트

Claude Code나 Codex에 긴 작업을 맡기고 다른 일을 하다가 10분 뒤에 돌아왔더니, 2분 만에 멈춰서 "예"를 기다리고 있었던 적 있죠. 에이전트가 **끝났을 때**나 **내 OK가 필요할 때** 소리나 알림이 오면 이 문제가 해결돼요.

두 도구 모두 내장 기능이나 한두 줄의 설정만으로 무료로 알림을 받을 수 있어요. 이 가이드에서 방법을 하나씩 차근차근 안내할게요.

핵심만 요약

-   **Claude Code**는 **Ghostty, Kitty, iTerm2**에서 이미 알림을 보낼 수 있어요(iTerm2는 설정 하나 필요). 다른 터미널에서는 **훅**을 추가하세요.
-   Claude Code의 **Stop** 훅은 작업이 끝나면, **Notification** 훅은 내가 필요할 때 실행돼요. 소리는 `afplay`, 알림은 `osascript`를 실행하게 하면 돼요.
-   **Codex**: `~/.codex/config.toml`에 `notify` 줄을 추가하거나, 내장 터미널 알림을 켜세요.
-   아무 일도 안 일어나나요? **세션을 다시 시작하세요**. 훅은 세션이 시작될 때 읽혀요.

이 페이지 내용

1.  [에이전트가 끝났다고 알려 주는 원리](#에이전트가-끝났다고-알려-주는-원리)
2.  [Claude Code: 내장 알림](#claude-code-내장-알림)
3.  [Claude Code: 소리를 내는 훅](#claude-code-소리를-내는-훅)
4.  [Codex: notify 설정](#codex-notify-설정)
5.  [아무 일도 안 일어난다면](#아무-일도-안-일어난다면)

## 에이전트가 끝났다고 알려 주는 원리

Claude Code 또는 Codex끝났거나, 내가 필요할 때

훅 / notify내 명령을 실행

소리로 알아요소리 · 배너 · 벨

이 페이지의 모든 방법은 똑같이 작동해요: 에이전트가 딱 맞는 순간에 명령을 실행하는 거예요.

두 도구 모두 정해진 순간에 내 명령을 실행할 수 있어요. 알림이란 결국 그게 전부예요. Claude Code는 이걸 **훅**, Codex는 **notify**라고 불러요. 그 명령이 하는 일(소리 재생, 배너 표시, 화면 깜빡임)은 에이전트가 멈추거나 입력을 요청할 때 일어나요.

에이전트가 일하는 동안 더 기분 좋은 Mac

Clacky는 에이전트가 일하는 동안 Mac 자체를 더 기분 좋게 만들어 줘요. 클릭·키보드 사운드, 그리고 에이전트가 만든 걸 보여 주고 싶을 때 쓰는 화면 녹화까지. 한 번 $4.99, Mac 1대용.

## Claude Code: 내장 알림

Claude Code는 작업이 끝나거나 권한 확인을 기다릴 때 스스로 데스크톱 알림을 보낼 수 있어요. Anthropic 문서에 따르면 **Ghostty**와 **Kitty**에서는 바로 작동해요. **iTerm2**에서는 한 번만 켜 주세요.

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

**tmux** 안에서 Claude Code를 쓰나요? `~/.tmux.conf`에 `set -g allow-passthrough on`을 추가하세요. 안 그러면 알림이 터미널까지 오지 않아요. Claude Code가 알려 주는 방식(예: 터미널 벨)은 `/config` 설정에서도 고를 수 있어요.

출처: [Claude Code 문서: 터미널 설정](https://code.claude.com/docs/en/terminal-config)

## Claude Code: 소리를 내는 훅

Apple의 터미널, VS Code 등 다른 터미널에서는 훅을 쓰면 돼요. 훅은 `~/.claude/settings.json`(모든 프로젝트) 또는 `.claude/settings.json`(한 프로젝트)에 들어가요. 중요한 이벤트는 두 가지예요.

-   **Stop**: Claude가 답변을 끝냈어요.
-   **Notification**: Claude가 나를 필요로 해요(권한 확인, 또는 입력을 기다리는 중).

아래 설정은 두 경우 모두 macOS 사운드를 재생해요. 설정 파일에 합쳐 넣으세요(이미 있는 내용은 그대로 두고요).

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

배너가 더 좋다면 이 명령을 대신 쓰세요(Anthropic 예시와 같아요).

```
osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'
```

Claude Code에서 `/hooks`를 입력하면 설정된 훅을 볼 수 있어요. 새 훅은 저장한 뒤 시작한 세션부터 적용돼요. `/System/Library/Sounds/`의 사운드는 무료로 써도 돼요: Glass, Ping, Pop, Purr, Submarine 등.

출처: [훅 레퍼런스](https://code.claude.com/docs/en/hooks) · [훅 가이드](https://code.claude.com/docs/en/hooks-guide)

## Codex: notify 설정

Codex CLI는 매 턴이 끝날 때마다 내 프로그램을 실행해요. `~/.codex/config.toml`의 `notify`로 설정하죠. Codex는 턴 정보를 담은 JSON을 마지막 인자로 넘기는데(`type`은 `agent-turn-complete`), 단순한 소리 명령이라면 무시해도 돼요.

```
notify = ["sh", "-c", "afplay /System/Library/Sounds/Glass.aiff"]
```

`notify`는 최상위 키라서 파일의 어떤 `[section]`보다도 위에 넣어야 해요. Codex에는 터미널 UI에 내장된 알림(`[tui]` 아래 `notifications`)도 있는데, 터미널 자체 알림이나 벨을 써요. 배너가 보일지는 터미널에 따라 달라요.

Codex의 `notify`는 턴이 끝날 때 실행돼요. Claude Code의 Notification 훅처럼 “승인이 필요해요” 이벤트가 따로 있지는 않아요.

출처: [Codex 문서: 고급 설정](https://developers.openai.com/codex/config-advanced)

## 아무 일도 안 일어난다면

-   **세션을 다시 시작하세요.** 훅은 세션이 시작될 때 읽히기 때문에, 이미 돌고 있던 세션은 알림을 보내지 않아요.
-   **파일이 제대로 읽히는지 확인하세요.** `settings.json`에 쉼표 하나만 빠져도 모든 훅이 멈춰요. 아무 JSON 검사기에 붙여 넣어 보세요.
-   **명령만 따로 테스트하세요.** 터미널에서 `afplay /System/Library/Sounds/Glass.aiff`를 실행해 보세요. 소리가 안 나나요? 출력 기기와 볼륨을 확인하세요.
-   **배너가 안 뜨나요?** 시스템 설정 → **알림**에서 터미널(`osascript`라면 스크립트 편집기)을 확인하고, 집중 모드도 확인하세요.
-   **소리가 두 번 나나요?** 설정이 두 개 있는 거예요(예: `~/.claude/settings.json`의 훅과 프로젝트의 `.claude/settings.json`에 있는 또 다른 훅). 하나만 남기세요.

## 자주 묻는 질문

### Claude Code에 내장 알림 소리가 있나요?

Ghostty, Kitty, iTerm2에서는 스스로 데스크톱 알림을 보낼 수 있어요(iTerm2는 **Send escape sequence-generated alerts**를 켜야 해요). 어떤 터미널에서든 소리를 내려면 `afplay`를 실행하는 **Stop** 또는 **Notification** 훅을 추가하세요.

### Stop 훅과 Notification 훅은 뭐가 다른가요?

**Stop**은 Claude가 답변을 끝냈을 때 실행돼요. **Notification**은 Claude가 나를 필요로 할 때 실행돼요: 권한 확인이거나 입력을 기다리고 있을 때요. 대부분 둘 다, 서로 다른 소리로 쓰고 싶어 해요.

### Codex가 승인이 필요할 때 알려 줄 수 있나요?

Codex의 `notify` 프로그램은 턴이 끝날 때(`agent-turn-complete`) 실행돼요. 지금은 승인용 이벤트가 따로 없어서, 턴이 끝날 때 소리가 나요.

## 다른 가이드

-   [덮개 닫고 Mac 깨워 두기클램셸 모드, caffeinate, pmset, 앱: 각각 실제로 뭘 하는지 알려 드려요.](https://clacky.app/ko/keep-mac-awake-lid-closed/)
-   [Mac 키보드·클릭 소리작동 원리, 필요한 권한, 앱, 해결법.](https://clacky.app/ko/mac-keyboard-sounds/)
-   [Mac에서 클릭 보여 주기기본 옵션, 편집 앱, 소리 나는 실시간 물결.](https://clacky.app/ko/show-mouse-clicks-mac/)
-   [Mac 클릭 소리기본 설정은 없어요: 소리를 더하는 법과 필요한 권한.](https://clacky.app/ko/mac-click-sound/)
-   [최고의 키보드 소리 앱무료와 유료 앱 17개를 나란히, 그리고 나한테 맞는 앱.](https://clacky.app/ko/best-keyboard-sound-apps-mac/)
-   [집중을 위한 키보드 소리공부, 글쓰기, 코딩을 위한 부드러운 타자 소리를 헤드폰으로.](https://clacky.app/ko/keyboard-sounds-for-focus/)
-   [키보드 소리 용어 정리도각, 크리미, 클랙, 팝이 무슨 뜻이고 각각 어떻게 들리는지.](https://clacky.app/ko/keyboard-sounds-explained/)
-   [포근한 Mac 앱일하는 동안 켜 두는 방치형 게임, 앰비언트 사운드, 펫, 부드러운 클릭.](https://clacky.app/ko/cozy-mac-apps/)
-   [최고의 커서 강조 앱시연, 통화, 녹화를 위한 스포트라이트, 클릭 물결, 클릭 소리.](https://clacky.app/ko/best-cursor-highlighter-apps-mac/)
-   [키보드 소리가 안 나요입력 모니터링, 보안 입력, 출력 장치, 조용히 설정.](https://clacky.app/ko/keyboard-sounds-not-working-mac/)
-   [Mac 텔레프롬프터카메라 아래에서 대본을 읽고, 녹화에는 안 나오게 해요.](https://clacky.app/ko/teleprompter-mac/)
-   [클릭 보여 주고 클릭 소리 녹음하기Mac 화면 녹화에 클릭 리플과 클릭 소리를 넣는 방법이에요.](https://clacky.app/record-click-sound/)
-   [키보드 소리와 함께하는 타자 테스트소리가 들리는 30초 타자 테스트, 브라우저에서 바로 해 보세요.](https://clacky.app/ko/typing-test/)

Clacky가 처음이세요? 클릭·키보드 사운드, 화면 녹화, 스크린샷, 그리고 작업하는 동안 자라는 작은 항구 마을을 담은 아늑한 Mac 메뉴 막대 앱이에요. [모든 도구 보기](https://clacky.app/ko/) · [브라우저에서 소리 들어 보기](https://clacky.app/ko/)

2026년 10월 22일에 확인했어요. 바뀐 내용이나 틀린 부분이 있나요? hello@clacky.app으로 메일 주세요.
