# Claude Code 입력 대기·작업 완료 알림 받는 방법

Claude Code 가 승인을 기다리거나 작업을 끝냈을 때 macOS 알림을 받는 방법입니다. 기본 알림, Notification 훅, tmux 설정, hivemux 알림과 호출판을 순서대로 설명합니다.

Source: https://hivemux.dev/ko/guides/claude-code-notifications/

> Claude Code 는 작업을 끝내거나 권한 확인에서 멈추면 알림 이벤트를 보내고, Ghostty·Kitty·iTerm2 에서는 기본으로 데스크톱 알림을 띄웁니다. 다른 터미널에서는 ~/.claude/settings.json 에 Notification 훅을 넣어 원하는 명령을 실행할 수 있고, tmux 안에서는 allow-passthrough 를 켜야 알림이 바깥 터미널까지 갑니다. hivemux 는 tmux 안의 모든 세션에 대해 입력 대기와 완료를 macOS 알림과 상태줄 호출판으로 알려 줍니다.

Claude Code 에 긴 작업을 맡기고 다른 창에서 일하다 보면, 파일 수정 승인을 기다리며 멈춰 있는 세션을 한참 뒤에야 발견하게 됩니다. 알림을 제대로 설정해 두면 이런 대기 시간을 줄일 수 있습니다. 아래 내용 중 Claude Code 자체 기능은 Anthropic 공식 문서(code.claude.com)에 나온 내용만 옮겼습니다.

## Claude Code 기본 알림

Claude Code 는 작업을 끝내거나 권한 확인에서 멈췄을 때, 사용자가 터미널을 떠나 있는 것으로 보이면 알림 이벤트를 보냅니다. 공식 문서에 따르면 기본으로 데스크톱 알림을 띄우는 터미널은 Ghostty, Kitty, iTerm2 입니다. iTerm2 는 Settings → Profiles → Terminal 에서 "Notification Center Alerts" 를 켜고, "Filter Alerts" 에서 "Send escape sequence-generated alerts" 를 허용해야 합니다.

그 밖의 터미널에서는 `preferredNotifChannel` 을 `"terminal_bell"` 로 두면 터미널 벨이 울립니다.

```json
{
  "preferredNotifChannel": "terminal_bell"
}
```

알림이 오지 않으면 macOS 시스템 설정 → 알림에서 쓰는 터미널 앱이 허용되어 있는지 먼저 확인하세요.

## Notification 훅으로 직접 알림

훅은 Claude Code 가 정해진 시점에 실행하는 셸 명령입니다. `Notification` 이벤트는 Claude Code 가 알림을 보낼 때, `Stop` 이벤트는 Claude 가 응답을 마칠 때 실행됩니다. 공식 문서의 macOS 예시는 `~/.claude/settings.json` 에 다음 블록을 넣는 방식입니다.

```json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}
```

`osascript` 알림은 스크립트 편집기(Script Editor) 앱을 거쳐 표시됩니다. 스크립트 편집기에 알림 권한이 없으면 아무것도 뜨지 않으므로, 터미널에서 `osascript -e 'display notification "test"'` 를 한 번 실행한 뒤 시스템 설정 → 알림에서 스크립트 편집기를 허용하세요. 훅은 기본 알림을 대신하지 않고 함께 실행됩니다.

## tmux 안에서 알림이 오지 않을 때

Claude Code 를 tmux 안에서 실행하면 기본 설정으로는 데스크톱 알림이 바깥 터미널에 닿지 않습니다. 공식 문서는 `~/.tmux.conf` 에 다음 줄을 넣으라고 안내합니다.

```sh
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
```

넣은 뒤에는 `tmux source-file ~/.tmux.conf` 로 실행 중인 서버에 적용합니다. 뒤의 두 줄은 tmux 안에서 Shift+Enter 줄바꿈이 되게 하는 설정입니다.

## hivemux 알림

여기까지 설정하면 세션별 알림은 받을 수 있지만, 세션이 여러 개일 때 알림을 놓치면 어느 세션이 기다리는지 다시 찾아야 합니다. hivemux 는 모든 Claude Code 세션을 실행 중·입력 대기·완료 상태로 보여 주고, 나를 기다리는 세션으로 바로 이동하게 해 주는 tmux 사이드바입니다.

```sh
curl -fsSL https://hivemux.dev/install.sh | bash
```

hivemux 는 Claude Code 훅으로 각 tmux 칸의 상태를 기록하고, 사이드바가 그 값을 1초마다 읽습니다. 작업이 입력을 기다리기 시작하거나 끝나면 사이드바가 터미널 알림 신호(OSC 777)를 tmux 를 거쳐 보내고, Ghostty 처럼 이 신호를 지원하는 터미널에서 macOS 알림이 뜹니다. 동작 방식은 다음과 같습니다.

- 지금 보고 있는 작업(화면에 보이고 터미널에 초점이 있는 창)은 알리지 않습니다.
- 사이드바 오른쪽 클릭 메뉴 → 설정에서 알림을 켜고 끌 수 있습니다.
- 알림은 사이드바가 보내므로, `prefix` 다음 `b` 로 사이드바를 숨기면 알림도 오지 않습니다.
- `hivemux connect` 로 다른 Mac 에 ssh 로 붙어 있으면 원격 작업의 알림도 이 Mac 에 뜹니다. mosh 로 붙으면 알림이 지나가지 못합니다.

[Image: hivemux 설정 창의 언어, 애니메이션, 알림, 사이드바 폭 항목]

## 호출판

알림은 잠깐 떴다 사라지지만, 호출판은 처리할 때까지 남아 있습니다. tmux 맨 위 상태줄 오른쪽에 푸드코트 주문 알림판처럼 동그란 번호 배지가 뜹니다.

- 호박색 배지: 입력이 필요한 작업입니다. 답할 때까지 깜빡입니다.
- 초록 배지: 끝났지만 아직 안 본 작업입니다. 처음 10초 동안 깜빡이고, 한 번 보면 사라집니다.

배지 안의 숫자는 그 작업의 `Option` 번호입니다. 배지를 클릭하거나 `Option+3` 처럼 그 번호를 누르면 해당 작업으로 이동하고, `Option+0` 은 가장 오래 기다린 작업으로 갑니다. 다른 프로젝트의 작업도 함께 뜨므로, 지금 어느 프로젝트를 보고 있든 기다리는 작업을 놓치지 않습니다.

알림이 뜨지 않을 때 확인할 항목은 [문제 해결 문서](/ko/docs/troubleshooting/)에 정리되어 있습니다.

## FAQ

### tmux 안에서 Claude Code 알림이 오지 않는 이유는 무엇인가요?

tmux 가 터미널 알림 신호를 바깥 터미널로 넘기지 않기 때문입니다. ~/.tmux.conf 에 set -g allow-passthrough on 을 넣고 tmux source-file ~/.tmux.conf 로 다시 읽으면 됩니다. hivemux 는 설치할 때 allow-passthrough 를 켜 둡니다.

### 폰으로도 Claude Code 알림을 받을 수 있나요?

Remote Control 이 켜진 세션이라면 /config 에서 Push when actions required 나 Push when Claude decides 를 켜면 Claude 앱으로 푸시가 옵니다. Pro, Max, Team, Enterprise 구독 로그인이 필요하고 API 키로는 쓸 수 없습니다.

### hivemux 알림이 지금 보고 있는 세션에서는 뜨지 않습니다.

의도한 동작입니다. 화면에 보이고 터미널에 초점이 있는 작업은 알리지 않습니다. 터미널을 뒤로 보내거나 다른 창에 있을 때만 알림이 뜹니다.

### hivemux 알림을 끄려면 어떻게 하나요?

사이드바 오른쪽 클릭 메뉴 → 설정에서 알림을 끄기로 바꾸면 됩니다. 설정은 저장되어 재시작 뒤에도 유지됩니다.