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 알림을 끄려면 어떻게 하나요?

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

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

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" 로 두면 터미널 벨이 울립니다.

{
  "preferredNotifChannel": "terminal_bell"
}

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

Notification 훅으로 직접 알림

훅은 Claude Code 가 정해진 시점에 실행하는 셸 명령입니다. Notification 이벤트는 Claude Code 가 알림을 보낼 때, Stop 이벤트는 Claude 가 응답을 마칠 때 실행됩니다. 공식 문서의 macOS 예시는 ~/.claude/settings.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 에 다음 줄을 넣으라고 안내합니다.

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 사이드바입니다.

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 로 붙으면 알림이 지나가지 못합니다.

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

호출판

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

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

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

알림이 뜨지 않을 때 확인할 항목은 문제 해결 문서에 정리되어 있습니다.